الانتقال من OpenAI إلى TokenLab في 5 دقائق

تعد الـ base URL الجزء السهل عند مغادرة أي مزود خدمة؛ أما مسارات الفشل فهي المكان الذي تتعثر فيه عمليات الترحيل. للانتقال من OpenAI إلى TokenLab، تحتاج إلى تغيير قيمتين في عميل OpenAI SDK الخاص بك: base_url و api_key. يغطي بقية هذا الدليل ما يجب عليك التأكد منه حول هذا التغيير. وهذا يعني معرف النموذج (model ID) الذي ترسله، وسعره الحالي، والبث (streaming)، واستدعاءات الأدوات (tool calls)، ومعالجة الأخطاء، والمهلات الزمنية (timeouts)، والفوترة. الحقائق أدناه مستمدة من وثائق TokenLab وواجهة برمجة تطبيقات النماذج المباشرة، مع تاريخ ملاحظة كل منها.

أبرز النقاط

• التغيير الجوهري يكمن في قيمتين: رابط TokenLab الأساسي https://api.tokenlab.sh/v1 ومفتاح TokenLab API (تبدأ المفاتيح بـ sk-).
• توثق TokenLab دعم OpenAI SDK لـ Chat Completions و Responses. لا تزال المعلمات الاختيارية، وخيارات الأدوات، والحقول الخاصة بـ Responses فقط تعتمد على النموذج المختار.
• اطلع على سعر نموذجك من واجهة برمجة التطبيقات المباشرة قبل اتخاذ أي قرار. في 2026-10-03، كان سعر gpt-5.5 هو 1.50 دولار للمدخلات و9.00 دولار للمخرجات لكل مليون token.
• نفذ قائمة التحقق في النهاية قبل نقل حركة مرور الإنتاج. تكمن معظم المفاجآت في معالجة الأخطاء، والمهلات الزمنية، والفوترة، وليس في المسار السعيد (happy path).

تغيير القيمتين للهجرة من OpenAI إلى TokenLab

ابدأ بالمفتاح. وفقاً لـ دليل البدء السريع (تمت ملاحظته في 2026-10-03)، يمكنك إنشاء حساب، وإنشاء مفتاح API، وحفظ القيمة الكاملة فوراً. يتم عرضها مرة واحدة فقط، ولا يمكن للبادئة الموجودة في قائمة المفاتيح مصادقة الطلبات. تحقق من رصيدك قبل إجراء أول مكالمة، لأن الطلبات تُحاسب بالسعر الحالي للنموذج المختار.

ثم قم بتغيير العميل. يصف دليل الترحيل (تمت ملاحظته في 2026-10-03) الوصفة كالتالي: اضبط base_url / baseURL على https://api.tokenlab.sh/v1، واستبدل المفتاح، واختر معرف نموذج من GET /v1/models.

على سبيل المثال، تخيل خدمة تحتوي على السلسلة gpt-5.5 في تكوينها. بعد تغيير القيمتين، تظل هذه السلسلة طلباً صالحاً، ولكننا لا نزال نؤكد على التحقق من المعرف أولاً. تعد GET /v1/models و GET /v1/models/{model} نقاط نهاية عامة للاكتشاف وتعمل بدون مفتاح.

Python

import os
from openai import OpenAI

# قبل: client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';

