> ## 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.

# ✨ مهارة تكامل TokenLab API

> ثبّت مهارة تكامل TokenLab API المُحدّثة وعلّم وكلاء البرمجة اكتشاف النماذج وقراءة العقود العامة والتعافي من أخطاء API.

<Note>
  تشرح هذه الصفحة مهارة `tokenlab-api-integration` المشتركة والمُحدّثة. التوزيع الرسمي موجود في [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills)، حيث يحتفظ المستودع العام بهذه المهارة فقط بشكل مقصود.
</Note>

<Note>
  استخدم هذه الصفحة لتثبيت المهارة وإرشاد سير عمل agent. لإعداد endpoint محدد، استخدم صفحة SDK أو العميل أو مرجع API الخاصة به.
</Note>

## ما الذي تفعله المهارة

* تولّد أمثلة صغيرة قابلة للتشغيل لعائلات TokenLab API مثل chat والصور والصوت والفيديو والترجمة وغيرها.
* تستخدم `https://api.tokenlab.sh/v1` للعملاء المتوافقين مع OpenAI وتوضح متى يجب الانتقال إلى مسارات Anthropic أو Gemini الأصلية.
* تكتشف النماذج عبر `/v1/models` و`/llms.txt` وقوائم `recommended_for` بدل التخمين من قوائم قديمة.
* تقرأ تفاصيل النموذج للنموذج قبل إعادة محاولة طلبات غير المحادثة حتى لا تُزال الحقول غير المدعومة بصمت.
* تتعامل مع تلميحات Agent-First مثل `did_you_mean` و`suggestions` و`retry_after` و`recommended_request`.

## التثبيت

<Note>
  استخدم أمر التثبيت الرسمي غير التفاعلي:

  ```bash theme={null}
  npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
  ```

  يثبّت هذا الأمر مهارة `tokenlab-api-integration` المشتركة من مستودع TokenLab skills.

  إذا لم تدعم أداتك installer، انسخ `skills/tokenlab-api-integration/` من المستودع إلى مجلد skills أو rules المشترك في أداتك.
</Note>

### تحديث التثبيتات الحالية

إذا ثبّت المهارة قبل تنظيف مستودع TokenLab، أعد تشغيل الأمر نفسه. الحزمة العامة الحالية أصغر ولم تعد تعتمد على سكربتات بحث محلية مولّدة.

### التحقق من التثبيت

اسأل coding agent لديك:

```
ما skills المتاحة؟
```

إذا رأيت `tokenlab-api-integration` فهذا يعني أن التثبيت نجح.

## الحصول على API Key

<Steps>
  <Step title="افتح TokenLab">
    انتقل إلى [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="سجّل الدخول">
    أنشئ حسابًا أو سجّل الدخول
  </Step>

  <Step title="احصل على API Key">
    افتح [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) وأنشئ key جديدًا
  </Step>

  <Step title="انسخ key">
    يبدأ key بـ `sk-...`. خزّنه بأمان.
  </Step>
</Steps>

<Tip>
  لا تلصق API keys في prompts أو ملفات المصدر. يجب أن تسأل المهارة عن متغير البيئة المستخدم وتولّد كودًا يقرأ key من ذلك المتغير.
</Tip>

## سير عمل Agent الموصى به

1. ابدأ بأصغر مثال يعمل ويطابق لغة المستخدم وعائلة API المطلوبة.
2. عندما يكون اختيار النموذج مفتوحًا، استدعِ `/v1/models` أو `https://api.tokenlab.sh/llms.txt` قبل تثبيت نموذج في الكود.
3. لأعمال غير المحادثة، استدعِ `/v1/models?recommended_for=<scene>` حيث تكون `<scene>` واحدة من `image` أو `video` أو `music` أو `3d` أو `tts` أو `stt` أو `embedding` أو `rerank` أو `translation`.
4. قبل تعديل طلب غير محادثة فشل، اقرأ `/v1/models/:model` ووافق `supported_operations` و`supported_parameters` و`request_endpoint`, `request_endpoint_by_operation` و`request_shape_mode` و`recommended_request`.
5. إذا أعادت API خطأ Agent-First، استخدم الحقول المنظمة لتصحيح الطلب ولا تعِد المحاولة إلا إذا كان الخطأ retryable.

## مثال محادثة بسيط

يستخدم هذا المثال OpenAI Python SDK مع base URL الخاص بـ TokenLab:

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)
```

شغّله باستخدام:

```bash theme={null}
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py
```

## اكتشاف النماذج والعقود العامة

فضّل الاكتشاف الحي بدل القوائم المضمّنة القديمة:

```bash theme={null}
# نظرة عامة على API قابلة للقراءة آليًا
curl https://api.tokenlab.sh/llms.txt

# عرض النماذج
curl "https://api.tokenlab.sh/v1/models" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer sk-KEY"

# قوائم مختصرة مرتبة لغير المحادثة
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer sk-KEY"

