مرجع 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 المصادقة باستخدام Bearer token:

Authorization: Bearer sk-your-api-key

احصل على مفتاح API الخاص بك من لوحة التحكم (Dashboard).

حول بيئة الاختبار التفاعلية (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	مسار حالة مهمة الصور للاستجابات القائمة على المهام

قد تعيد بعض نماذج الصور النتائج مباشرة (inline)، وقد يعيد بعضها استجابات قائمة على المهام، وقد يتصرف البعض الآخر بكلتا الطريقتين اعتماداً على مسار المزود الموجه. إذا تضمنت استجابة الإنشاء 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)

تتبع جميع الاستجابات تنسيقاً ثابتاً:

استجابة النجاح

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4o",
  "choices": [...],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

شفافية التوجيه (Routing Transparency)

تتضمن جميع الاستجابات حقل _routing مع معلومات القناة:

{
  "id": "chatcmpl-abc123",
  ...,
  "_routing": {
    "channel": {
      "id": "ch_xxx",
      "name": "channel-name",
      "provider": "openai"
    },
    "cached": false,
    "retryCount": 0
  }
}

الحقل	الوصف
`channel.id`	معرف القناة المستخدم
`channel.provider`	المزود الأساسي (openai، anthropic، إلخ.)
`cached`	ما إذا كانت الاستجابة قد تمت خدمتها من ذاكرة التخزين المؤقت (cache)
`retryCount`	عدد محاولات إعادة المحاولة (إن وجدت)

استجابة الخطأ

{
  "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 3.0 الكاملة

الأساسيات

النص

الملفات والدفعات

الصور

الصوت والوقت الفعلي

الموسيقى

الفيديو والمواد

Worlds

3D

المهام غير المتزامنة

Gemini الأصلي

الإدارة

نظرة عامة (Overview)

عنوان URL الأساسي (Base URL)

المصادقة (Authentication)

نقاط النهاية المدعومة (Supported Endpoints)

الدردشة وتوليد النصوص

التضمينات وإعادة الترتيب (Embeddings & Rerank)

الصور

الصوت

الوقت الفعلي

الفيديو

المهام غير المتزامنة (Async Tasks)

الموسيقى

توليد نماذج ثلاثية الأبعاد (3D Generation)

النماذج (Models)

Gemini (v1beta)

تنسيق الاستجابة (Response Format)

استجابة النجاح

شفافية التوجيه (Routing Transparency)

استجابة الخطأ

حدود المعدل (Rate Limits)

مواصفات OpenAPI

مواصفات OpenAPI

​نظرة عامة (Overview)

​عنوان URL الأساسي (Base URL)

​المصادقة (Authentication)

​نقاط النهاية المدعومة (Supported Endpoints)

​الدردشة وتوليد النصوص

​التضمينات وإعادة الترتيب (Embeddings & Rerank)

​الصور

​الصوت

​الوقت الفعلي

​الفيديو

​المهام غير المتزامنة (Async Tasks)

​الموسيقى

​توليد نماذج ثلاثية الأبعاد (3D Generation)

​النماذج (Models)

​Gemini (v1beta)

​تنسيق الاستجابة (Response Format)

​استجابة النجاح

​شفافية التوجيه (Routing Transparency)

​استجابة الخطأ

​حدود المعدل (Rate Limits)

​مواصفات OpenAPI

مواصفات OpenAPI

نظرة عامة (Overview)

عنوان URL الأساسي (Base URL)

المصادقة (Authentication)

نقاط النهاية المدعومة (Supported Endpoints)

الدردشة وتوليد النصوص

التضمينات وإعادة الترتيب (Embeddings & Rerank)

الصور

الصوت

الوقت الفعلي

الفيديو

المهام غير المتزامنة (Async Tasks)

الموسيقى

توليد نماذج ثلاثية الأبعاد (3D Generation)

النماذج (Models)

Gemini (v1beta)

تنسيق الاستجابة (Response Format)

استجابة النجاح

شفافية التوجيه (Routing Transparency)

استجابة الخطأ

حدود المعدل (Rate Limits)

مواصفات OpenAPI