الأساسيات
مرجع API
نقاط النهاية، المصادقة، ترويسات الاستجابة، والأخطاء
نظرة عامة
يدعم TokenLab نقاط النهاية المتوافقة مع OpenAI بالإضافة إلى تنسيقات طلبات Anthropic و Gemini. يمكن لعملاء OpenAI الحاليين استخدام /v1؛ اختر تنسيقاً آخر فقط عندما يحتاج تطبيقك إلى سلوك خاص بذلك الـ API. POST /v1/responses اختياري ويعتمد على دعم النموذج.
عنوان URL الأساسي
https://api.tokenlab.shالمصادقة
تستخدم طلبات النماذج مفتاح API الخاص بـ TokenLab. ترويسة المصادقة القياسية هي:
Authorization: Bearer sk-your-api-keyتعتبر GET /v1/models و GET /v1/models/{model} و GET /v1/models/{model}/pricing و GET /v1/pricing عامة ولا تحتاج إلى مفتاح. تقبل Anthropic Messages أيضاً x-api-key؛ بينما تقبل Gemini x-goog-api-key أو ?key= بالإضافة إلى مصادقة Bearer. تتطلب /v1/management/* رمز إدارة (mt-...).
احصل على مفتاح API الخاص بك من لوحة التحكم.
سياسة التسليم
تقبل طلبات التوليد X-TokenLab-Delivery-Policy: auto | verified | official. تتجاوز ترويسة الطلب إعداد مفتاح API، والذي بدوره يتجاوز الإعداد الافتراضي لمساحة العمل (Workspace).
Autoيستخدم TokenLab Verified عند توفره، ثم Official إذا لزم الأمر. أنت تدفع مقابل الخيار الذي يكمل طلبك.TokenLab Verifiedهو تسليم تم التحقق منه بواسطة TokenLab. يتم تطبيق سعر Verified.Officialيحاسب بالسعر الرسمي، وهو السعر المعلن من قبل صانع النموذج.- تستخدم جلسات Realtime مفتاح API أو إعداد مساحة العمل ولا تقبل تجاوز الطلب.
ترجع الترويسة غير الصالحة 400. إذا كان الخيار المطلوب غير متاح، يرجع TokenLab 503 delivery_tier_unavailable ومعرف طلب. اقرأ retryable: عندما لا يكون للعملية المحددة إمداد، تكون القيمة false. لا تكرر نفس الطلب دون تغيير.
تقبل صفحات API التي تحتوي على نموذج طلب مفتاح API الخاص بـ TokenLab وترسل طلبات حقيقية. تستخدم هذه الطلبات رصيد حسابك وحدوده. يمكنك أيضاً استخدام cURL أو Postman أو SDK.
نقاط النهاية المدعومة
الدردشة وتوليد النصوص
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/chat/completions | POST | إكمال الدردشة المتوافق مع OpenAI |
/v1/messages | POST | الرسائل المتوافقة مع Anthropic |
/v1/messages/count_tokens | POST | حساب الرموز (tokens) المدخلة لطلب الرسائل |
/v1/messages/batches | POST, GET | إنشاء و سرد دفعات الرسائل |
/v1/messages/batches/{message_batch_id} | GET, DELETE | استرجاع أو حذف دفعة رسائل |
/v1/messages/batches/{message_batch_id}/results | GET | قراءة النتائج |
/v1/messages/batches/{message_batch_id}/cancel | POST | إلغاء دفعة رسائل |
/v1/responses | POST | API استجابات OpenAI |
/v1/responses/{id} | GET, DELETE | استرجاع أو حذف استجابة مخزنة |
/v1/responses/compact | POST | ضغط سياق محادثة الاستجابات |
/v1/translations | POST | ترجمة نص إلى نص |
التضمينات (Embeddings) وإعادة الترتيب (Rerank)
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/embeddings | POST | إنشاء تضمينات نصية |
/v1/multimodal/embeddings | POST | إنشاء تضمينات باستخدام نموذج تضمين متعدد الوسائط |
/v1/rerank | POST | إعادة ترتيب المستندات |
القرارات
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/systemone | POST | تقييم أسئلة القرار المكتوبة |
الملفات والدفعات
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/files | POST, GET | رفع و سرد الملفات |
/v1/files/{file_id} | GET, DELETE | استرجاع أو حذف ملف |
/v1/files/{file_id}/content | GET | تنزيل محتوى الملف |
/v1/batches | POST, GET | إنشاء و سرد الدفعات |
/v1/batches/{batch_id} | GET | استرجاع دفعة |
/v1/batches/{batch_id}/cancel | POST | إلغاء دفعة |
الصور
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/images/generations | POST | توليد صور من نص |
/v1/images/edits | POST | تعديل الصور |
/v1/images/variations | POST | إنشاء تنويعات للصور |
/v1/images/generations/{id} | GET | مسار حالة التوافق لاستجابات الصور القائمة على المهام |
قد تعيد نماذج الصور صورة جاهزة أو مهمة غير متزامنة. إذا كانت الاستجابة تتضمن status: "pending" أو معرف مهمة، قم بعمل استطلاع (poll) لـ GET /v1/tasks/{id}.
الصوت
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/audio/speech | POST | تحويل النص إلى كلام (TTS) |
/v1/audio/transcriptions | POST | تحويل الكلام إلى نص (STT) |
/v1/audio/translations | POST | ترجمة الكلام إلى نص إنجليزي |
الوقت الفعلي (Realtime)
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/realtime?model={model} | WS | جلسات WebSocket في الوقت الفعلي |
استخدم /v1/realtime لترقيات WebSocket. يرجع GET /v1/realtime العادي بيانات تعريف نقطة النهاية. هذا ليس واجهة REST الخاصة بـ OpenAI Realtime؛ حيث أن سر العميل (client-secret)، والمكالمات، ونقاط نهاية الجلسات التجريبية القديمة غير متوفرة.
الفيديو
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/videos/generations | POST | إنشاء مهمة توليد فيديو |
/v1/videos/generations/{id} | GET | مسار حالة التوافق |
/v1/videos/assets | POST, GET | إنشاء وسرد أصول مواد Seedance |
/api/v3/contents/generations/tasks | POST, GET | مهام Seedance بتنسيق طلب Volcengine |
قم بعمل استطلاع لـ GET /v1/tasks/{id} باستخدام id المهمة. يظل /v1/videos/generations/{id} متاحاً لعمليات التكامل الحالية.
المهام غير المتزامنة
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/tasks/{id} | GET | حالة أي مهمة غير متزامنة |
/v1/tasks/{id} | DELETE | إلغاء مهمة غير متزامنة |
قم بعمل استطلاع لـ GET /v1/tasks/{id} لكل مهمة غير متزامنة: الصور، الفيديو، الموسيقى، ثلاثية الأبعاد، العوالم، وتحويل الصوت غير المتزامن. استخدم id أو task_id من استجابة الإنشاء. ترجع استجابة إنشاء العوالم poll_url تحت /v1/worlds/generations/{id}؛ قم بعمل استطلاع لـ /v1/tasks/{id} هناك أيضاً. مسارات الحالة لكل نمط في هذه الصفحة هي نقاط نهاية توافق لعمليات التكامل الحالية.
الموسيقى
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/music/generations | POST | إنشاء مهمة توليد موسيقى |
/v1/music/generations/{id} | GET | مسار حالة التوافق |
التوليد ثلاثي الأبعاد
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/3d/generations | POST | إنشاء مهمة توليد نموذج ثلاثي الأبعاد |
/v1/3d/generations/{id} | GET | مسار حالة التوافق |
العوالم
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/worlds/generations | POST | إنشاء مهمة توليد عالم |
/v1/worlds/list | POST | سرد العوالم |
/v1/worlds/{id} | GET, DELETE | استرجاع أو حذف عالم |
/v1/worlds/media-assets/prepare-upload | POST | تحضير رفع أصل وسائط |
النماذج والأسعار
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1/models | GET | سرد جميع النماذج المتاحة |
/v1/models/{model} | GET | الحصول على معلومات نموذج محدد |
/v1/models/{model}/pricing | GET | الحصول على أسعار نموذج واحد |
/v1/pricing | GET | سرد أسعار النماذج |
Gemini (v1beta)
دعم تنسيق Google Gemini API الأصلي:
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
/v1beta/models | GET | سرد النماذج التي تقبل طلبات Gemini |
/v1beta/models/{model} | GET | الحصول على نموذج |
/v1beta/models/{model}:generateContent | POST | توليد محتوى |
/v1beta/models/{model}:streamGenerateContent | POST | توليد محتوى متدفق |
/v1beta/models/{model}:countTokens | POST | حساب الرموز |
/v1beta/files, /v1beta/cachedContents | POST, GET, DELETE | ملفات Gemini والمحتوى المخزن مؤقتاً |
تدعم نقاط نهاية Gemini مصادقة معامل الاستعلام ?key= بالإضافة إلى رمز Bearer القياسي.
الإدارة
يدير /v1/management/* الرصيد، ومفاتيح API، وخطافات الويب (webhooks) باستخدام رمز إدارة. راجع واجهة برمجة تطبيقات الإدارة.
تنسيق الاستجابة
تحتفظ كل نقطة نهاية بتنسيق 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
}
}ترويسات الاستجابة
استخدم هذه الترويسات عندما تكون موجودة.
| الترويسة | الوصف |
|---|---|
X-Request-ID | معرف الطلب للدعم وتصحيح الأخطاء |
X-Routing-Time-MS | غير متدفق: إجمالي الوقت بالمللي ثانية حتى وصول استجابة المنبع، بما في ذلك الانتظار والاستدلال لدى المنبع. متدفق: دائماً 0. ليس قياسًا للتوجيه أو الانتظار. |
X-Task-ID | معرف المهمة غير المتزامنة العام للاستجابات القائمة على المهام |
X-Billing-Transaction-ID | معرف معاملة الفوترة بعد الفوترة النهائية |
قد تتضمن رفض الطلبات الرسمية upstream مع الخطأ الذي أبلغت عنه الخدمة واسم الخدمة العام. راجع معالجة أخطاء API.
استجابة الخطأ
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}حدود المعدل (Rate Limits)
تعتمد الحدود على فئة الحساب وتطبق لكل مفتاح API. تحمل استجابة 429 ترويسات Retry-After و X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset. راجع حدود المعدل لمعرفة الفئات وكيفية إعادة المحاولة.
مواصفات OpenAPI
مواصفات OpenAPI
تنزيل مواصفات OpenAPI 3.1 الكاملة