// قبل: new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
const client = new OpenAI({
  apiKey: process.env.TOKENLAB_API_KEY,
  baseURL: 'https://api.tokenlab.sh/v1',
  timeout: 30_000,
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(completion.choices[0].message.content);

cURL

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Say hello"}]}'

تعكس إعدادات المهلة وإعادة المحاولة في المثالين الأولين أمثلة دليل البدء السريع (تمت ملاحظتها في 2026-10-03)، والتي تستخدم مهلة 30 ثانية وصفر إعادة محاولة في SDK. نحن نبقي عمليات إعادة المحاولة عند الصفر أثناء الاختبار حتى يظهر الطلب الفاشل بدلاً من إعادة محاولته بصمت.

مرر الـ base URL بشكل صريح في تكوين العميل. يوصي دليل SDK (تمت ملاحظته في 2026-10-03) بهذا بدلاً من الاعتماد على أسماء مستعارة لمتغيرات البيئة القديمة. احتفظ بالمفتاح على الخادم وفي مدير الأسرار (secret manager)، ولا تضعه أبداً في كود جانب العميل.

اختر معرف النموذج واقرأ سعره

لا ينبغي أن يفترض الترحيل معرف نموذج أو سعراً. كلاهما موجود في واجهة برمجة تطبيقات النماذج. قرأنا https://api.tokenlab.sh/v1/models/gpt-5.5 و https://api.tokenlab.sh/v1/models/laguna-s-2.1 في 2026-10-03. تم تحديث تسعير كليهما آخر مرة في 2026-10-02T16:53:30.068Z.

الحقل	gpt-5.5	laguna-s-2.1
مرحلة دورة الحياة	نشط	نشط
الحد الأقصى لـ tokens المدخلات / المخرجات	1,000,000 / 128,000	1,048,576 / 131,072
تنسيقات الطلبات المقبولة	openai_chat_completions, openai_responses	openai_chat_completions
القدرات المدرجة	البرمجة، json-mode، prompt-cache، الاستدلال، استخدام الأدوات، الرؤية	استخدام الأدوات
المدخلات، دولار لكل مليون token	1.5	0.1
المخرجات، دولار لكل مليون token	9	0.2
قراءة الكاش، دولار لكل مليون token	0.15	0.01

المصادر: gpt-5.5 و laguna-s-2.1، كلاهما تمت ملاحظتهما في 2026-10-03.

لتحويل هذه المعدلات إلى رقم، إليك تقديراً مع توضيح الطريقة. خذ مهمة بها مليون token للمدخلات و100 ألف token للمخرجات، مع عدم وجود نتائج في الكاش.

• gpt-5.5: 1 × 1.50 دولار + 0.1 × 9.00 دولار = 1.50 دولار + 0.90 دولار = 2.40 دولار.
• laguna-s-2.1: 1 × 0.10 دولار + 0.1 × 0.20 دولار = 0.10 دولار + 0.02 دولار = 0.12 دولار.

هذه تقديرات من معدلات لكل token مدرجة. رسومك النهائية هي سجل الاستخدام (Usage record). تختلف عملية الـ tokenization حسب النموذج، لذا فإن نفس النص ينتج أعداداً مختلفة من الـ tokens على نماذج مختلفة.

نحن لا ندعي وجود توفير هنا. للمقارنة مع ما تدفعه اليوم، ضع معدلات TokenLab بجانب فاتورة OpenAI الخاصة بك، أو صفحة تسعير OpenAI، في اليوم الذي تقوم فيه بالتبديل. تتغير الأسعار، ويقول دليل الفوترة (تمت ملاحظته في 2026-10-03) ألا تقوم بترميز جدول أسعار منسوخ. إنه يشير إلى GET /v1/models/:model/pricing للحصول على القيم الحالية.

تتبع معرفات النماذج الأخرى نفس النمط. تستخدم أمثلة الوثائق gpt-5.6-terra و gpt-5.6-luna لـ Chat Completions، و claude-sonnet-5 و gemini-3.5-flash على مساراتها الخاصة. اقرأ التنسيقات المقبولة لكل نموذج قبل توجيه حركة المرور إليه. للمقارنات الأوسع، راجع دليل النماذج، ومقارنة OpenRouter و TokenLab، وتصنيفات النماذج. يمكن لفرق الصور والفيديو البدء بـ أفضل واجهة برمجة تطبيقات لنماذج الصور بالذكاء الاصطناعي 2026 و أفضل واجهة برمجة تطبيقات لنماذج الفيديو بالذكاء الاصطناعي 2026. لمهام البرمجة، راجع أفضل نماذج الذكاء الاصطناعي للبرمجة.

ما يجب التحقق منه تالياً عند الهجرة من OpenAI إلى TokenLab

توثق TokenLab أن OpenAI SDK يعمل مع Chat Completions و Responses. هذا توافق مع تنسيق الطلب والاستجابة، وليس وعداً بأن كل نموذج يتصرف بنفس الطريقة. يقول دليل تنسيقات API (تمت ملاحظته في 2026-10-03) أن المعلمات الاختيارية تعتمد على النموذج. كما يقول إن النموذج لا يقبل بالضرورة جميع تنسيقات API الأربعة، ويظهر tokenlab.accepted_request_formats ما يقبله. تعامل مع كل مجال أدناه كشيء يجب اختباره بحركة المرور الحقيقية الخاصة بك.

البث (Streaming)

يرسل stream: true أجزاء الرسالة الجزئية كأحداث مرسلة من الخادم (server-sent events). اضبط stream_options مع include_usage: true لتلقي استخدام الـ token في أجزاء البث، كما يوثق مرجع إنشاء Chat Completion (تمت ملاحظته في 2026-10-03).

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Count to five."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

سلوكان يجب التخطيط لهما. إذا تمت مقاطعة البث بعد وصول المخرجات، فلا تعامله كاستجابة كاملة. يحذر دليل معالجة الأخطاء (تمت ملاحظته في 2026-10-03) من أن تكراره قد ينتج مخرجات مختلفة أو رسوماً ثانية. ويمكن أن ينتهي البث قبل انتهاء الفوترة، لذا قد يكون معرف الفوترة غائباً.

استدعاءات الأدوات (Tool calls)

يسرد مرجع Chat Completions كلاً من tools و tool_choice و parallel_tool_calls. ويقول إن الاستدعاءات المتوازية تعمل "عندما يدعمها النموذج المختار". تم توثيق استدعاء الوظائف (Function calling) على أنه "مدعوم من قبل النموذج المختار"، لذا تحقق من قائمة القدرات. في الجدول أعلاه، يسرد كل من gpt-5.5 و laguna-s-2.1 استخدام الأدوات، ولكن gpt-5.5 فقط يسرد json-mode والرؤية. أرسل مخططات الأدوات الحقيقية الخاصة بك، وليس مثالاً تجريبياً، وتحقق من أن الوسائط المرجعة يتم تحليلها بشكل صحيح.

إذا كنت تخطط لاستدعاء نماذج Claude، لاحظ قاعدة دليل الترحيل. استدعاءات أدوات Claude، وكتل التفكير، وحقول رسائل Anthropic تنتمي إلى /v1/messages، ولا تضمن Chat Completions عملها.

أشكال الأخطاء

تُرجع Chat Completions و Responses كائن error بنمط OpenAI. وفقاً لدليل معالجة الأخطاء، فإن message و type فقط هما الموجودان دائماً. تظهر حقول مثل code و param و retryable و retry_after عند الحاجة. تفرع بناءً على حالة HTTP و code، وليس على نص الرسالة، واجعل المحلل الخاص بك يتحمل الحقول المفقودة. تحتفظ رسائل Anthropic و Gemini بتنسيقات الأخطاء الخاصة بها، لذا لن يغطي محلل واحد كل مسار.

الحالة	الكود	ماذا يعني
401	invalid_api_key	المفتاح مفقود، غير صالح، غير نشط أو تم إلغاؤه
401	expired_api_key	انتهت صلاحية المفتاح
402	insufficient_balance	رصيد الحساب لا يمكنه تغطية الطلب
402	quota_exceeded	تم الوصول إلى حد استخدام المفتاح نفسه
403	model_not_allowed	لا يمكن لهذا المفتاح استخدام النموذج المطلوب
429	rate_limit_exceeded	طلبات كثيرة جداً؛ انتظر Retry-After

المصادر: المصادقة و معالجة الأخطاء، تمت ملاحظتها في 2026-10-03.

يصحح هذا الجدول افتراضاً شائعاً. الرصيد الفارغ هو 402، وليس 401. إذا كان الكود الحالي الخاص بك يعامل كل 4xx كـ مفتاح سيء، فقم بتحديثه.

المهلات الزمنية وإعادة المحاولة

يقول دليل الترحيل إن كود إعادة المحاولة والمهلة والبث الحالي يمكن أن يبقى عادةً. راجعه مقابل قواعد إعادة المحاولة الموثقة.

• لا تكرر استجابات 400، 401، 402، 403، 404 أو 413 دون تغيير.
• أعد محاولة 429 بعد التأخير الذي يوفره الخادم.
• أعد محاولة 500–504 فقط عندما يكون retryable هو true، واحترم retry_after.
• يمكن أن يعود 503 all_channels_failed مع retryable: false. في هذه الحالة، العملية ليس لها مورد في طبقة التسليم المختارة، لذا فإن تكرارها لن يساعد.

احفظ معرف الطلب (Request ID) من رؤوس الاستجابة مع النموذج ومعرف المهمة الخاص بك. إنه ما تحتاجه للتحقيق.

الفوترة

يعمل رصيد واحد عبر النماذج، بدون اشتراك أو حد أدنى للإنفاق، وفقاً لدليل الفوترة. يتم محاسبة كل طلب مكتمل مرة واحدة، لخيار التسليم الذي أنتجه. الخيارات هي TokenLab Verified و Official و Auto، ويجرب Auto خيار Verified أولاً، ثم Official. اضبط حد إنفاق على كل مفتاح API إذا كنت تريد إيقافاً نهائياً. عند الوصول إلى الحد، تُرجع الطلبات بهذا المفتاح 402.

تتضمن استجابات OpenAI المتوافقة غير المتدفقة billing_transaction_id عندما تنتهي الفوترة قبل إرسال الاستجابة. قد تظهر أيضاً في رأس X-Billing-Transaction-ID. قم بتخزينه، وقم بالمطابقة مقابل صفحة الاستخدام بدلاً من حسابات الـ token الخاصة بك.

قائمة التحقق من التحقق بعد الهجرة من OpenAI إلى TokenLab

قم بتشغيل هذه بالترتيب مقابل مفتاح تجريبي (staging key) قبل نقل حركة مرور الإنتاج. يتتبع كل صف سلوكاً موثقاً أعلاه.

الخطوة	ما يجب تشغيله	ما يجب أن تراه
1. اكتشاف النموذج	GET /v1/models/gpt-5.5 (لا حاجة لمفتاح)	دورة الحياة active والتنسيقات المقبولة التي تخطط لاستخدامها
2. طلب مصادق	نموذج Python أو cURL أعلاه	إجابة غير فارغة؛ يظهر الطلب في عرض الطلبات مع النموذج والحالة والاستخدام
3. حقول الاستخدام	اقرأ usage في استجابة غير متدفقة	prompt_tokens, completion_tokens, total_tokens
4. البث	stream: true مع include_usage: true	أجزاء SSE، ثم الاستخدام؛ يتم التعامل مع البث المتقطع كغير مكتمل
5. استدعاءات الأدوات	tools و tool_choice الحقيقية الخاصة بك	يتم تحليل الوسائط ومطابقتها لمخططك
6. الرؤية أو وضع JSON	فقط إذا كان النموذج يسرد vision أو json-mode	المخرجات المتوقعة؛ تخطَّ الاختبار إذا لم تكن القدرة مدرجة
7. مفتاح سيء	طلب بمفتاح محذوف أو خاطئ	401 invalid_api_key
8. لا يوجد رصيد أو حد مفتاح	استخدم مفتاحاً بحد منخفض أو مساحة عمل فارغة	402 insufficient_balance أو quota_exceeded
9. تقييد النموذج	قيد قائمة نماذج المفتاح، ثم اطلب نموذجاً آخر	403 model_not_allowed
10. المهلة وإعادة المحاولة	فرض مهلة في بيئة الاختبار	يعيد الكود الخاص بك المحاولة فقط وفقاً لـ retryable و retry_after
11. الفوترة	قارن billing_transaction_id والاستخدام بتقديرك	تطابق الرسوم سعر النموذج الحالي والـ tokens المسجلة

بعد اجتياز الجدول، قم بتغيير تكوين الإنتاج الخاص بك وقم بالنشر. احتفظ بمفتاح OpenAI القديم نشطاً حتى يؤكد الاستخدام أن المسار الجديد مستقر.

أسئلة شائعة

هل أحتاج إلى تغيير أسماء نماذجي عند التبديل من OpenAI؟

ليس بالضرورة، ولكن أكد كل واحد منها. معرفات نماذج TokenLab هي سلاسل دقيقة، لذا تحقق منها باستخدام GET /v1/models أو GET /v1/models/{model}. في 2026-10-03، أدرجت واجهة برمجة التطبيقات المباشرة gpt-5.5 كـ active. إذا أرجع طلب model_not_found، فإن المعرف غير معروف أو غير متاح. اقرأ قائمة النماذج واستخدم معرفاً حالياً.

هل سيتصرف البث واستدعاءات الأدوات تماماً مثل API الخاص بـ OpenAI؟

توثق TokenLab البث من خلال SSE واستدعاء الوظائف من خلال تنسيق الطلب المتوافق مع OpenAI. تقول الوثائق أيضاً إن الخيارات المدعومة تعتمد على النموذج المختار. لذلك نتعامل مع النتيجة على أنها متوافقة، وليست متطابقة. اختبر البث، و tools، و tool_choice وأي response_format تستخدمه مع النموذج المحدد الذي تخطط لتشغيله.

ما هو كود الحالة الذي أحصل عليه عندما ينفد رصيدي؟

تحصل على HTTP 402 مع الكود insufficient_balance. المفتاح الذي وصل إلى حد إنفاقه الخاص يُرجع أيضاً 402، مع quota_exceeded. المفتاح المفقود أو غير الصالح أو الذي تم إلغاؤه يُرجع 401. لا تكرر أياً من هذه دون تغيير. قم بزيادة الرصيد، أو رفع حد المفتاح، أو استبدال المفتاح.

هل يمكنني استدعاء نماذج Claude أو Gemini من نفس عميل OpenAI؟

يسرد كتالوج النماذج claude-sonnet-5 و gemini-3.5-flash مع openai_chat_completions ضمن تنسيقات طلباتها. لذلك يمكن للدردشة الأساسية أن تمر عبر نفس العميل. الحقول الخاصة بـ Claude مثل كتل التفكير واستخدام أدوات Claude تنتمي إلى /v1/messages. تبقى الحقول الأصلية لـ Gemini على مسار /v1beta. احتفظ بتنسيق API واحد لكل محادثة.

ابدأ البناء على TokenLab

أنشئ مفتاحاً على TokenLab، واضبط الـ base URL على https://api.tokenlab.sh/v1، وقم بتشغيل طلب البدء السريع قبل لمس الإنتاج.