# اقرأ تفاصيل النموذج لنموذج واحد قبل إعادة محاولة طلب غير محادثة
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# تفاصيل التسعير فقط
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## تلميحات التوجيه الأصلي

المسار المتوافق مع OpenAI `/v1` هو الافتراضي لأمثلة chat وResponses والصور وembedding والصوت وrerank. استخدم مسارات Anthropic أو Gemini الأصلية فقط عندما يحتاج الطلب إلى سلوك خاص بالمزوّد أو عندما يعيد TokenLab تلميح التحسين `X-TokenLab-Native-Endpoint`.

```
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
```

## استرداد أخطاء Agent-First

تتضمن الأخطاء حقولًا يمكن لوكلاء البرمجة تحليلها من دون استخراج النص من الوثائق:

| الخطأ                      | حقول مفيدة                                                                                                                                       | إجراء agent                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| اسم النموذج غير صحيح       | `did_you_mean`, `suggestions`, `hint`                                                                                                            | أعِد المحاولة بالنموذج المصحح أو ببديل مقترح                                          |
| الرصيد غير كافٍ            | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | اطلب موافقة أو انتقل إلى نموذج ميسور التكلفة                                          |
| حد معدل أو عدم توفر مؤقت   | `retryable`, `retry_after`, `alternatives`                                                                                                       | انتظر ثم أعد المحاولة أو اختر بديلًا من القائمة                                       |
| عدم تطابق عقد غير المحادثة | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | أعد بناء الطلب من تفاصيل النموذج، واستخدم return a clear error للحقول التي تغير النية |

## عائلات API المدعومة

| العائلة              | المسار الرئيسي                                                           |
| -------------------- | ------------------------------------------------------------------------ |
| Chat وResponses      | `/v1/chat/completions`, `/v1/responses`                                  |
| رسائل Claude الأصلية | `/v1/messages`                                                           |
| طلبات Gemini الأصلية | `/v1beta/models/{model}:generateContent`                                 |
| الصور                | `/v1/images/generations`, `/v1/images/edits`                             |
| الفيديو              | `/v1/videos/generations`                                                 |
| الموسيقى             | `/v1/music/generations`                                                  |
| Worlds               | `/v1/worlds/generations` مع endpoints لحالة world وmedia asset           |
| 3D                   | `/v1/3d/generations`                                                     |
| الصوت                | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime             | `/v1/realtime?model={model}`                                             |
| Embeddings وrerank   | `/v1/embeddings`, `/v1/rerank`                                           |
| ترجمة النص           | `/v1/translations`                                                       |

## أفضل الممارسات

<CardGroup cols={2}>
  <Card title="أمان API Key" icon="shield">
    استخدم متغيرات البيئة والاستدعاءات من الخادم. لا تكشف keys في كود الواجهة الأمامية.
  </Card>

  <Card title="العقد أولًا لغير المحادثة" icon="file-code">
    اقرأ `/v1/models?recommended_for=...` و`/v1/models/:model` قبل إعادة محاولة طلبات الصور أو الفيديو أو الموسيقى أو 3D أو الترجمة أو الصوت أو embedding أو rerank.
  </Card>

  <Card title="أصغر مثال قابل للتشغيل" icon="terminal">
    أنشئ استدعاءً واحدًا يعمل قبل إضافة التجريدات أو الطوابير أو تدفقات UI.
  </Card>

  <Card title="استخدم التلميحات المنظمة" icon="rotate-cw">
    حلّل `did_you_mean` و`retry_after` و`alternatives` و`recommended_request` قبل تغيير الكود.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="المهارة لا تعمل تلقائيًا؟">
    اذكر “TokenLab” أو “TokenLab API” في الطلب، مثل: `استخدم TokenLab لإضافة توليد الصور إلى تطبيق Node.js`.
  </Accordion>

  <Accordion title="ما coding agents المدعومة؟">
    أي coding agent يدعم مجلدات skills أو rules المشتركة يمكنه استخدام هذا المجلد. يتولى installer `skills` التعامل مع agents المدعومة تلقائيًا.
  </Accordion>

  <Accordion title="كيف أحدّث المهارة؟">
    أعد تشغيل أمر التثبيت. سيحدّث النسخة المحلية من المستودع العام الرسمي.

    ```bash theme={null}
    npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
    ```
  </Accordion>
</AccordionGroup>

## الموارد

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/ar/guides/agent-first-api">
    تلميحات أخطاء منظمة وسلوك الاسترداد
  </Card>

  <Card title="وثائق API" icon="book" href="https://docs.tokenlab.sh">
    إعداد خاص بكل endpoint وAPI Reference
  </Card>

  <Card title="النماذج" icon="sparkles" href="https://tokenlab.sh/ar/models">
    تصفح النماذج المتاحة
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    نظرة عامة على API قابلة للقراءة آليًا للوكلاء
  </Card>
</CardGroup>

<Info>
  لديك أسئلة؟ استخدم [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) أو تواصل عبر [support@tokenlab.sh](mailto:support@tokenlab.sh).
</Info>