مرجع API

Claudin.io هي واجهة برمجة تطبيقات متوافقة مع OpenAI. إذا كنت قد استخدمت OpenAI API، فكل شيء هنا مألوف لديك — فقط وجّه إلى عنوان Claudin.io الأساسي واستخدم نموذج claudinio.

عنوان URL الأساسي

https://api.claudin.io

توجد مسارات بنمط OpenAI تحت /v1.

المصادقة

أرسل مفتاح API الخاص بك مع كل طلب، كأحد الترويسات التالية:

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY

النموذج

معرف النموذج	نافذة السياق
claudinio	256K رمز

استخدم claudinio في كل مكان. (تتوقع بعض برامج العملاء صيغة provider/model — بالنسبة لها، استخدم claudinio/claudinio.)

نقاط النهاية

المسار والطريقة	الوصف
POST /v1/chat/completions	إكمال المحادثة — نقطة النهاية الأساسية
POST /v1/completions	إكمال النص القديم
POST /v1/messages	صيغة رسائل Anthropic
POST /v1/responses	Responses API (Codex)
POST /v1/embeddings	تضمينات النص
GET /v1/models	قائمة النماذج المتاحة

إكمال المحادثة

curl https://api.claudin.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claudinio",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Write a haiku about proxies."}
    ],
    "temperature": 0.7
  }'

يتم دعم معاملات OpenAI القياسية: messages وtemperature وtop_p وmax_tokens وstream وstop وtools / tool_choice (استدعاء الدوال) وresponse_format وغيرها. هناك معاملان لهما حدود يجدر بك معرفتها قبل إرسالهما: max_tokens مُقيَّد بين حد أدنى وحد أقصى، وn يجب أن يكون 1.

max_tokens والاستدلال

نماذج Claudinio تستدل قبل أن تجيب، وتُحتسب رموز الاستدلال ضمن max_tokens — نفس الميزانية تغطي سلسلة التفكير الداخلية والرد المرئي. لذلك يمكن إنفاق قيمة صغيرة من max_tokens بالكامل تقريبًا على الاستدلال، مما يترك الإجابة مقطوعة في منتصف الجملة.

لمنع ذلك، يتم رفع القيم الأقل من 32000 تلقائيًا إلى 32000. وفي الطرف الآخر، يتم خفض القيم الأعلى من 393216 إلى 393216 — الحد الأقصى الذي تقبله النماذج — لأن الرقم الأكبر يُرفض تمامًا بدلاً من معاملته باعتباره "بقدر ما تشاء". أي قيمة بينهما تمر دون تغيير، وحذف المعامل جائز دائمًا.

max_tokens هو سقف، وليس حجزًا: لا تُدفع إلا مقابل الرموز المولّدة فعليًا، لذا فإن القيمة السخية لا تكلف شيئًا إضافيًا.

إذا كنت تحلل مخرجات منظمة (JSON أو XML أو تنسيق صارم)، فتحقق من finish_reason قبل التحليل — يعني "length" أن الاستجابة وصلت إلى حد الرموز وهي غير مكتملة، لذا فإن فشل التحليل متوقع وليس مشكلة في نموذج معطوب:

choice = response.choices[0]
if choice.finish_reason == "length":
    ...  # truncated — retry with a larger max_tokens
data = json.loads(choice.message.content)

إكمالات متعددة (n)

يتم دعم n = 1 فقط. إرسال n أكبر من 1 يُرجع 400 مع "code": "unsupported_parameter"؛ حذف المعامل آمن دائمًا.

نماذج Claudinio تستدل قبل أن تجيب، وتنتج عملية الاستدلال سطرًا واحدًا من التفكير — لا توجد طريقة رخيصة لتفرعها إلى عدة مرشحين مستقلين، لذا لا يقدم المزوّدون الأساسيون ذلك. إذا كنت تريد أكثر من مرشح واحد، أرسل الطلب أكثر من مرة (درجة حرارة temperature أعلى تمنحك تنوعًا)، ولاحظ أن كل واحد يُحتسب على حدة.

