# Responses API

> POST /v1/responses, অর্থাৎ OpenAI Responses API: chat completions-এর বদলে কখন এটা নেবেন, request ও response-এর উদাহরণ, max_output_tokens আর streaming event।

`POST https://tokens.bd/v1/responses` OpenAI Responses API-কে সরাসরি পাস করে দেয়। এটা মূলত সেই client-দের জন্য যারা Responses API-র ওপর বানানো, যেমন Codex CLI। নতুন code লিখছেন আর এটা বেছে নেওয়ার বিশেষ কারণ নেই, তাহলে chat completions নিন। বেশির ভাগ upstream model-এ সেটাই বেশি support পায়।

## কখন Responses API নেবেন

| `/v1/responses` নিন যখন                                                     | `/v1/chat/completions` নিন যখন                     |
| ------------------------------------------------------------------------- | ----------------------------------------------- |
| আপনার tool শুধু Responses বোঝে (`wire_api = "responses"` দিয়ে Codex CLI)    | সবচেয়ে বেশি model-এর সঙ্গে চলুক চান                 |
| `client.responses.create` ধরে আগে থেকেই code লেখা আছে                       | যেসব framework chat completions আশা করে সেগুলো চালান |
| Typed output item আর event-এর নাম চান                                      | `n` > 1 বা শুধু chat-এর অন্য field লাগে            |

এই endpoint চলবে কিনা তা নির্ভর করে model-টা কোন upstream থেকে আসছে তার ওপর। Gateway request যেমন আছে তেমনই forward করে। কোনো model-এর পেছনের provider Responses implement না করলে upstream থেকে 400 বা 404 দিয়ে call fail করবে। তেমন হলে ওই model-এর জন্য chat completions ব্যবহার করুন।

## Responses API request-এর উদাহরণ

:::code-tabs

```bash title="cURL"
curl https://tokens.bd/v1/responses \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash",
    "instructions": "You are a concise senior engineer.",
    "input": "Give me one reason to pin dependency versions.",
    "max_output_tokens": 200
  }'
```

```python title="Python"
import os
from openai import OpenAI

client = OpenAI(base_url="https://tokens.bd/v1", api_key=os.environ["TOKENS_API_KEY"])

resp = client.responses.create(
    model="deepseek/deepseek-v4.1-flash",
    instructions="You are a concise senior engineer.",
    input="Give me one reason to pin dependency versions.",
    max_output_tokens=200,
)
print(resp.output_text)
print(resp.usage)
```

:::

ছোট করা একটা response:

```json
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "deepseek/deepseek-v4.1-flash",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Reproducible builds: the same commit installs the same code everywhere."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 15,
    "total_tokens": 39
  }
}
```

Request-এ সাধারণত যেসব field লাগে:

| Field                  | নোট                                                                                                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                | আবশ্যক। `GET /v1/models`-এর যেকোনো id।                                                                                                                              |
| `input`                | একটা string, অথবা input item-এর array (message, tool output)।                                                                                                   |
| `instructions`         | System-ধাঁচের নির্দেশ।                                                                                                                                             |
| `max_output_tokens`    | Output-এর সীমা। Gateway এটা দিয়ে খরচের reservation ধরে, আর ব্যালান্স কম থাকলে এটা কমিয়েও দিতে পারে (সর্বনিম্ন 16)।                                                       |
| `tools`, `tool_choice` | Function tool, যেসব model support করে তাদের জন্য। Web search বা file search-এর মতো hosted tool provider-এর নিজস্ব feature; gateway দিয়ে এগুলো চলবে, এমন ধরে নেবেন না। |
| `stream`               | Server-Sent Events পেতে `true`।                                                                                                                                  |

## Conversation state

Tokens আপনার prompt বা response জমিয়ে রাখে না। তাই এক call থেকে আরেক call-এ state রাখার জন্য `previous_response_id` বা `store: true`-র ওপর ভরসা করবেন না। এগুলো চলবে কিনা upstream-এর ওপর নির্ভর করে। তাছাড়া retry বা failover হলে request এমন source-এ যেতে পারে যে আগের response কখনো দেখেইনি। তাই প্রতিবার পুরো conversation `input`-এ পাঠান; এটা সব জায়গায় কাজ করে।

## Responses API-র event stream করা

`"stream": true` দিলে response আসে Server-Sent Events হিসেবে, প্রতিটার একটা নির্দিষ্ট type থাকে। বেশির ভাগ client যেগুলো নিয়ে কাজ করে:

| Event                                    | কী থাকে                                       |
| ---------------------------------------- | -------------------------------------------- |
| `response.created`                       | Response object, status `in_progress`        |
| `response.output_text.delta`             | `delta`-তে text-এর একটা টুকরো                    |
| `response.function_call_arguments.delta` | Tool-call argument-এর একটা টুকরো                |
| `response.completed`                     | শেষ response object, `usage`-সহ                |

Chat completions-এর মতো এখানে usage পেতে `stream_options` লাগে না: ওটা আসে `response.completed`-এ।

```python
stream = client.responses.create(
    model="deepseek/deepseek-v4.1-flash",
    input="Write a haiku about cache invalidation.",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n", event.response.usage)
```

Disconnect আর timeout অন্য endpoint-এর মতোই চলে; দেখুন [streaming](/docs/streaming)।

## Codex CLI /v1/responses ব্যবহার করে

Codex CLI এই endpoint দিয়েই Tokens-এর সঙ্গে কথা বলে। `~/.codex/config.toml`-এর provider block দেখতে এমন, আর key পড়া হয় `TOKENS_API_KEY` থেকে:

```toml title="~/.codex/config.toml"
model = "deepseek/deepseek-v4.1-flash"
model_provider = "tokens"

[model_providers.tokens]
name = "Tokens"
base_url = "https://tokens.bd/v1"
env_key = "TOKENS_API_KEY"
wire_api = "responses"
```

Tokens CLI এটা আপনার হয়ে লিখে দিতে পারে; এক লাইনের setup আছে [quickstart](/docs/quickstart)-এ। কোনো model-এ Codex error দিলে Codex-এর settings ঘাঁটার আগে ওপরের curl উদাহরণ দিয়ে দেখে নিন model-টা `/v1/responses`-এ চলছে কিনা।

Error-এর shape কেমন তা আছে [errors](/docs/errors) পেজে, আর limit আছে [rate limits](/docs/rate-limits) পেজে।

---
Page: https://tokens.bd/bn/docs/responses