SiCore TokenWorks

مستندات API

راهنمای اتصال دقیق و مرجع API، برای ادغام سریع شما با سرویس API هوش مصنوعی SiCore TokenWorks

1شروع سریع

استفاده از API SiCore TokenWorks فقط سه مرحله ساده دارد:

  1. ثبت‌نام حساب SiCore TokenWorks و ورود به کنسول
  2. ایجاد API Key در کنسول
  3. با API Key خود با رابط‌های ما تماس بگیرید

Tip: کاربران جدید پس از ثبت‌نام، سهمیه آزمایشی رایگان دریافت می‌کنند و بدون نیاز به اتصال کارت اعتباری می‌توانند شروع به استفاده کنند.

2آدرس پایه

آدرس پایه API به شرح زیر است، همه درخواست‌ها از پروتکل HTTPS استفاده می‌کنند:

text
https://www.token8341.com/v1

رابط تکمیل گفتگو:

text
POST https://www.token8341.com/v1/chat/completions

Note: این رابط کاملاً با فرمت رابط Chat Completions شرکت OpenAI سازگار است، می‌توانید مستقیماً از SDK شرکت OpenAI برای فراخوانی استفاده کنید.

3روش احراز هویت

SiCore TokenWorks از Bearer Token برای احراز هویت API استفاده می‌کند. لطفاً API Key خود را در هدر درخواست قرار دهید:

text
Authorization: Bearer sk-your-api-key-here

می‌توانید کلیدهای خود را در صفحه «API Keys» کنسول ایجاد و مدیریت کنید. لطفاً API Key خود را به‌طور ایمن نگهداری کنید و آن را در مخازن کد عمومی یا کد سمت کلاینت افشا نکنید.

4لیست مدل‌های پشتیبانی‌شده

شناسه مدلنام مدلتأمین‌کننده
gpt-4oGPT-4oOpenAI
gpt-4o-miniGPT-4o MiniOpenAI
claude-3-5-sonnetClaude 3.5 SonnetAnthropic
claude-4-sonnetClaude 4 SonnetAnthropic
gemini-2-0-proGemini 2.0 ProGoogle
deepseek-v4-proDeepSeek-V4-ProDeepSeek
qwen-maxQwen-MaxAlibaba Cloud

مدل‌های بیشتری به‌طور مداوم در حال اضافه شدن هستند، لطفاً اطلاعیه‌های به‌روزرسانی ما را دنبال کنید.

5کد نمونه

curl

bash
curl https://www.token8341.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Python (openai SDK)

python
from openai import OpenAI

client = OpenAI(
    base_url="https://www.token8341.com/v1",
    api_key="sk-your-api-key-here"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

Node.js (openai SDK)

javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://www.token8341.com/v1",
  apiKey: "sk-your-api-key-here",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "Hello!" },
  ],
});

console.log(response.choices[0].message.content);

6توضیح کدهای خطا

هنگام شکست درخواست API، کد وضعیت HTTP و پیام خطای مربوطه بازگردانده می‌شود، فرمت به شرح زیر است:

json
{
  "error": {
    "message": "Insufficient balance",
    "type": "insufficient_balance",
    "code": 402
  }
}
کد وضعیتنامتوضیحات
400Bad Request请求参数错误,请检查请求体格式
401UnauthorizedAPI Key 无效或缺失,请检查 Authorization 请求头
402Insufficient Balance账户余额不足,请充值后重试
404Not Found请求的模型或接口不存在
429Rate Limit请求频率过高,请稍后重试
500Internal Server Error服务内部错误,请联系技术支持
503Service Unavailable模型服务暂时不可用,请稍后重试

پرسش‌های متداول اتصال

پرسش‌های متداول درباره API Key، تغییر مدل و زبان‌های اتصال

آیا یک API Key می‌تواند همه مدل‌ها را فراخوانی کند؟

بله. این ویژگی اصلی SiCore TokenWorks است — توسعه‌دهنده فقط یک‌بار متصل می‌شود و می‌تواند همه مدل‌های موجود در پلتفرم را فراخوانی کند، بدون نیاز به ثبت‌نام جداگانه و مدیریت Key برای هر ارائه‌دهنده.

آیا تغییر مدل نیاز به تغییر کد دارد؟

نیازی به تغییر کد منطقی نیست؛ فقط با تغییر پارامتر model ID می‌توان بین مدل‌های داخلی و خارجی جابه‌جا شد.

از چه زبان‌های برنامه‌نویسی پشتیبانی می‌شود؟

نمونه‌های اتصال اصلی مانند cURL، Python و Node.js ارائه شده است و با هر زبانی که از درخواست HTTP پشتیبانی کند و همچنین OpenAI SDK رسمی سازگار است.

احراز هویت API چگونه انجام می‌شود؟

روش احراز هویت Bearer Token است و کافی است API Key را در هدر درخواست قرار دهید؛ اینترفیس کاملاً با فرمت Chat Completions در OpenAI سازگار است و می‌توانید مستقیماً با SDK رسمی OpenAI فراخوانی کنید، بدون نیاز به سازگارسازی اضافی.

آیا SDK یا نمونه کد آماده‌ای وجود دارد؟

