> لعملاء الذكاء الاصطناعي: تعليمات الإعداد خطوة بخطوة — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)، فهرس الوثائق — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# مرجع API

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

## البروتوكولات والعناوين

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

| الطريقة والمسار | التنسيق | الغرض | ملاحظات |
| --- | --- | --- | --- |
| `POST /v1/chat/completions` | OpenAI Chat Completions | الدردشة والوكلاء واستدعاء الأدوات | المسار الرئيسي: تحوّل البوابة بقية التنسيقات إليه. |
| `POST /v1/messages` | Anthropic Messages | Claude Code وSDK Anthropic | العنوان الأساسي بدون `/v1`؛ تُستبدل نماذج `claude-*` بالنموذج المُوصى به؛ الحقل `max_tokens` إلزامي. |
| `POST /v1/responses` | OpenAI Responses | Codex CLI وحِزم SDK OpenAI الجديدة | بلا حالة: أرسل السجل كاملًا في كل طلب. |
| `POST /v1/completions` | OpenAI Completions (legacy) | الإكمال التلقائي وتصحيح الكود في المحررات | يُمرَّر `suffix` إلى النموذج كتلميح؛ وفي الرد يأتي `logprobs: null`. |
| `POST /v1/embeddings` | OpenAI Embeddings | التمثيلات المتجهية للنص | الرد `501`: لا توجد نماذج تضمين في الشبكة. |

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

تستجيب دون مفتاح. جدول النماذج مع السياق والحالة — في قسم [النماذج](https://gate.joingonka.ai/ar/docs/models).

| الطريقة والمسار | الوصف |
| --- | --- |
| `GET /v1/models` | قائمة النماذج: السياق والأسعار والمعاملات المدعومة — الحقول بتنسيق OpenRouter. |
| `GET /v1/models/{model}` | بطاقة نموذج واحد؛ الشرطة المائلة في المعرّف — كما هي أو `%2F`. نموذج مخفي أو غير معروف — `404 model_not_found`. |
| `GET /v1/capabilities` | قدرات البوابة: المعاملات والبروتوكولات والإضافات وحقول التكلفة والحدود (`limits`). |
| `GET /v1/plugins` | الإضافات: المعرّف والاسم. |
| `GET /v1/network-status` | حالة نماذج الشبكة: التوفر وزمن الاستجابة ومدة التشغيل. |
| `GET /v1/nodes` | ملخص تجمّع العُقد: الإجمالي والنشطة والمحجورة. |
| `GET /v1/web-search/engines` | هل البحث في الويب مفعّل، وفي أي حالة محركاته. |

### 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` تنفّذها إضافة البحث في الويب الخاصة بالبوابة — راجع قسم [الإضافات](https://gate.joingonka.ai/ar/docs/api#plugins).
- لا يوجد عدّ للرموز (`/v1/messages/count_tokens`) — الرد `404`.

أسهل طريقة لإعداد Claude Code هي عبر المثبّت — [ربط الأدوات](https://gate.joingonka.ai/ar/docs#connect). يدويًا عبر متغيرات البيئة؛ و`ANTHROPIC_MODEL` يثبّت نموذج الشبكة.

#### Claude Code

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

#### cURL

```bash
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](https://gate.joingonka.ai/keys).

| البادئة | المفتاح | الطلبات إلى النماذج |
| --- | --- | --- |
| `jg-` | مفتاح الحساب العادي | نعم |
| `gc-` | مفتاح فرعي: حدود خاصة به، وتُخصم تكلفته من رصيد المالك | نعم |
| `gm-` | مفتاح إداري: لإدارة المفاتيح الفرعية فقط | لا — `403 forbidden` |

- يمكنك وضع حد للإنفاق على كل مفتاح في لوحة الحساب: يوميًا وشهريًا وإجماليًا؛ وتجاوزه — `402 child_key_limit_exceeded`.
- عدد الطلبات في الدقيقة لكل مفتاح محدود — والقيم في قسم [الحدود](https://gate.joingonka.ai/ar/docs/errors#limits).
- بدون مفتاح لا يعمل سوى الدردشة التجريبية على الموقع: الطلب بلا مفتاح من كودك سيتلقى `402` مع `is_demo`.
- تُدار المفاتيح في لوحة الحساب فقط: `/api/keys` بمفتاح API غير متاح. الرصيد والإنفاق حسب المفتاح — [API الحساب](https://gate.joingonka.ai/ar/docs/billing#account-api).

> المفتاح سرّي: لا تخزّنه في المستودع أو في كود الواجهة الأمامية، مرّره عبر متغيرات البيئة.

## أمثلة

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

### Python

```python
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)
```

### TypeScript

```typescript
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

```bash
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?"}]
  }'
```

### Anthropic SDK

```python
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)
```

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

#### Python

```python
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)
```

#### TypeScript

```typescript
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

```bash
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
  }'
