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 प्रॉम्प्ट में हिंट के तौर पर मॉडल को भेजा जाता है: नेटवर्क में असली मिडल-फ़िल नहीं है।
• जवाब में 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 अकाउंट।

वही अनुरोध चार SDK में। मॉडल — अनुशंसित (MiniMaxAI/MiniMax-M2.7), कुंजी — environment variable 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 के वे पैरामीटर जिनकी गारंटी गेटवे खुद देता है — capabilities उत्तर में 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 अनुभाग हटा दिए जाते हैं; पुनरावर्ती संदर्भ बिना बाधाओं वाला स्कीमा बन जाता है।
• उन निर्माणों वाला pattern जो RE2 में नहीं हैं (लुकअहेड और लुकबिहाइंड, बैकरेफ़रेंस, एटॉमिक ग्रुप, पज़ेसिव क्वांटिफ़ायर) हटा दिया जाता है; 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 लौटाता है — नेटवर्क में एम्बेडिंग मॉडल नहीं हैं।
• एरर कोड, सीमाएँ और टाइमआउट — त्रुटियाँ और सीमाएँ अनुभाग में।