الأساسيات
مرجع API
المرجع الكامل لواجهة برمجة تطبيقات TokenLab API
نظرة عامة (Overview)
TokenLab هو الأصلي أولًا ومتوافق مع OpenAI. استخدم المسارات الأصلية الخاصة بالمزوّد مثل POST /v1/messages لـ Anthropic و/v1beta/models/...:generateContent لـ Gemini عندما تحتاج إلى سلوك أصلي، واستخدم نقاط نهاية /v1 المتوافقة مع OpenAI عندما تكون بصدد ترحيل SDKs أو أدوات بأسلوب OpenAI موجودة. يظل POST /v1/responses مسارًا اختياريًا متقدمًا لسلوك خاص بـ Responses.
عنوان URL الأساسي (Base URL)
https://api.tokenlab.shالمصادقة (Authentication)
تستخدم طلبات النماذج مفتاح API من TokenLab. ترويسة المصادقة القياسية هي:
Authorization: Bearer sk-your-api-keyتكون GET /v1/models وGET /v1/models/{model} وGET /v1/pricing عامة ولا تحتاج إلى مفتاح. يقبل Anthropic Messages أيضًا x-api-key، ويقبل Gemini الترويسة x-goog-api-key أو المعلمة ?key= بالإضافة إلى Bearer. تتطلب /v1/management/* رمز إدارة (mt-...).
احصل على مفتاح API الخاص بك من لوحة التحكم (Dashboard).
تقبل طلبات التوليد X-TokenLab-Delivery-Policy: auto | verified | official. تتقدم الترويسة على إعداد مفتاح API، ثم على الإعداد الافتراضي لمساحة العمل. يفضّل auto استخدام TokenLab Verified ثم Official عند الحاجة، وتكون الفوترة بحسب الطريقة التي أكملت الطلب. يستخدم verified أسعار TokenLab؛ ويستند official إلى أسعار الشركة المصنّعة العامة بالسعر المعروض على TokenLab. يستخدم Realtime إعداد المفتاح أو مساحة العمل دون تجاوز عبر الاستعلام. تعيد الترويسة غير الصالحة 400، ويعيد الخيار غير المتاح 503 delivery_tier_unavailable ومعرّف الطلب.
حول بيئة الاختبار التفاعلية (Interactive Playground): بيئة الاختبار في موقع التوثيق هذا مخصصة لأغراض العرض التوضيحي فقط ولا تدعم إدخال مفاتيح API. لاختبار API، يرجى استخدام:
- cURL - انسخ أوامر الأمثلة واستبدل
sk-your-api-keyبمفتاحك الفعلي - Postman - استورد مواصفات OpenAPI الخاصة بنا
- SDK - استخدم OpenAI/Anthropic SDK مع عنوان URL الأساسي الخاص بنا
نقاط النهاية المدعومة (Supported Endpoints)
الدردشة وتوليد النصوص
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/chat/completions | POST | إكمال الدردشة المتوافق مع OpenAI |
/v1/messages | POST | واجهة برمجة تطبيقات الرسائل المتوافقة مع Anthropic |
/v1/responses | POST | واجهة برمجة تطبيقات استجابات OpenAI |
التضمينات وإعادة الترتيب (Embeddings & Rerank)
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/embeddings | POST | إنشاء تضمينات النصوص (text embeddings) |
/v1/rerank | POST | إعادة ترتيب المستندات (Rerank) |
الصور
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/images/generations | POST | توليد الصور من النصوص |
/v1/images/edits | POST | تعديل الصور |
/v1/images/generations/{id} | GET | مسار حالة مهمة الصور للاستجابات القائمة على المهام |
قد تعيد نماذج الصور صورة مكتملة أو مهمة غير متزامنة. إذا تضمنت الاستجابة poll_url، فاستخدم ذلك الرابط للاستعلام عن المهمة.
الصوت
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/audio/speech | POST | تحويل النص إلى كلام (TTS) |
/v1/audio/transcriptions | POST | تحويل الكلام إلى نص (STT) |
الوقت الفعلي
| المسار | الطريقة | الوصف |
|---|---|---|
/v1/realtime?model={model} | WS | جلسات WebSocket فورية |
استخدم /v1/realtime لطلبات ترقية WebSocket. يعيد GET /v1/realtime العادي معلومات المسار للعملاء الذين لا يمكنهم فحص مسارات WebSocket مباشرة. هذا ليس سطح OpenAI Realtime REST؛ مسارات client secret و translation client secret و Calls و legacy beta session غير متاحة حالياً.
الفيديو
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/videos/generations | POST | إنشاء مهمة توليد فيديو |
/v1/tasks/{id} | GET | الحصول على حالة المهمة غير المتزامنة لوظائف الفيديو |
/v1/videos/generations/{id} | GET | مسار حالة مهمة الفيديو المتوافق مع الأنظمة القديمة |
للعملاء الجدد، يفضل استخدام /v1/tasks/{id} واتباع poll_url الذي تعيده استجابات الإنشاء. احتفظ بـ /v1/videos/generations/{id} فقط للتوافق مع الإصدارات السابقة.
المهام غير المتزامنة (Async Tasks)
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/tasks/{id} | GET | نقطة نهاية موحدة لحالة المهام غير المتزامنة. يوصى بها عند اتباع poll_url المستلم |
لا تقتصر نقطة النهاية هذه على الفيديو والموسيقى و3D. قد تستخدم بعض مهام الصور أيضاً /v1/tasks/{id} كمسار استطلاع (polling) أساسي.
الموسيقى
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/music/generations | POST | إنشاء مهمة توليد موسيقى |
/v1/music/generations/{id} | GET | مسار الحالة الخاص بالموسيقى |
للعملاء الجدد، يفضل استخدام poll_url المستلم أولاً. إذا كنت بحاجة إلى نقطة نهاية ثابتة لحالة المهمة، فاستخدم /v1/tasks/{id}؛ احتفظ بـ /v1/music/generations/{id} لمسارات التوافق الخاصة بالموسيقى.
توليد نماذج ثلاثية الأبعاد (3D Generation)
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/3d/generations | POST | إنشاء مهمة توليد نماذج ثلاثية الأبعاد (3D) |
/v1/3d/generations/{id} | GET | مسار الحالة الخاص بالنماذج ثلاثية الأبعاد |
للعملاء الجدد، يفضل استخدام poll_url المستلم أولاً. إذا كنت بحاجة إلى نقطة نهاية ثابتة لحالة المهمة، فاستخدم /v1/tasks/{id}؛ احتفظ بـ /v1/3d/generations/{id} لمسارات التوافق الخاصة بالنماذج ثلاثية الأبعاد.
النماذج (Models)
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1/models | GET | قائمة بجميع النماذج المتاحة |
/v1/models/{model} | GET | الحصول على معلومات نموذج محدد |
Gemini (v1beta)
دعم تنسيق Google Gemini API الأصلي:
| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف |
|---|---|---|
/v1beta/models/{model}:generateContent | POST | توليد المحتوى (تنسيق Gemini) |
/v1beta/models/{model}:streamGenerateContent | POST | توليد المحتوى بالبث (تنسيق Gemini) |
تدعم نقاط نهاية Gemini المصادقة عبر معلمة الاستعلام ?key= بالإضافة إلى Bearer token القياسي.
تنسيق الاستجابة (Response Format)
تحافظ كل نقطة نهاية على تنسيق API الخاص بها. تستخدم أمثلة النجاح والخطأ أدناه تنسيق Chat Completions.
استجابة النجاح
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1234567890,
"model": "gpt-5.6-terra",
"choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
}
}شفافية التوجيه (Routing Transparency)
لا يكشف TokenLab تفاصيل المزوّد أو القناة أو السياسة أو بيانات الاعتماد في أجسام الاستجابات العامة. لا تعتمد على _routing أو أي حقول توجيه داخلية أخرى كجزء من عقد واجهة API العامة.
لأغراض التصحيح والدعم، استخدم ترويسات الاستجابة العامة عندما تكون موجودة:
| الترويسة | الوصف |
|---|---|
X-Routing-Time-MS | وقت اختيار المسار، عند توفره |
X-Request-ID | معرّف الطلب للدعم والتصحيح، عند توفره |
X-Task-ID | معرّف المهمة غير المتزامنة العام للاستجابات المعتمدة على المهام، عند توفره |
X-Billing-Transaction-ID | معرّف معاملة الفوترة بعد الفوترة النهائية، عند توفره |
استجابة الخطأ
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}حدود المعدل (Rate Limits)
تعتمد حدود المعدل على الأدوار وهي قابلة للتكوين من قبل المسؤولين. القيم الافتراضية:
| الدور | الطلبات/الدقيقة |
|---|---|
| User (مستخدم) | 1,000 |
| Partner (شريك) | 10,000 |
| VIP | 10,000 |
اتصل بالدعم للحصول على حدود معدل مخصصة. قد تختلف القيم الدقيقة حسب تكوين الحساب.
عند تجاوز حدود المعدل، تعيد API رمز الحالة 429 مع رأس Retry-After يشير إلى مدة الانتظار المطلوبة.
مواصفات OpenAPI
مواصفات OpenAPI
قم بتنزيل مواصفات OpenAPI 3.1 الكاملة