```

#### Anthropic SDK

```python
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` | عشوائية الاستجابة: كلما ارتفعت زاد التنوع. |
| `top_p` | اختيار الرموز حسب الاحتمال التراكمي. |
| `top_k` | الاختيار من بين أعلى k رمزًا احتمالًا. |
| `min_p` | قطع الرموز منخفضة الاحتمال نسبةً إلى أعلى رمز احتمالًا. |
| `frequency_penalty` | عقوبة على التكرار المتكرر. |
| `presence_penalty` | عقوبة على الرموز التي ظهرت سابقًا. |
| `repetition_penalty` | معامل مضاعف ضد التكرار. |
| `stop` | السلاسل التي يتوقف عندها التوليد. |
| `seed` | بذرة لإعادة إنتاج النتيجة. |
| `max_tokens` | حد رموز الاستجابة؛ إن تجاوز سقف النموذج يُقطع إلى السقف. |
| `max_completion_tokens` | اسم آخر لـ `max_tokens`: تنقل البوابة القيمة إليه. |
| `tools` | الدوال التي يمكن للنموذج استدعاؤها، بصيغة OpenAI. |
| `tool_choice` | هل يُستدعى الدوال: باختيار النموذج، أو أبدًا، أو إلزاميًا، أو دالة محددة. |
| `response_format` | استجابة مُهيكلة: `json_object` أو `json_schema`. |

- بدون `temperature`، تضع البوابة `0.7`.
- بدون `max_tokens`، تضع البوابة القيمة الافتراضية للنموذج: بدون بث أقصر، وفي البث سقف النموذج. الأرقام حسب النموذج في قسم [الحدود](https://gate.joingonka.ai/ar/docs/errors#limits).

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

`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` — استدعاء واحد لكل قطعة: الاستدعاءات التي تدمجها الشبكة تقطعها البوابة.

```text
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`:

| `id` | متى وما يحتوي |
| --- | --- |
| `joingonka-error` | خلل بعد فتح البث: الحقل `error`، ثم انقطاع بدون `[DONE]`. |
| `joingonka-stream-stalled` | صمتت الشبكة أطول من فترة الانتظار المسموحة: يُغلق البث بـ `finish_reason: stop`. |
| `joingonka-stream-unfinished` | قطعت الشبكة التوليد: `finish_reason: length` — تابع بالطلب التالي. |
| `joingonka-citations` | مصادر البحث في الويب في `delta.annotations` — قبل الإنهاء. |
| `joingonka-meta` | التكلفة والتوقيت — فقط مع ترويسة `x-joingonka-meta: 1`. |

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

- 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`: ارفع حد الاستجابة.

```json
{
  "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`.

```json
{
  "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`.

| الإضافة | الوصف | الشروط |
| --- | --- | --- |
| `response-healing` | يصلح JSON المقطوع في استجابة النموذج. | فقط بدون بث وإذا بدأت الاستجابة بـ `{` أو `[`. |
| `privacy-sanitization` | يُخفي في الرسائل النصية: البريد الإلكتروني، و IPv4، وأرقام البطاقات، و JWT، ومفاتيح hex من 64 حرفًا، والمفاتيح بصيغة `sk-…`, `gw_…`, `gm-…`, `Bearer …`. | الوضع — الحقل `privacy_mode`: `redact` (افتراضي) أو `tokenize`. |
| `file-parser` | يستخرج النص من PDF. | إذا كان نص الرسالة كله PDF بصيغة base64: `data:application/pdf;base64,…` أو بدون بادئة. |
| `web` | البحث في الويب: تُدمج النتائج في الطلب، وتحصل الاستجابة على روابط المصادر. | مع `privacy-sanitization` — خطأ `400`. |

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

- الخيارات: `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` هذا الإضافة نفسها في وضع الوكيل.

#### plugins: web

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

#### mode: agent

```json
{
  "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.cost_gnk` | تكلفة الطلب بعملة GNK |
| `usage.platform_fee_gnk` | ومنها — هامش المنصة، بعملة GNK |
| `usage.total_cost_gnk` | الإجمالي المخصوم بعملة GNK |
| `usage.total_cost_usd` | الإجمالي بالدولار وفق سعر GNK الحالي |

- في البثّ، يحتوي `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` — لا توجد نماذج تضمين في الشبكة.
- رموز الأخطاء والحدود والمهلات — في قسم [الأخطاء والحدود](https://gate.joingonka.ai/ar/docs/errors).