البدء

دليل البدء السريع

قم بإجراء أول طلب API لـ TokenLab باستخدام cURL أو Python أو JavaScript أو Go أو PHP. قم بإعداد مفتاح API الخاص بك، وتهيئة نقطة النهاية (endpoint)، والتحقق من استجابة Chat Completions.

الحصول على مفتاح API

إنشاء حساب

سجّل في tokenlab.sh باستخدام بريدك الإلكتروني أو حساب Google أو GitHub الخاص بك.

إنشاء وحفظ مفتاح API

افتح API Keys في مساحة العمل الخاصة بك. قم بإنشاء مفتاح واحفظ قيمته الكاملة على الفور؛ حيث يتم عرضها مرة واحدة فقط. إذا كنت قد حفظت مفتاحاً كاملاً بالفعل، فاستخدم تلك القيمة. البادئة التي تظهر أو يتم نسخها من القائمة لا يمكنها مصادقة الطلبات.

التحقق من رصيد مساحة العمل

تحقق من رصيدك في Billing. قد يحصل الحساب الجديد على رصيد تجريبي لمرة واحدة؛ بخلاف ذلك، يبدأ الرصيد بـ 0 دولار ويحتاج إلى شحن (بحد أدنى 5 دولارات) قبل إجراء الطلب الأول. تتم محاسبة الطلب بالسعر الحالي للنموذج المختار.

حافظ على سرية مفتاح API. لا تضعه في كود جهة العميل (client-side code) أو في مستودع عام.

تعيين المفتاح لهذه المحطة الطرفية (Terminal)

الأوامر أدناه تبقي المفتاح بعيداً عن الأمر نفسه. فهي تعينه فقط للمحطة الطرفية الحالية وعملياتها الفرعية. استخدم مدير أسرار (secret manager) للتطبيقات المنشورة.

printf 'TokenLab API key: '
read -r -s TOKENLAB_API_KEY
printf '\n'
export TOKENLAB_API_KEY

تثبيت عميل (Client)

pip install openai

إرسال طلبك الأول

بالنسبة لمعظم عمليات التكامل الجديدة، ابدأ بـ Chat Completions على POST /v1/chat/completions.

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

احفظ أحد أمثلة SDK باسم quickstart.py أو quickstart.mjs أو main.go أو quickstart.php، ثم قم بتشغيل python quickstart.py أو node quickstart.mjs أو go run . أو php quickstart.php. تستخدم Python و JavaScript و Go مكتبات OpenAI SDK الرسمية؛ بينما يستخدم PHP عميل OpenAI PHP client الذي يديره المجتمع (PHP 8.2+).

استخدم POST /v1/responses فقط عندما تحتاج إلى سلوك خاص بـ Responses. يعتمد دعم الحقول الخاصة بـ Responses فقط على النموذج المختار.

تأكيد النتيجة

يُرجع الطلب الناجح إجابة غير فارغة. افتح Runs في نفس مساحة العمل للتحقق من النموذج والحالة والاستخدام. في حالة وجود أخطاء، اتبع استكشاف الأخطاء وإصلاحها. يعد تغيير النموذج أو إضافة البث (streaming) خطوة تالية منفصلة في دليل SDK.

لماذا يُرجع طلبي الأول 402؟

يعتمد نجاح طلبك الأول على الرصيد الموضح في Billing. أثناء فترة العرض التجريبي، يحصل الحساب الجديد المؤهل على 0.25 دولار لمرة واحدة، لما يصل إلى 10 طلبات خلال 7 أيام؛ الطلب الحادي عشر يُرجع 402 ويشير إلى استنفاد طلبات الفترة التجريبية المجانية، حتى لو تبقى القليل من الرصيد. الحساب الذي يبلغ رصيده 0 دولار يحصل على HTTP 402 مع رمز الخطأ insufficient_balance. قم بشحن ما لا يقل عن 5 دولارات في Billing؛ 5 دولارات هي الحد الأدنى للشحن. ثم أرسل نفس الطلب مرة أخرى. لست بحاجة إلى مفتاح API جديد: المفتاح الذي أنشأته سيستمر في العمل بمجرد تغطية الرصيد للطلب.

تكلفة طلب الاختبار الأول ضئيلة جداً. طلب مثال واحد إلى deepseek-v4.1-flash يكلف أقل بكثير من 0.01 دولار.

إذا كان لديك رصيد بالفعل، فإن رسالة 402 توضح المبلغ الذي يحتاجه الطلب وما هو رصيدك الحالي. يحتجز TokenLab تكلفة max_tokens الكاملة قبل بدء الطلب، لذا قد يحتاج الإدخال الطويل أو max_tokens الكبير إلى رصيد أكبر من الرصيد الصغير. في /v1/chat/completions و /v1/messages، عندما يكون max_tokens أصغر مناسباً، توفر الرسالة أيضاً القيمة التي يجب خفضه إليها. عندما تكون تكلفة الإدخال وحده أكثر من رصيدك، فإنه يطلب تقصير الإدخال بدلاً من ذلك.

المفتاح الذي يصل إلى حد الإنفاق الخاص به يُرجع أيضاً 402 مع الرمز quota_exceeded. قم بزيادة أو إزالة الحد تحت API Keys. للتعامل مع 402 في الكود، راجع معالجة الأخطاء.

استمر في البناء

في هذه الصفحة