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

تشرح هذه الصفحة مهارة 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 الموصى به

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

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

الخطأ	حقول مفيدة	إجراء 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`	أعد بناء الطلب من تفاصيل النموذج، وأعد خطأً واضحًا للحقول التي تغيّر المقصود

عائلات 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 agents المدعومة؟

أي 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.

البدء

الأدلة الأساسية

أدلة الوسائط

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

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

التثبيت

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

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

الحصول على API Key

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

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

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

اختيار البروتوكول الأصلي

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

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

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

أمان API Key

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

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

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

FAQ

الموارد

Agent-First API

وثائق API

النماذج

llms.txt

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

​التثبيت

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

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

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

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

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

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

​اختيار البروتوكول الأصلي

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

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

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

أمان API Key

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

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

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

​FAQ

​الموارد

Agent-First API

وثائق API

النماذج

llms.txt

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

التثبيت

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

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

الحصول على API Key

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

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

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

اختيار البروتوكول الأصلي

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

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

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

FAQ

الموارد