لعملاء الذكاء الاصطناعي: تعليمات الإعداد خطوة بخطوة — /docs/agents.md، فهرس الوثائق — /llms.txt.

مرجع API

كل ما يتعلق بالطلبات المرسلة إلى البوابة: البروتوكولات والعناوين والمفاتيح والمعاملات. أدناه — البث، واستدعاء الأدوات، والاستدلال، والإضافات، وتكلفة الطلب في الاستجابة.

تقبل البوابة تنسيقي OpenAI وAnthropic. العنوان الأساسي لـ SDK OpenAI هو https://gate.joingonka.ai/v1نسخ، ولـ SDK Anthropic هو https://gate.joingonka.aiنسخ. تعمل جميع البروتوكولات بالمفتاح نفسه والرصيد نفسه: الطلب بأي تنسيق يسلك المسار ذاته.

عناوين مرجعية#

تستجيب دون مفتاح. جدول النماذج مع السياق والحالة — في قسم النماذج.

Anthropic Messages#

• العنوان الأساسي هو https://gate.joingonka.aiنسخ: ستضيف حزمة SDK المسار /v1/messages تلقائيًا.
• المفتاح في الترويسة x-api-key (كما ترسله SDK Anthropic) أو Authorization: Bearer.
• تستبدل البوابة نماذج claude-* بالنموذج المُوصى به (MiniMaxAI/MiniMax-M2.7); ويبقى في الحقل model من الرد الاسم الذي أرسله العميل.
• max_tokens إلزامي كما في API Anthropic؛ وما يتجاوز سقف النموذج يُقتطع.
• البث — أحداث Anthropic؛ في فترات التوقف ترسل البوابة event: ping، ويصل الخطأ عبر الحدث event: error.
• لا تظهر استدلالات النموذج في الرد: لا توجد كتل thinking.
• الأداة المدمجة web_search تنفّذها إضافة البحث في الويب الخاصة بالبوابة — راجع قسم الإضافات.
• لا يوجد عدّ للرموز (/v1/messages/count_tokens) — الرد 404.

أسهل طريقة لإعداد Claude Code هي عبر المثبّت — ربط الأدوات. يدويًا عبر متغيرات البيئة؛ وANTHROPIC_MODEL يثبّت نموذج الشبكة.

export ANTHROPIC_BASE_URL=https://gate.joingonka.ai
export ANTHROPIC_AUTH_TOKEN=$JOINGONKA_API_KEY
export ANTHROPIC_MODEL=MiniMaxAI/MiniMax-M2.7
claude

curl https://gate.joingonka.ai/v1/messages \
  -H "x-api-key: $JOINGONKA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What is Gonka?"}]
  }'

OpenAI Responses#

• لا تحفظ البوابة الردود: أرسل السجل كاملًا في input. الحقلان previous_response_id وconversation — خطأ 400 مع رمز.
• يُقبل store ولا يغيّر شيئًا.
• الأدوات: function وweb_search — الأخيرة تنفّذها إضافة البحث في الويب. تتجاهل البوابة الأدوات المدمجة الأخرى ويُنفَّذ الطلب بدونها؛ وطلب أداة كهذه عبر tool_choice — خطأ 400.
• الأجزاء input_image وinput_file — خطأ 400: نماذج الشبكة تعمل بالنص فقط.
• عناوين الحالة (GET /v1/responses/{id}, DELETE /v1/responses/{id}, GET /v1/responses/{id}/input_items, POST /v1/responses/{id}/cancel, POST /v1/responses/compact) ترد بـ 404 مع رمز — فالبوابة لا تحفظ الردود.
• Codex CLI: عيّن معرّف المزوّد الخاص بك في model_provider (وليس openai) — حينها يضغط Codex السجل بنفسه دون /v1/responses/compact.

Legacy Completions#

• prompt — سلسلة أو مصفوفة من سلسلة واحدة؛ والرد في choices[].text. عدة موجّهات أو رموز بدل النص — خطأ 400.
• يُمرَّر suffix إلى النموذج كتلميح في الموجّه: لا تملك الشبكة ملءًا حقيقيًا للوسط.
• في الرد logprobs: null؛ وbest_of يُتجاهل؛ وecho يعمل.

يُمرَّر المفتاح في الترويسة Authorization: Bearer jg-… أو x-api-key: jg-… — على كل العناوين. يُنشأ المفتاح بعد التسجيل من صفحة gate.joingonka.ai/keys.

• يمكنك وضع حد للإنفاق على كل مفتاح في لوحة الحساب: يوميًا وشهريًا وإجماليًا؛ وتجاوزه — 402 child_key_limit_exceeded.
• عدد الطلبات في الدقيقة لكل مفتاح محدود — والقيم في قسم الحدود.
• بدون مفتاح لا يعمل سوى الدردشة التجريبية على الموقع: الطلب بلا مفتاح من كودك سيتلقى 402 مع is_demo.
• تُدار المفاتيح في لوحة الحساب فقط: /api/keys بمفتاح API غير متاح. الرصيد والإنفاق حسب المفتاح — API الحساب.

