الأدلة الأساسية
✨ مهارة تكامل TokenLab API
ثبّت مهارة تكامل TokenLab API المُحدّثة وعلّم وكلاء البرمجة اكتشاف النماذج وقراءة العقود العامة والتعافي من أخطاء API.
اقرأ هذه الصفحة وأضف TokenLab Skill إلى الوكيل الحالي. تحقق أولًا من الإصدار والإعدادات النشطة، واحتفظ بالحسابات والمزوّدين والصلاحيات والإعدادات القائمة. انسخ الملفات احتياطيًا واعرض التغييرات. سأدخل مفتاح API محليًا؛ لا تطلبه أو تعرضه في المحادثة. تحقق أولًا من تحميل الإعدادات، واشرح أي اختبار مدفوع قبل تنفيذه.
https://tokenlab.sh/docs/ar/integrations/coding-agent-skillتشرح هذه الصفحة مهارة tokenlab-api-integration المشتركة والمُحدّثة. التوزيع الرسمي موجود في hedging8563/tokenlab-skills، حيث يحتفظ المستودع العام بهذه المهارة فقط بشكل مقصود.
استخدم هذه الصفحة لتثبيت المهارة وإرشاد سير عمل agent. لإعداد endpoint محدد، استخدم صفحة SDK أو العميل أو مرجع API الخاصة به.
ما الذي تفعله المهارة
- تولّد أمثلة صغيرة قابلة للتشغيل لعائلات 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.
التثبيت
استخدم أمر التثبيت الرسمي غير التفاعلي:
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 المشترك في أداتك.
تحديث التثبيتات الحالية
إذا ثبّت المهارة قبل تنظيف مستودع TokenLab، أعد تشغيل الأمر نفسه. الحزمة العامة الحالية أصغر ولم تعد تعتمد على سكربتات بحث محلية مولّدة.
التحقق من التثبيت
اسأل coding agent لديك:
ما skills المتاحة؟إذا رأيت tokenlab-api-integration فهذا يعني أن التثبيت نجح.
الحصول على API Key
افتح TokenLab
انتقل إلى tokenlab.sh
سجّل الدخول
أنشئ حسابًا أو سجّل الدخول
احصل على API Key
افتح Dashboard → API Keys وأنشئ key جديدًا
انسخ key
يبدأ key بـ sk-.... خزّنه بأمان.
لا تلصق API keys في prompts أو ملفات المصدر. يجب أن تسأل المهارة عن متغير البيئة المستخدم وتولّد كودًا يقرأ key من ذلك المتغير.
سير عمل Agent الموصى به
اقرأ قائمة النماذج الحالية ثم tokenlab.accepted_request_formats وحقول الطلب المعلنة للنموذج المختار. حافظ على التنسيق نفسه للمحادثة واستدعاءات الأدوات؛ لا تتحول الحقول تلقائيًا بين التنسيقات. لا تغيّر النموذج أو البروتوكول المختار من تلقاء نفسك عند حدوث خطأ.
مثال محادثة بسيط
يستخدم هذا المثال OpenAI Python SDK مع base URL الخاص بـ TokenLab:
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-5.6-luna",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)شغّله باستخدام:
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.pyاكتشاف النماذج والعقود العامة
فضّل الاكتشاف الحي بدل القوائم المضمّنة القديمة:
# نظرة عامة على API قابلة للقراءة آليًا
curl https://api.tokenlab.sh/llms.txt
# عرض النماذج
curl "https://api.tokenlab.sh/v1/models" -H "Authorization: Bearer $TOKENLAB_API_KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer $TOKENLAB_API_KEY"
# قوائم مختصرة مرتبة لغير المحادثة
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer $TOKENLAB_API_KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer $TOKENLAB_API_KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer $TOKENLAB_API_KEY"
# اقرأ تفاصيل النموذج لنموذج واحد قبل إعادة محاولة طلب غير محادثة
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer $TOKENLAB_API_KEY"
# تفاصيل التسعير فقط
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer $TOKENLAB_API_KEY"اختيار البروتوكول الأصلي
المسار المتوافق مع OpenAI /v1 هو الافتراضي لأمثلة chat والصور وembedding والصوت وrerank. لا تستنتج توفر البروتوكول الأصلي من اسم النموذج أو المزود، ولا من رؤوس استجابة Chat. اقرأ GET /v1/models/{model} واستخدم فقط صيغة طلب تعلنها تفاصيل النموذج.
الحقل المحدد هو tokenlab.accepted_request_formats.
نقاط نهاية البروتوكولات هي Chat Completions على /v1/chat/completions، وResponses على /v1/responses، وMessages على /v1/messages، وGemini على /v1beta/models/{model}:generateContent.
استرداد أخطاء Agent-First
تتضمن الأخطاء حقولًا يمكن لوكلاء البرمجة تحليلها من دون استخراج النص من الوثائق:
اعتمد أولًا على حالة HTTP وحقل الخطأ code. يمكن الاستفادة من did_you_mean لتصحيح اسم النموذج، لكن لا تغيّر النموذج دون اختيار المستخدم. عند 429 اتبع Retry-After أو retry_after، ولا تعد المحاولة إلا إذا سمح الخطأ بذلك وكان القرار صريحًا. أصلح أخطاء التحقق والمصادقة والرصيد والصلاحيات أولًا. إذا انتهت مهلة طلب إنشاء، فتحقق من وجود مهمة سابقة قبل إرساله مجددًا.
عائلات 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 |
أفضل الممارسات
أمان API Key
استخدم متغيرات البيئة والاستدعاءات من الخادم. لا تكشف keys في كود الواجهة الأمامية.
العقد أولًا لغير المحادثة
اقرأ /v1/models?recommended_for=... و/v1/models/:model قبل إعادة محاولة طلبات الصور أو الفيديو أو الموسيقى أو 3D أو الترجمة أو الصوت أو embedding أو rerank.
أصغر مثال قابل للتشغيل
أنشئ استدعاءً واحدًا يعمل قبل إضافة التجريدات أو الطوابير أو تدفقات UI.
استخدم التلميحات المنظمة
حلّل did_you_mean وretry_after وalternatives وrecommended_request قبل تغيير الكود.
FAQ
الموارد
لأسئلة API أو الحساب، استخدم الدعم داخل التطبيق، وراجع المعاينة ثم أرسل صراحة. لطلب معين، ابدأ من الطلبات ودليل التحقيق. أبلغ عن عيوب Skill نفسها في GitHub Issues.