> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
Authorization: Bearer sk-your-api-key
```

احصل على مفتاح API الخاص بك من [لوحة التحكم (Dashboard)](https://tokenlab.sh/dashboard).

<Warning>
  **حول بيئة الاختبار التفاعلية (Interactive Playground)**: بيئة الاختبار في موقع التوثيق هذا مخصصة لأغراض العرض التوضيحي فقط ولا تدعم إدخال مفاتيح API. لاختبار API، يرجى استخدام:

  * **cURL** - انسخ أوامر الأمثلة واستبدل `sk-your-api-key` بمفتاحك الفعلي
  * **Postman** - استورد [مواصفات OpenAPI](/openapi.json) الخاصة بنا
  * **SDK** - استخدم OpenAI/Anthropic SDK مع عنوان URL الأساسي الخاص بنا
</Warning>

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

<Info>
  قد تعيد بعض نماذج الصور النتائج مباشرة (inline)، وقد يعيد بعضها استجابات قائمة على المهام، وقد يتصرف البعض الآخر بكلتا الطريقتين اعتماداً على مسار المزود الموجه. إذا تضمنت استجابة الإنشاء `poll_url` فقم باتباعه بدقة.
</Info>

### الصوت

| نقطة النهاية (Endpoint)    | الطريقة (Method) | الوصف                     |
| -------------------------- | ---------------- | ------------------------- |
| `/v1/audio/speech`         | POST             | تحويل النص إلى كلام (TTS) |
| `/v1/audio/transcriptions` | POST             | تحويل الكلام إلى نص (STT) |

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

| المسار                       | الطريقة | الوصف                 |
| ---------------------------- | ------- | --------------------- |
| `/v1/realtime?model={model}` | WS      | جلسات WebSocket فورية |

<Info>
  استخدم `/v1/realtime` لطلبات ترقية WebSocket. يعيد `GET /v1/realtime` العادي معلومات المسار للعملاء الذين لا يمكنهم فحص مسارات WebSocket مباشرة. هذا ليس سطح OpenAI Realtime REST؛ مسارات client secret و translation client secret و Calls و legacy beta session غير متاحة حالياً.
</Info>

### الفيديو

| نقطة النهاية (Endpoint)       | الطريقة (Method) | الوصف                                               |
| ----------------------------- | ---------------- | --------------------------------------------------- |
| `/v1/videos/generations`      | POST             | إنشاء مهمة توليد فيديو                              |
| `/v1/tasks/{id}`              | GET              | الحصول على حالة المهمة غير المتزامنة لوظائف الفيديو |
| `/v1/videos/generations/{id}` | GET              | مسار حالة مهمة الفيديو المتوافق مع الأنظمة القديمة  |

<Info>
  للعملاء الجدد، يفضل استخدام `/v1/tasks/{id}` واتباع `poll_url` الذي تعيده استجابات الإنشاء. احتفظ بـ `/v1/videos/generations/{id}` فقط للتوافق مع الإصدارات السابقة.
</Info>

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

| نقطة النهاية (Endpoint) | الطريقة (Method) | الوصف                                                                              |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| `/v1/tasks/{id}`        | GET              | نقطة نهاية موحدة لحالة المهام غير المتزامنة. يوصى بها عند اتباع `poll_url` المستلم |

<Info>
  لا تقتصر نقطة النهاية هذه على الفيديو والموسيقى و3D. قد تستخدم بعض مهام الصور أيضاً `/v1/tasks/{id}` كمسار استطلاع (polling) أساسي.
</Info>

### الموسيقى

| نقطة النهاية (Endpoint)      | الطريقة (Method) | الوصف                       |
| ---------------------------- | ---------------- | --------------------------- |
| `/v1/music/generations`      | POST             | إنشاء مهمة توليد موسيقى     |
| `/v1/music/generations/{id}` | GET              | مسار الحالة الخاص بالموسيقى |

<Info>
  للعملاء الجدد، يفضل استخدام `poll_url` المستلم أولاً. إذا كنت بحاجة إلى نقطة نهاية ثابتة لحالة المهمة، فاستخدم `/v1/tasks/{id}`؛ احتفظ بـ `/v1/music/generations/{id}` لمسارات التوافق الخاصة بالموسيقى.
</Info>

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

| نقطة النهاية (Endpoint)   | الطريقة (Method) | الوصف                                      |
| ------------------------- | ---------------- | ------------------------------------------ |
| `/v1/3d/generations`      | POST             | إنشاء مهمة توليد نماذج ثلاثية الأبعاد (3D) |
| `/v1/3d/generations/{id}` | GET              | مسار الحالة الخاص بالنماذج ثلاثية الأبعاد  |

<Info>
  للعملاء الجدد، يفضل استخدام `poll_url` المستلم أولاً. إذا كنت بحاجة إلى نقطة نهاية ثابتة لحالة المهمة، فاستخدم `/v1/tasks/{id}`؛ احتفظ بـ `/v1/3d/generations/{id}` لمسارات التوافق الخاصة بالنماذج ثلاثية الأبعاد.
</Info>

### النماذج (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) |

<Note>
  تدعم نقاط نهاية Gemini المصادقة عبر معلمة الاستعلام `?key=` بالإضافة إلى Bearer token القياسي.
</Note>

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

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

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

```json theme={null}
{
  "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` مع معلومات القناة:

```json theme={null}
{
  "id": "chatcmpl-abc123",
  ...,
  "_routing": {
    "channel": {
      "id": "ch_xxx",
      "name": "channel-name",
      "provider": "openai",
      "channelType": "PLATFORM"
    },
    "cached": false,
    "retryCount": 0
  }
}
```

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

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

```json theme={null}
{
  "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          |

<Note>
  اتصل بالدعم للحصول على حدود معدل مخصصة. قد تختلف القيم الدقيقة حسب تكوين الحساب.
</Note>

عند تجاوز حدود المعدل، تعيد API رمز الحالة `429` مع رأس `Retry-After` يشير إلى مدة الانتظار المطلوبة.

## مواصفات OpenAPI

<Card title="مواصفات OpenAPI" icon="file-code" href="/openapi.json">
  قم بتنزيل مواصفات OpenAPI 3.0 الكاملة
</Card>