AI ایجنٹس کے لیے: سیٹ اپ کی مرحلہ وار ہدایات — /docs/agents.md، دستاویزات کا انڈیکس — /llms.txt۔

API حوالہ

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

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

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

بغیر کلید جواب دیتے ہیں۔ کانٹیکسٹ اور اسٹیٹس کے ساتھ ماڈلز کا جدول — ماڈلز حصے میں۔

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 ٹول گیٹ وے کا ویب سرچ پلگ ان چلاتا ہے — دیکھیں پلگ انز حصہ۔
• ٹوکنز کی گنتی (/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 میں اپنا پرووائیڈر 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 صفحے پر رجسٹریشن کے بعد بنائی جاتی ہے۔

• ڈیش بورڈ میں ہر کلید کے لیے روزانہ، ماہانہ اور کل خرچ کی حد مقرر کی جا سکتی ہے؛ حد سے تجاوز — 402 child_key_limit_exceeded۔
• فی کلید فی منٹ درخواستوں کی تعداد محدود ہے — اقدار حدود حصے میں۔
• بغیر کلید صرف سائٹ کی ڈیمو چیٹ کام کرتی ہے: اپنے کوڈ سے بغیر کلید درخواست is_demo کے ساتھ 402 پائے گی۔
• کلیدوں کا انتظام صرف ڈیش بورڈ میں ہوتا ہے: API کلید کے ساتھ /api/keys قابل رسائی نہیں۔ کلید کا بیلنس اور خرچ — API اکاؤنٹ۔

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

• 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۔ گیٹ وے انہیں چیک نہیں کرتا: نیٹ ورک کی فہرست سے باہر قدر — 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 میں — فی چنک ایک کال: نیٹ ورک میں جڑی ہوئی کالوں کو گیٹ وے کاٹ کر الگ کرتا ہے۔

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

{
  "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 پلگ ان درست کرتا ہے۔

{
  "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 صرف ٹوکنز رکھتا ہے؛ لاگت — 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 — نیٹ ورک میں کوئی ایمبیڈنگ ماڈل نہیں۔
• ایرر کوڈز، حدود اور ٹائم آؤٹس — خرابیاں اور حدود سیکشن میں۔