واجهة API متوافقة مع OpenAI

ما هي

تتيح واجهة API المتوافقة مع OpenAI لأي أداة تتعامل مع تنسيق chat completions في OpenAI استخدام نماذج الدردشة في ToRun، مع الدفع من حسابك في ToRun. يستطيع وكيل برمجة مثل opencode استخدام ToRun بوصفه مزوّد النماذج الخاص به، إلى جانب أدوات MCP من ToRun.

العنوان وتسجيل الدخول

استخدم مفتاح المطوّر نفسه الذي تستخدمه لخادم MCP: راجع مفاتيح المطوّر. المفتاح الذي أُنشئ قبل إضافة واجهة API المتوافقة مع OpenAI يتلقى الرد 403 insufficient_scope. صلاحيات المفتاح لا تتغير أبدًا، لذا أنشئ مفتاحًا جديدًا.

للواجهة نقطتا نهاية: GET /v1/models وPOST /v1/chat/completions. أي مسار آخر تحت /v1 يردّ بـ 404 not_found.

النماذج

يعرض GET /v1/models النموذج torun/auto أولًا، ثم كل نموذج نصي تستطيع خطتك استخدامه، بمعرّف النموذج. ويذكر كل نموذج:

• كمية النص التي يستطيع قراءتها (context_length) وطول الرد الذي يستطيع كتابته (max_completion_tokens)،
• هل يستطيع استدعاء الأدوات (supports_tools) وقراءة الصور (supports_vision)،
• سعره بوحدات Runs لكل مليون رمز (pricing: input وoutput).

يتيح torun/auto لـ ToRun اختيار نموذج لكل طلب: نموذج يقرأ الصور عندما يحتوي الطلب على صورة، ونموذج يستدعي الأدوات عندما يرسل tools.

Chat completions

يقبل POST /v1/chat/completions:

• messages بالأدوار system وdeveloper (يُعامَل معاملة system) وuser وassistant وtool،
• tools وtool_choice (auto أو none أو required أو دالة واحدة مسمّاة): تعود أدوات أداتك الخاصة إليها كاستدعاءات أدوات، ولا يشغّلها ToRun أبدًا،
• response_format مع json_object. يُقبل json_schema ويأتي الرد بتنسيق JSON، لكن المخطط نفسه لا يُفرض،
• temperature (من 0 إلى 2)، وtop_p (من 0 إلى 1)، وmax_completion_tokens أو max_tokens، وstop (حتى 4 تسلسلات)، وseed، وreasoning_effort،
• stream وstream_options.include_usage.

قيمة n أكبر من 1، وlogprobs، وtop_logprobs، والصوت، وأي مخرجات غير النص تُرفض بالرد 400 unsupported_parameter بدلًا من تجاهلها.

الصور

أرسل الصورة مضمّنة، بصيغة data:image/...;base64,... في جزء image_url، حتى 20 ميغابايت لكل طلب. الصورة المرسلة كرابط تُرفض بالرد 400 image_url_not_supported: لا يجلبها ToRun. تخضع الصور لفحص الأمان، كما في التطبيق.

البث

مع "stream": true يصل الرد كأحداث server-sent events بشكل chat.completion.chunk:

• يحمل الجزء الأول الدور assistant، وتُبث استدعاءات الأدوات مع index الخاص بها.
• عندما لا يكون هناك ما يُرسل، يصل سطر تعليق : keepalive كل 15 ثانية؛ ويتخطاه محللو SSE.
• ينهي data: [DONE] البث الذي نجح.
• مع stream_options.include_usage، يكون للجزء الأخير choices فارغ ويحمل usage.
• يصل الفشل بعد بدء البث كحدث واحد data: {"error": ...}، دون [DONE].

يُوقف الاستدعاء بلا بث بعد 110 ثوانٍ بالرد 504 timeout. أرسل الطلبات الطويلة مع "stream": true.

الاستخدام

يحمل usage القيم prompt_tokens وcompletion_tokens وtotal_tokens وprompt_tokens_details.cached_tokens وcompletion_tokens_details.reasoning_tokens، إضافةً إلى torun_credits: تكلفة الاستدعاء بوحدات Runs.

استخدامها في opencode

يضيف إعداد opencode الموجود في صفحة المطورين ToRun كمزوّد نماذج إلى جانب خادم MCP:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "torun": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ToRun",
      "options": { "baseURL": "https://mcp.torun.ai/v1", "apiKey": "{env:TORUN_API_KEY}" },
      "models": { "torun/auto": { "name": "ToRun Auto" } }
    }
  }
}

تعمل أي أداة أخرى تتعامل مع واجهة الدردشة في OpenAI بالطريقة نفسها. يعرض تبويب OpenAI API في الصفحة هذا الاستدعاء:

curl https://mcp.torun.ai/v1/chat/completions \
  -H "Authorization: Bearer $TORUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "torun/auto", "messages": [{"role": "user", "content": "Hello"}]}'

كيف تُدفع الاستدعاءات

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

الحدود

يستطيع كل مفتاح إرسال 60 طلبًا في الدقيقة إلى هذه الواجهة وتشغيل 4 عمليات completions في الوقت نفسه. وفوق ذلك تردّ الواجهة بـ 429 rate_limit_exceeded مع ترويسة Retry-After.

الأخطاء

لكل خطأ الشكل {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. تأتي message باللغة التي تطلبها ترويسة Accept-Language في الطلب.

الطلب الذي لا يمكن دفع ثمنه يتلقى الرد 402، وليس 429، حتى لا يواصل العميل إعادة محاولته.