الطلب نفسه في أربع SDK. النموذج هو الموصى به (MiniMaxAI/MiniMax-M2.7)، والمفتاح من متغير البيئة JOINGONKA_API_KEY.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gate.joingonka.ai/v1",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gate.joingonka.ai/v1",
  apiKey: process.env.JOINGONKA_API_KEY,
});

const response = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
});
console.log(response.choices[0].message.content);

curl https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://gate.joingonka.ai",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

message = client.messages.create(
    model="MiniMaxAI/MiniMax-M2.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(message.content[0].text)

استجابة متدفقة#

import os
from openai import OpenAI

client = OpenAI(base_url="https://gate.joingonka.ai/v1", api_key=os.environ["JOINGONKA_API_KEY"])

stream = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://gate.joingonka.ai/v1", apiKey: process.env.JOINGONKA_API_KEY });

const stream = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

curl -N https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}],
    "stream": true
  }'

import os
import anthropic

client = anthropic.Anthropic(base_url="https://gate.joingonka.ai", api_key=os.environ["JOINGONKA_API_KEY"])

with client.messages.stream(
    model="MiniMaxAI/MiniMax-M2.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Gonka?"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

المعاملات التي تضمنها البوابة بنفسها في POST /v1/chat/completions — قائمة supported_parameters في استجابة capabilities:

• بدون temperature، تضع البوابة 0.7.
• بدون max_tokens، تضع البوابة القيمة الافتراضية للنموذج: بدون بث أقصر، وفي البث سقف النموذج. الأرقام حسب النموذج في قسم الحدود.

تُمرَّر إلى الشبكة كما هي#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body. البوابة لا تتحقق منها: القيمة خارج قائمة الشبكة تؤدي إلى خطأ 400 من النوع api_error.

لا تُمرَّر إلى الشبكة#

بقية الحقول تستقبلها البوابة ولا تمرّرها إلى الشبكة — مثل user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options. usage في البث تصل دائمًا.

• stream: true — استجابة بأحداث SSE؛ والحدث الأخير هو data: [DONE].
• قبل الإنهاء تصل قطعة تحتوي usage — دائمًا، حتى بدون stream_options.
• أثناء التوقف ترسل البوابة كل 15 ثانية تعليق : keep-alive — يتجاهله عملاء SSE.
• طالما لم يُفتح البث، يصل الرفض برمز استجابة عادي؛ وبعد الفتح يصل كقطعة joingonka-error.
• في delta.tool_calls — استدعاء واحد لكل قطعة: الاستدعاءات التي تدمجها الشبكة تقطعها البوابة.

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[{"index":0,"delta":{"content":"Hi"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":2,"total_tokens":14}}

data: [DONE]

قطع الخدمة في البوابة#

يمكن التعرف عليها من الحقل id:

البث في بروتوكولات أخرى#

• Anthropic Messages: أحداث من message_start إلى message_stop، وفي فترات التوقف event: ping، والخلل event: error.
• OpenAI Responses: الأحداث response.*، والخلل response.failed.
• Legacy Completions: عند الخلل — data: {"error": …}، ثم [DONE].

• صيغة OpenAI: tools و tool_choice. الصيغة القديمة functions و function_call مقبولة أيضًا — وستأتي الاستجابة بها.
• في البث — استدعاء واحد لكل قطعة: العملاء الذين يقرأون العنصر الأول فقط لا يفقدون أي استدعاء.
• السجل الذي كانت الشبكة ستردّ عليه بخطأ 400 تصلحه البوابة: الدور developer يصبح system، ومعرّفات الاستدعاء الفارغة والمكررة تحصل على معرّفات فريدة، وarguments ككائن يتحول إلى سلسلة JSON، وtype المفقود يُستكمل، والاستدعاء بلا اسم يُحذف مع نتيجته.
• الاستدعاء الذي كتبه النموذج كترميز في النص تنقله البوابة إلى tool_calls؛ والاستدعاءات الزائفة في ردّ على طلب بلا أدوات تحذفها.
• انقطع التوليد في منتصف الوسائط — ستصلك finish_reason: length، لا tool_calls: ارفع حد الاستجابة.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

قيود JSON-Schema#

مخططات الأدوات و response_format تترجمها الشبكة إلى قواعد؛ والتعبيرات النمطية بمحرك RE2. البوابة تعيد المخطط إلى الشكل الذي تقبله الشبكة:

• $ref تُفتح في مكانها، وقسمَا $defs و definitions يُحذفان؛ والمرجع التكراري يصبح مخططًا بلا قيود.
• pattern بما يحتويه من تراكيب غير موجودة في RE2 (النظر للأمام والخلف، والمراجع الخلفية، والمجموعات الذرية، والمحددات الكمية الاستحواذية (possessive quantifiers)) يُزال؛ والتكرارات التي تتجاوز 1000 تُقلَّص إلى 1000.
• anyOf و oneOf من الثوابت تنطوي إلى enum؛ وإذا كانت الفروع غير القابلة للطي أكثر من 16، يُزال الاتحاد.

response_format: {"type": "json_object"} — استجابة JSON صالحة، و{"type": "json_schema", "json_schema": {"name": …, "schema": …}} — وفق مخططك مع القيود أعلاه. الـ JSON المقطوع بدون بث تصلحه إضافة response-healing.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "Name three planets."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "planets",
      "schema": {
        "type": "object",
        "properties": {"planets": {"type": "array", "items": {"type": "string"}}},
        "required": ["planets"]
      }
    }
  }
}

• استدلال النموذج يأتي منفصلًا عن الاستجابة: message.reasoning_content، وفي البث delta.reasoning_content. الحقل reasoning تعيد البوابة تسميته إلى هذه الصيغة.
• الاستدلال يستهلك max_tokens: مع حد صغير تُقطع الاستجابة (finish_reason: length) قبل النص أصلًا.
• إذا لم يكن هناك نص استجابة ووُجد استدلال، تنقله البوابة إلى content — ما عدا الاستجابات التي تستدعي أداة.
• reasoning_effort و reasoning.effort تُمرَّران إلى الشبكة. وإذا كان للنموذج وضعان فقط، تُعيد البوابة القيمة إليهما: none و minimal → low، والأعلى → الاستدلال الافتراضي.
• إذا رفضت العقدة القيمة، تخفضها البوابة (max و xhigh → high، وminimal → low، وإلا تُزيل الحقل) وتعيد إرسال الطلب.
• في /v1/messages لا يُمرَّر الاستدلال — لا توجد كتل thinking.

تُفعَّل الإضافات بالحقل plugins — مصفوفة نصوص أو كائنات بخيارات. القائمة — GET /v1/plugins.

البحث في الويب#

• الخيارات: max_results — من 1 إلى 10، افتراضيًا 5؛ engine — تلميح للمحرك؛ search_prompt — نص خاص قبل النتائج؛ enabled: false — إيقاف البحث.
• المصادر — في message.annotations[].url_citation؛ وفي البث — قطعة joingonka-citations قبل الإنهاء.
• mode: "agent" — النموذج يقرر بنفسه هل يبحث وما يبحث عنه؛ max_searches — من 1 إلى 5، افتراضيًا 3.
• الدفع: في الوضع العادي — الرموز فقط (نتائج البحث تُحتسب ضمن رموز الإدخال)؛ في وضع الوكيل — رموز جميع الخطوات بالإضافة إلى 1000 nGNK عن كل عملية بحث تُنفَّذ (x_joingonka.web_search_surcharge_ngonka).
• في Anthropic Messages وOpenAI Responses، تنفّذ الأداة المدمجة web_search هذا الإضافة نفسها في وضع الوكيل.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is new in the Gonka network?"}],
  "plugins": [{"id": "web", "max_results": 5}]
}

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is new in the Gonka network?"}],
  "plugins": [{"id": "web", "mode": "agent", "max_searches": 3}]
}

