الانتقال إلى المحتوى الرئيسي
تشرح هذه الصفحة مهارة 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

1

افتح TokenLab

انتقل إلى tokenlab.sh
2

سجّل الدخول

أنشئ حسابًا أو سجّل الدخول
3

احصل على API Key

افتح Dashboard → API Keys وأنشئ key جديدًا
4

انسخ key

يبدأ key بـ sk-.... خزّنه بأمان.
لا تلصق API keys في prompts أو ملفات المصدر. يجب أن تسأل المهارة عن متغير البيئة المستخدم وتولّد كودًا يقرأ key من ذلك المتغير.

​
سير عمل 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: 
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)
شغّله باستخدام: 
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 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

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

أمان API Key

استخدم متغيرات البيئة والاستدعاءات من الخادم. لا تكشف keys في كود الواجهة الأمامية.

العقد أولًا لغير المحادثة

اقرأ /v1/models?recommended_for=... و/v1/models/:model قبل إعادة محاولة طلبات الصور أو الفيديو أو الموسيقى أو 3D أو الترجمة أو الصوت أو embedding أو rerank.

أصغر مثال قابل للتشغيل

أنشئ استدعاءً واحدًا يعمل قبل إضافة التجريدات أو الطوابير أو تدفقات UI.

استخدم التلميحات المنظمة

حلّل did_you_mean وretry_after وalternatives وrecommended_request قبل تغيير الكود.

​
FAQ

اذكر “TokenLab” أو “TokenLab API” في الطلب، مثل: استخدم TokenLab لإضافة توليد الصور إلى تطبيق Node.js.
أي coding agent يدعم مجلدات skills أو rules المشتركة يمكنه استخدام هذا المجلد. يتولى installer skills التعامل مع agents المدعومة تلقائيًا.
أعد تشغيل أمر التثبيت. سيحدّث النسخة المحلية من المستودع العام الرسمي.
npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y

​
الموارد

Agent-First API

تلميحات أخطاء منظمة وسلوك الاسترداد

وثائق API

إعداد خاص بكل endpoint وAPI Reference

النماذج

تصفح النماذج المتاحة

llms.txt

نظرة عامة على API قابلة للقراءة آليًا للوكلاء
لديك أسئلة؟ استخدم GitHub Issues أو تواصل عبر support@tokenlab.sh.