نرفض n > 1 بدلاً من إرجاع اختيار واحد بهدوء: العميل الذي طلب أربعة واستلم واحدًا يفشل عادةً لاحقًا، داخل كوده الخاص، دون أي خطأ منا يوضح السبب.

البث

عيّن "stream": true لاستلام أحداث مرسلة من الخادم بصيغة بث OpenAI (أجزاء data: {...} تنتهي بـ data: [DONE]).

استدعاء الأدوات / الدوال

يدعم claudinio استدعاءات الأدوات. مرّر tools واقرأ tool_calls من الاستجابة، تمامًا كما هو الحال مع OpenAI API. هذا ما يجعلها تعمل داخل المحررات الوكيلية مثل Claude Code وKilo وCursor.

الإدخال متعدد الوسائط

claudinio هو نموذج نصي، لكن Claudin.io يتعامل بشفافية مع كتل الصور والصوت والفيديو: إذا أرسلتها، يحوّلها الوكيل إلى أوصاف/نسخ نصية قبل أن يراها النموذج. لا تحتاج إلى فعل أي شيء خاص — أرسل كتل المحتوى القياسية بنمط OpenAI وسيعمل الأمر تلقائيًا.

الأخطاء

تتبع الأخطاء صيغة أخطاء OpenAI:

{ "error": { "message": "…", "type": "…", "code": "…" } }

الحالة	المعنى	ما يجب فعله
401	مفتاح API غير صالح أو مفقود	تحقق من المفتاح وترويسة المصادقة
403	نقطة النهاية غير مسموحة	استخدم أحد مسارات /v1/* المدعومة
402	لا يوجد اشتراك نشط	اشترك — إعادة المحاولة لن تساعد
429	تم الوصول إلى حد الميزانية أو تقييد المعدل	انتظر إعادة تعيين النافذة (انظر ترويسة Retry-After) أو رقِّ خطتك
400	طلب غير صالح البنية	تحقق من JSON / المعاملات — انظر max_tokens وn
5xx	خلل مؤقت في المزود/الجهة العلوية	أعد المحاولة مع التراجع التدريجي

تفاصيل المزود مخفية عن قصد

يتم تنظيف رسائل الخطأ حتى لا تكشف عن مزود النموذج الأساسي. سترى دائمًا أخطاء Claudin.io بصيغة OpenAI.

الوصول إلى حد الميزانية

عندما تستنفد حماية الإنفاق للنافذة الحالية، تُرجع الطلبات 429 مع ترويسة Retry-After تعطي الثواني حتى إعادة تعيين النافذة. تُظهر لوحة التحكم الوقت الدقيق لإعادة التعيين والميزانية المتبقية. تراجع بناءً على تلك الترويسة بدلاً من إعادة المحاولة فورًا. انظر الخطط والحدود لمعرفة كيفية عمل النوافذ.

رسالة بدل الرمز 429

في عدد صغير من الحسابات نجرّب ردًّا مختلفًا على الموقف نفسه. فبدل الخطأ يكتمل الطلب، ويشرح الردّ نفسه أن الحدّ قد بُلغ ومتى تُعاد تهيئته. نحن نقيس ما إذا كانت المعلومة تصل إلى الأشخاص بهذه الطريقة على نحو أوثق من خطأ يبتلعه وكيلهم بصمت — وما إذا كانوا، حين يُقال لهم ذلك بوضوح، يفضّلون الانتقال إلى خطة على مقاسهم.

إن كنت تبني أتمتة، فلا تقرأ الرمز 2xx على أنه "أُنجز العمل". تعامل مع أي ردّ يقول إن الحدّ قد بُلغ على أنه بلوغ فعلي للحدّ، وتوقّف حتى تُعاد تهيئة النافذة. يبقى الرمز 429 أعلاه هو السلوك الافتراضي، وهو ما تتلقاه كل الحسابات تقريبًا.

تحديد المعدل

لا تفرض Claudin.io حظرًا صارمًا على الاستخدام العادي. معدلات الطلبات المسيئة تُبطَّأ (خنق شفاف) بدلاً من رفضها، لذا لا يُعاقب حسنو السلوك أبدًا. عمليًا لا تحتاج إلى فعل أي شيء — فقط أعد المحاولة في الحالات النادرة لـ 429.