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 keyAPI keyThe key you create and send with every request that calls a model.More on API keys →, as JSON. Responses lists every field the route takes, and the 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:
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"])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:
{
"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 DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → |
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 balanceBalanceWhat you can spend, in DA.More on Balance and charges → 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:
inputandinstructions, 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_pandstream.
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
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 |
Last modified on