> AI ایجنٹس کے لیے: سیٹ اپ کی مرحلہ وار ہدایات — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)، دستاویزات کا انڈیکس — [`/llms.txt`](https://gate.joingonka.ai/llms.txt)۔

# API حوالہ

گیٹ وے کو بھیجی جانے والی درخواستوں سے متعلق سب کچھ: پروٹوکول، پتے، کیز اور پیرامیٹرز۔ ذیل میں — اسٹریمنگ، ٹول کالنگ، ریزننگ، پلگ انز اور جواب میں درخواست کی لاگت۔

## پروٹوکولز اور پتے

گیٹ وے OpenAI اور Anthropic دونوں فارمیٹ قبول کرتا ہے۔ OpenAI SDK کے لیے بیس URL — `https://gate.joingonka.ai/v1`، Anthropic SDK کے لیے — `https://gate.joingonka.ai`۔ تمام پروٹوکول ایک کلید اور ایک بیلنس پر کام کرتے ہیں: کسی بھی فارمیٹ کی درخواست اسی راستے سے جاتی ہے۔

| میتھڈ اور پاتھ | فارمیٹ | کس لیے | خصوصیات |
| --- | --- | --- | --- |
| `POST /v1/chat/completions` | OpenAI Chat Completions | چیٹ، ایجنٹس، ٹول کالز | بنیادی راستہ: باقی فارمیٹ گیٹ وے اسی میں بدلتا ہے۔ |
| `POST /v1/messages` | Anthropic Messages | Claude Code اور Anthropic SDK | بیس URL `/v1` کے بغیر؛ `claude-*` ماڈلز تجویز کردہ سے بدل جاتے ہیں؛ `max_tokens` فیلڈ لازمی ہے۔ |
| `POST /v1/responses` | OpenAI Responses | Codex CLI اور نئے OpenAI SDK | بغیر حالت: ہر درخواست میں پوری تاریخ بھیجیں۔ |
| `POST /v1/completions` | OpenAI Completions (legacy) | ایڈیٹرز میں آٹو کمپلیٹ اور کوڈ کی تدوین | `suffix` پرامپٹ میں اشارے کے طور پر ماڈل کو بھیجا جاتا ہے؛ جواب میں `logprobs: null`۔ |
| `POST /v1/embeddings` | OpenAI Embeddings | متن کی ویکٹر نمائندگی | جواب `501`: نیٹ ورک میں ایمبیڈنگ ماڈلز نہیں ہیں۔ |

### حوالہ جاتی پتے

بغیر کلید جواب دیتے ہیں۔ کانٹیکسٹ اور اسٹیٹس کے ساتھ ماڈلز کا جدول — [ماڈلز](https://gate.joingonka.ai/ur/docs/models) حصے میں۔

| میتھڈ اور پاتھ | تفصیل |
| --- | --- |
| `GET /v1/models` | ماڈلز کی فہرست: کانٹیکسٹ، قیمتیں، معاون پیرامیٹرز — OpenRouter فارمیٹ میں فیلڈز۔ |
| `GET /v1/models/{model}` | ایک ماڈل کا کارڈ؛ id میں سلیش — جوں کا توں یا `%2F`۔ چھپا یا نامعلوم ماڈل — `404 model_not_found`۔ |
| `GET /v1/capabilities` | گیٹ وے کی صلاحیتیں: پیرامیٹرز، پروٹوکولز، پلگ انز، لاگت کے فیلڈز اور حدود (`limits`)۔ |
| `GET /v1/plugins` | پلگ انز: id اور نام۔ |
| `GET /v1/network-status` | نیٹ ورک کے ماڈلز کی حالت: دستیابی، تاخیر، اپ ٹائم۔ |
| `GET /v1/nodes` | نوڈ پول کا خلاصہ: کل، فعال اور قرنطینہ میں کتنے۔ |
| `GET /v1/web-search/engines` | ویب سرچ فعال ہے یا نہیں اور اس کے انجنز کی حالت۔ |

### Anthropic Messages

- بیس URL — `https://gate.joingonka.ai`: SDK خود `/v1/messages` شامل کرے گا۔
- کلید — `x-api-key` ہیڈر میں (Anthropic SDK اسی طرح بھیجتا ہے) یا `Authorization: Bearer` میں۔
- `claude-*` ماڈلز گیٹ وے تجویز کردہ ماڈل (`MiniMaxAI/MiniMax-M2.7`) سے بدل دیتا ہے؛ جواب کے `model` فیلڈ میں وہی نام رہتا ہے جو کلائنٹ نے بھیجا تھا۔
- `max_tokens` لازمی ہے، جیسا کہ Anthropic API میں؛ ماڈل کی حد سے زیادہ ہو تو کاٹ دیا جاتا ہے۔
- اسٹریم — Anthropic ایونٹس؛ وقفوں میں گیٹ وے `event: ping` بھیجتا ہے، خرابی `event: error` ایونٹ میں آتی ہے۔
- ماڈل کی سوچ جواب میں شامل نہیں ہوتی: `thinking` بلاکس نہیں ہوتے۔
- بلٹ اِن `web_search` ٹول گیٹ وے کا ویب سرچ پلگ ان چلاتا ہے — دیکھیں [پلگ انز](https://gate.joingonka.ai/ur/docs/api#plugins) حصہ۔
- ٹوکنز کی گنتی (`/v1/messages/count_tokens`) نہیں ہے — جواب `404`۔

Claude Code کو انسٹالر سے ترتیب دینا آسان ہے — [ٹولز جوڑنا](https://gate.joingonka.ai/ur/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` میں اپنا پرووائیڈر id دیں (openai نہیں) — تب Codex خود تاریخ سکیڑتا ہے، `/v1/responses/compact` کے بغیر۔

### Legacy Completions

- `prompt` — ایک اسٹرنگ یا ایک اسٹرنگ کی ایرے؛ جواب — `choices[].text` میں۔ متعدد پرامپٹس یا متن کے بجائے ٹوکنز — `400` خرابی۔
- `suffix` پرامپٹ میں اشارے کے طور پر ماڈل کو بھیجا جاتا ہے: نیٹ ورک میں حقیقی mid-fill نہیں ہے۔
- جواب میں `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/ur/docs/errors#limits) حصے میں۔
- بغیر کلید صرف سائٹ کی ڈیمو چیٹ کام کرتی ہے: اپنے کوڈ سے بغیر کلید درخواست `is_demo` کے ساتھ `402` پائے گی۔
- کلیدوں کا انتظام صرف ڈیش بورڈ میں ہوتا ہے: API کلید کے ساتھ `/api/keys` قابل رسائی نہیں۔ کلید کا بیلنس اور خرچ — [API اکاؤنٹ](https://gate.joingonka.ai/ur/docs/billing#account-api)۔

> کلید ایک راز ہے: اسے ریپوزٹری یا فرنٹ اینڈ کوڈ میں محفوظ نہ کریں، انوائرنمنٹ ویری ایبلز کے ذریعے پاس کریں۔

## مثالیں

ایک ہی درخواست چار SDKs میں۔ ماڈل — تجویز کردہ (`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` کی فہرست:

| پیرامیٹر | تفصیل |
| --- | --- |
| `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/ur/docs/errors#limits) سیکشن میں۔

### نیٹ ورک میں جوں کا توں پاس ہوتے ہیں

`reasoning_effort`, `reasoning`, `enable_thinking`, `chat_template_kwargs`, `thinking_token_budget`, `min_tokens`, `logit_bias`, `n`, `parallel_tool_calls`, `extra_body`۔ گیٹ وے انہیں چیک نہیں کرتا: نیٹ ورک کی فہرست سے باہر قدر — `api_error` قسم کی `400` غلطی۔

### نیٹ ورک میں پاس نہیں ہوتے

باقی فیلڈز گیٹ وے قبول کرتا ہے مگر نیٹ ورک میں پاس نہیں کرتا — مثلاً، `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` بن جاتا ہے، خالی اور مکرر کال id منفرد ملتی ہیں، `arguments` بطور آبجیکٹ JSON اسٹرنگ بنتا ہے، گمشدہ `type` مکمل ہوتا ہے، بلا نام کال نتیجے سمیت ہٹا دی جاتی ہے۔
- وہ کال جو ماڈل نے متن میں مارک اپ سے لکھی، گیٹ وے اسے `tool_calls` میں منتقل کرتا ہے؛ ٹولز کے بغیر درخواست کے جواب میں جھوٹی کالیں ہٹا دیتا ہے۔
- آرگیومنٹس کے بیچ جنریشن رک گئی — `tool_calls` نہیں، `finish_reason: length` آئے گا: جواب کی حد بڑھائیں۔

```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` سیکشنز ہٹا دیے جاتے ہیں؛ ریکرسیو حوالہ بلا پابندی اسکیمہ بن جاتا ہے۔
- RE2 میں نہ ہونے والی ساختوں والا `pattern` (لک آہیڈ اور لک بہائنڈ، بیک ریفرنسز، ایٹامک گروپس، پوسیسیو کوانٹیفائرز) ہٹا دیا جاتا ہے؛ 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` | متنی پیغامات میں email، IPv4، کارڈ نمبرز، JWT، 64 حروف والی hex کلیدیں اور `sk-…`, `gw_…`, `gm-…`, `Bearer …` جیسی کلیدیں ماسک کرتا ہے۔ | موڈ — `privacy_mode` فیلڈ: `redact` (ڈیفالٹ) یا `tokenize`۔ |
| `file-parser` | PDF سے متن نکالتا ہے۔ | اگر پیغام کا متن مکمل طور پر base64 میں PDF ہو: `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` صرف ٹوکنز رکھتا ہے؛ لاگت — `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/ur/docs/errors) سیکشن میں۔