بله. پلتفرم نمونه‌های اتصال اصلی مانند cURL، Python و Node.js را ارائه می‌دهد و توسعه‌دهندگان می‌توانند بر اساس زبان خود انتخاب کنند و به‌سرعت یکپارچه‌سازی کنند.

آیا مدل‌ها به‌طور مستمر اضافه می‌شوند؟ آیا برای مدل‌های جدید باید کد را تغییر داد؟

بله. پلتفرم به‌طور مستمر مدل‌های جدید داخلی و بین‌المللی را یکپارچه می‌کند، روش اتصال و سیستم صورتحساب یکسان باقی می‌ماند و پس از عرضه مدل جدید می‌توان بدون تغییر کد مستقیماً آن را انتخاب کرد.

مکانیزم کش API مدل‌های بزرگ چگونه استفاده می‌شود؟ در چه سناریوهایی می‌تواند hit شود؟

پلتفرم از کش اشتراکی prompt یکسان میان کاربران استفاده می‌کند؛ پس از hit، قیمت بیش از ۹۰٪ دیگر کاهش می‌یابد و کمترین قیمت hit کش ¥0.010 به ازای هر میلیون Token است و بخش hit شده بر اساس قیمت کش محاسبه می‌شود. مناسب سناریوهایی است که چند کاربر از prompt پیشوند یکسان به‌صورت مکرر استفاده می‌کنند، مانند system prompt ثابت، پیشوند دانش عمومی و غیره — بخش ثابت را در ابتدا قرار دهید تا نرخ hit بالاتر باشد.

در صورت شکست یا timeout فراخوانی API، چگونه retry خودکار و degradation انجام دهیم؟

روش معمول این است: برای timeout و خطاهای قابل retry از retry با backoff نمایی استفاده کنید و حداکثر تعداد retry را تعیین کنید؛ اگر همچنان شکست خورد، به مدل پشتیبان degradation کنید. برای تغییر مدل در پلتفرم فقط کافی است ID مدل را تغییر دهید، بدون هیچ تغییری در کد؛ کافی است هدف degradation را به‌عنوان ID مدل دیگری بنویسید. در سمت پلتفرم نیز افزونگی چندگرهی و مسیریابی هوشمند بین‌منطقه‌ای وجود دارد و خرابی یک گره به‌صورت خودکار سوئیچ می‌شود.

چگونه اثر و هزینه مدل‌های مختلف را مقایسه کنیم؟

با یک API Key می‌توان همه مدل‌ها را فراخوانی کرد؛ برای تغییر مدل فقط ID مدل را تغییر دهید، بدون هیچ تغییری در کد، و برای مقایسه افقی نیازی به اتصال جداگانه برای هر مدل نیست. توصیه می‌شود با همان دسته نمونه‌های کسب‌وکار به‌صورت جداگانه فراخوانی کنید، کیفیت خروجی و میزان مصرف را ثبت کنید، سپس با «جدول مقایسه قیمت همه مدل‌ها» در وب‌سایت رسمی، قیمت رسمی و قیمت این سایت را مورد به مورد مقایسه کنید.

API Key سمت سرور چگونه به‌صورت امن نگهداری شود؟

توصیه می‌شود API Key را فقط در سمت سرور نگهداری کنید و آن را از طریق هدر درخواست به‌صورت Bearer Token ارسال کنید؛ آن را در کد frontend یا client ننویسید. داده‌های درخواست و پاسخ پلتفرم در تمام مسیر با HTTPS رمزنگاری و منتقل می‌شوند و مدیریت دسترسی سطح سازمانی و لاگ حسابرسی ارائه می‌شود؛ سوابق فراخوانی قابل ردیابی است.

در سناریوهای همزمانی بالا چگونه پایداری فراخوانی و تأخیر پایین تضمین می‌شود؟

پلتفرم بر مراکز توان محاسباتی در مناطقی مانند هولینگر مغولستان داخلی، هامی سین‌کیانگ و ژونگ‌وِی نینگ‌شیا تکیه دارد و از طریق الگوریتم زمان‌بندی خودتوسعه‌یافته، مسیریابی هوشمند بین‌منطقه‌ای و توازن بار پویا انجام می‌دهد؛ خرابی یک گره به‌صورت خودکار سوئیچ می‌شود؛ کاربران شهرهای اصلی می‌توانند تأخیر در حد میلی‌ثانیه دریافت کنند و تعهد دسترس‌پذیری سرویس 99.9% است. توصیه می‌شود در سمت client نیز retry با backoff و degradation چندمدلی را ترکیب کنید.

چگونه میزان فراخوانی، هزینه و خطاها را پایش کنیم؟

پلتفرم حساب یکپارچه و یک سیستم صورتحساب واحد ارائه می‌دهد؛ میزان مصرف شفاف است، موجودی به‌صورت لحظه‌ای واریز می‌شود و جزئیات مصرف در هر زمان قابل مشاهده است؛ همچنین قابلیت لاگ حسابرسی فراخوانی API ارائه می‌شود و سوابق فراخوانی قابل ردیابی است. کاربران سازمانی در صورت نیاز به الزامات انطباق سخت‌گیرانه‌تر (مدیریت دسترسی، لاگ حسابرسی و غیره) می‌توانند برای هماهنگی تجاری با پشتیبانی تماس بگیرند.