# Responses · basic use

`POST /v1/responses` with a string or the conversation so far in `input` returns the model's
reply in `output`, with what it cost.

## Request

Send it with an API key, as JSON. [Responses](/docs/reference/responses) lists every field the
route takes, and the [Text](/docs/text) guide walks through a first call on any of the three
text routes.

The route keeps nothing between requests: each one carries the whole conversation in `input`,
the model's earlier replies included, oldest first.

| Field | Needed | You send |
|---|---|---|
| `model` | yes | a text model, `lab/model` |
| `input` | yes | a string; or the conversation so far, a list of messages, each with its `role` (`user`, `assistant`, `system` or `developer`) and its `content`, a string or a list of parts such as `{"type": "input_text", "text": ...}` |
| `instructions` | no | the system prompt: how the model should answer, ahead of `input` |
| `max_output_tokens` | no | the most tokens the reply may hold, reasoning included |
| `stream` | no | `true` to receive the reply as it is written, as server-sent events |
| `temperature` | no | 0 to 2: higher is more varied, lower more predictable |
| `top_p` | no | 0 to 1: sample only from the likeliest tokens that together reach this share |
| `store` | no | `false`, or leave it out: nothing is stored, and `true` gets a 400 |
| `previous_response_id` | no | never: the route keeps no earlier response, and any value gets a 400 |

Souk Bot answers customers of a clothing shop in Oran. On the customer's second message, it
sends the first exchange back with it:

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/responses"
MODEL = "anthropic/claude-sonnet-4.5"
CONVERSATION = [
    {"role": "user", "content": "Do you have this jacket in size M?"},
    {"role": "assistant", "content": "Yes, in black and in navy."},
    {"role": "user", "content": "Which one is warmer?"},
]

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "instructions": "You answer for a clothing shop in Oran.",
            "input": CONVERSATION,
            "max_output_tokens": 300,
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

for item in answer["output"]:
    if item["type"] == "message":
        print(item["content"][0]["text"])
print(answer["usage"]["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/responses";
const MODEL = "anthropic/claude-sonnet-4.5";
const CONVERSATION = [
  { role: "user", content: "Do you have this jacket in size M?" },
  { role: "assistant", content: "Yes, in black and in navy." },
  { role: "user", content: "Which one is warmer?" },
];

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    instructions: "You answer for a clothing shop in Oran.",
    input: CONVERSATION,
    max_output_tokens: 300,
  }),
});
const answer = await response.json();

for (const item of answer.output) {
  if (item.type === "message") console.log(item.content[0].text);
}
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address      = "https://opendunes.com/v1/responses"
	model        = "anthropic/claude-sonnet-4.5"
	instructions = "You answer for a clothing shop in Oran."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")
	conversation := []map[string]string{
		{"role": "user", "content": "Do you have this jacket in size M?"},
		{"role": "assistant", "content": "Yes, in black and in navy."},
		{"role": "user", "content": "Which one is warmer?"},
	}

	body, err := json.Marshal(map[string]any{
		"model":             model,
		"instructions":      instructions,
		"input":             conversation,
		"max_output_tokens": 300,
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Output []struct {
			Type    string `json:"type"`
			Content []struct {
				Text string `json:"text"`
			} `json:"content"`
		} `json:"output"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}

	for _, item := range answer.Output {
		if item.Type == "message" && len(item.Content) > 0 {
			fmt.Println(item.Content[0].Text)
		}
	}
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/responses"
MODEL="anthropic/claude-sonnet-4.5"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "instructions": "You answer for a clothing shop in Oran.",
    "input": [
      {"role": "user", "content": "Do you have this jacket in size M?"},
      {"role": "assistant", "content": "Yes, in black and in navy."},
      {"role": "user", "content": "Which one is warmer?"}
    ],
    "max_output_tokens": 300
  }'
```

The next turn adds the reply and the customer's next message to the list, and sends it all
again.

## Response

`200 OK`, once the reply is written. Souk Bot's answer, illustrative:

```json
{
  "id": "resp_8f2c1a7d",
  "object": "response",
  "created_at": 1759140000,
  "model": "anthropic/claude-sonnet-4.5",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_4b9e2f10",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The navy one: it has a thicker lining.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 52,
    "output_tokens": 14,
    "total_tokens": 66,
    "cost": 0.041
  }
}
```

| Field | Holds |
|---|---|
| `id` | the response's id, `resp_...` |
| `object` | `response` |
| `created_at` | when the request was taken, in Unix seconds |
| `model` | the model that answered, `lab/model` |
| `status` | `completed`, `incomplete` when it stopped short, or `failed` |
| `output` | the items the model produced, in order; the reply is the item whose `type` is `message` |
| `content` | in the `message` item: the reply's parts, each an `output_text` |
| `output_text` | a part holding the reply's `text` |
| `annotations` | in each `output_text` part: the sources it cites, empty when it cites none |
| `usage` | what was counted, and the charge |
| `input_tokens` | every token sent: `instructions` and the whole of `input` |
| `output_tokens` | every token produced |
| `total_tokens` | the two together |
| `cost` | the charge, in DA |

**With `stream: true`.** The answer is a stream of server-sent events, each with its `event:`
name. `response.created` opens it; `response.output_item.added` and
`response.content_part.added` open the message and its text; `response.output_text.delta`
carries each next piece of the reply; `response.output_text.done`,
`response.content_part.done` and `response.output_item.done` close them; and
`response.completed` ends it, its `response` carrying `usage`, `cost` among it. The stream
closes with `data: [DONE]`. A line opening with `:` is a keep-alive.

## What it cost

Charged in DA from your balance once the reply is delivered: the tokens the model reports, at
the model's rates, which its model page shows. `usage.cost` carries the charge.

- **Moves the count**: `input` and `instructions`, every token sent, so a longer conversation
  costs more on each turn; `max_output_tokens`, the ceiling on what comes back.
- **Changes the answer, never the bill**: `temperature`, `top_p` and `stream`.

A reply with no output, an error before any output and a response-cache hit charge nothing.

## Errors

An error keeps the Responses shape: `status` is `failed`, `error.message` says why, and
`error_type` names the cause in one word. [Responses · errors](/docs/reference/responses-errors)
lists every status and every word.

| Status | When |
|---|---|
| 400 | `model` or `input` is missing, a field has the wrong type or is out of range, `store` is `true`, or a `previous_response_id` is sent |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; `metadata.limit_source`, beside `error`, names which, and `deposit_url` or `key_url` there says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries `Retry-After: 60` |
| 404 | `model` is not a model on sale |
| 429 | the provider is limiting its rate; `Retry-After` says how many seconds to wait |
| 502 | the model is down, or answered with nothing usable |
