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 অ্যাকাউন্ট।

একই অনুরোধ চারটি 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 তালিকা:

• 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 হয়, খালি ও পুনরাবৃত্ত 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 — নেটওয়ার্কে কোনো এমবেডিং মডেল নেই।
• এরর কোড, লিমিট ও টাইমআউট — ত্রুটি ও সীমা বিভাগে।