SiCore TokenWorks

توثيق API

دليل اندماج مفصل ومرجع API لمساعدتك على دمج خدمة SiCore TokenWorks AI API بسرعة

1بدء سريع

استخدام SiCore TokenWorks API يتطلب ثلاث خطوات بسيطة فقط:

  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، ويمكن للمطورين اختيار ما يناسب لغتهم للتكامل بسرعة.

هل ستُضاف نماذج باستمرار؟ وهل تتطلب النماذج الجديدة تعديل الكود؟

نعم. تواصل المنصة إضافة نماذج محلية وعالمية رئيسية جديدة، مع الحفاظ على اتساق طريقة التكامل ونظام الفوترة، وبعد إطلاق النموذج الجديد يمكن اختياره مباشرة دون تعديل الكود.

كيف يمكن استخدام آلية التخزين المؤقت في واجهة برمجة تطبيقات النماذج الكبيرة؟ وفي أي السيناريوهات يتم تفعيلها؟

تعتمد المنصة تخزينًا مؤقتًا مشتركًا بين المستخدمين لنفس الـ prompt، وعند تفعيله ينخفض السعر بأكثر من 90% إضافية، حيث يصل سعر تفعيل التخزين المؤقت إلى ¥0.010 لكل مليون Token كحد أدنى، ويتم احتساب الجزء المفعّل بسعر التخزين المؤقت. يناسب هذا السيناريوهات التي يعيد فيها عدة مستخدمين استخدام نفس البادئة من الـ prompt، مثل الـ prompt الثابت للنظام أو بادئات المعرفة العامة — ضع الجزء الثابت في المقدمة لتحصل على معدل تفعيل أعلى.

في حال فشل استدعاء API أو انتهاء المهلة، كيف يتم إجراء إعادة المحاولة التلقائية والتخفيض الاحتياطي؟

الطريقة المعتادة هي: استخدام إعادة المحاولة بتراجع أسي لأخطاء انتهاء المهلة والأخطاء القابلة لإعادة المحاولة، مع تحديد الحد الأقصى لعدد المحاولات؛ وإذا استمر الفشل يتم التخفيض الاحتياطي إلى نموذج بديل. في المنصة، يكفي تغيير ID النموذج للتبديل بين النماذج دون أي تعديل في الكود، فقط اكتب هدف التخفيض الاحتياطي كـ ID نموذج آخر. كما توفر المنصة تكرارًا متعدد العقد وتوجيهًا ذكيًا عبر المناطق، مع تبديل تلقائي عند خلل أي عقدة.

كيف يمكن مقارنة أداء وتكلفة النماذج المختلفة؟

يكفي مفتاح API واحد لاستدعاء جميع النماذج، وتبديل النموذج يتطلب فقط تغيير ID النموذج دون أي تعديل في الكود، لذا لا تحتاج إلى تكامل منفصل لكل نموذج عند إجراء مقارنة أفقية. يُنصح باستدعاء نفس مجموعة عينات الأعمال لكل نموذج على حدة، وتسجيل جودة المخرجات والاستخدام، ثم المقارنة بندًا بندًا بين السعر الرسمي وسعر الموقع بالرجوع إلى «جدول مقارنة أسعار جميع النماذج» في الموقع الرسمي.

كيف يتم تخزين API Key الخاص بالخادم بشكل آمن؟

يُنصح بحفظ API Key على الخادم فقط، وحمله عبر ترويسة الطلب بطريقة Bearer Token، وعدم كتابته في كود الواجهة الأمامية أو العميل. تُنقل بيانات الطلب والاستجابة عبر المنصة مشفرة بالكامل باستخدام HTTPS، كما توفر المنصة إدارة صلاحيات على مستوى المؤسسات وسجلات تدقيق، مع إمكانية تتبع سجلات الاستدعاء.

كيف يمكن ضمان استقرار الاستدعاء وزمن استجابة منخفض في سيناريوهات التزامن العالي؟

تعتمد المنصة على مراكز حوسبة في مناطق مثل هولينغير في منغوليا الداخلية، وهامی في شينجيانغ، وتشونغوي في نينغشيا، وتستخدم خوارزميات جدولة مطورة داخليًا للتوجيه الذكي عبر المناطق وموازنة الحمل الديناميكية، مع تبديل تلقائي عند خلل أي عقدة؛ ويحصل المستخدمون في المدن الرئيسية على زمن استجابة بمستوى المللي ثانية، مع التزام بتوافر الخدمة بنسبة 99.9%. يُنصح بأن يدمج جانب العميل أيضًا إعادة المحاولة بتراجع والتخفيض الاحتياطي متعدد النماذج.

كيف يمكن مراقبة حجم الاستدعاءات والتكاليف والحالات الشاذة؟

توفر المنصة حسابًا موحدًا ونظام فواتير واحدًا، مع شفافية في الاستخدام، ووصول الرصيد في الوقت الفعلي، وإمكانية عرض تفاصيل الاستهلاك في أي وقت؛ كما توفر وظيفة سجلات التدقيق لاستدعاءات API، مع إمكانية تتبع سجلات الاستدعاء. إذا احتاج مستخدمو المؤسسات إلى متطلبات امتثال أكثر صرامة (إدارة الصلاحيات، سجلات التدقيق، إلخ)، يمكنهم التواصل مع خدمة العملاء للتنسيق التجاري.