الاستجابة بدون بثّ تحمل تكلفة الطلب في usage:

• في البثّ، يحتوي usage على الرموز فقط؛ أما التكلفة فتأتي في الchunk ‏joingonka-meta.
• مع الترويسة x-joingonka-meta: 1، تتلقى الاستجابة POST /v1/chat/completions كتلة x_joingonka: التكلفة (cost_ngonka)، والرصيد بعد الخصم (balance_ngonka، في وضع عدم البثّ فقط)، والتوقيتات (ttft_ms). ولا تُعيد البروتوكولات الأخرى هذه الكتلة.
• x-request-id — معرّف الطلب: أرفقه عند التواصل مع الدعم.
• تأتي Retry-After مع 429: انتظر هذا العدد من الثواني قبل إعادة المحاولة.
• تساعد الترويستان X-Title وHTTP-Referer (كما في OpenRouter) البوابة على التعرّف على تطبيقك؛ ولا يُحتفظ بنصّهما.

• الصور: تُستبدَل أجزاء image_url بنصّ بديل — فلا يرى النموذج الصورة (vision: false ضمن الإمكانات).
• من المتصفح، لا يمكن الوصول إلى الAPI إلا من نطاقات JoinGonka (فحص Origin): استدعِه من الخادم الخاص بك، ولا تضع المفتاح في الواجهة الأمامية.
• التضمينات: يُعيد POST /v1/embeddings الاستجابة 501 — لا توجد نماذج تضمين في الشبكة.
• رموز الأخطاء والحدود والمهلات — في قسم الأخطاء والحدود.