> 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/bn/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/bn/docs/api#plugins) বিভাগ।
- টোকেন গণনা (`/v1/messages/count_tokens`) নেই — উত্তর `404`।

Claude Code ইনস্টলার দিয়ে সেট আপ করা সহজ — [টুল যুক্ত করা](https://gate.joingonka.ai/bn/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/bn/docs/errors#limits) বিভাগে।
- কী ছাড়া শুধু সাইটের ডেমো চ্যাট কাজ করে: নিজের কোড থেকে কী ছাড়া অনুরোধ `is_demo` সহ `402` পাবে।
- কী শুধু ড্যাশবোর্ডে ব্যবস্থাপনা করা যায়: API কী দিয়ে `/api/keys` অ্যাক্সেসযোগ্য নয়। কী-র ব্যালান্স ও খরচ — [API অ্যাকাউন্ট](https://gate.joingonka.ai/bn/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` তালিকা:

| প্যারামিটার | বিবরণ |
| --- | --- |
| `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/bn/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` হয়, খালি ও পুনরাবৃত্ত 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 থেকে টেক্সট বের করে। | যদি মেসেজের টেক্সট সম্পূর্ণভাবে 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`-এ শুধু টোকেন থাকে; খরচ — `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/bn/docs/errors) বিভাগে।