Responses
POST /v1/responses sends a conversation to a text model in the Responses shape and
returns its reply, 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. The request and the answer keep the Responses shape. The route
keeps no conversation between requests: send the whole conversation in input every time. A
previous_response_id gets a 400, and store is always false. A field this page does not list
still travels to the model as sent.
Input
| Field | Needed | You send |
|---|---|---|
model | yes | a text model, lab/model |
input | yes | a string, or the conversation so far as a list of items, oldest first: a message with its role (user, assistant, system or developer) and its content, a string or a list of input_text, input_image, input_file, input_audio and input_video parts, where the model reads them; the model's earlier function_call and reasoning items; and your function_call_output for each call it made. An input_file part with a file_id uses a file you stored in Files |
instructions | no | the system prompt: how the model should answer, ahead of input |
stream | no | true to receive the reply as it is written, as server-sent events |
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"
request = urllib.request.Request(
ADDRESS,
data=json.dumps(
{
"model": MODEL,
"input": "Explain what a prepaid wallet is, in one sentence.",
}
).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"])Sampling
Show 5 more fields
| Field | Needed | You send |
|---|---|---|
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 |
top_k | no | sample only from this many likeliest tokens; 1 always takes the likeliest |
frequency_penalty | no | -2 to 2: above 0, a token is less likely the more often it has appeared |
presence_penalty | no | -2 to 2: above 0, a token is less likely once it has appeared at all |
Tools
Show 6 more fields
| Field | Needed | You send |
|---|---|---|
tools | no | the tools the model may call: each {"type": "function", "name": ..., "description": ..., "parameters": {...}} with a JSON Schema for its arguments. A helperHelperA tool run for you when a model reaches for it mid-answer: a web search, a page read, a sandbox. Named opendunes:‹name›.More on Helpers → is named {"type": "opendunes:<name>"} and runs while the model answers; shell, tool search and apply patch work on this route |
tool_choice | no | auto, none, required, or one tool by name |
parallel_tool_calls | no | false to have the model call one tool at a time |
max_tool_calls | no | 1 to 30: the most helper steps one request may take |
stop_server_tools_when | no | conditions that end the helper steps early; when set, it takes over from max_tool_calls |
plugins | no | the plugins to run on this request, each with its settings |
Output shape
Show 8 more fields
| Field | Needed | You send |
|---|---|---|
max_output_tokens | no | the most tokens the reply may hold, reasoning included. A limit you name is never lowered: above the model's longest answer it becomes that, and one your balanceBalanceWhat you can spend, in DA.More on Balance and charges → cannot pay gets a 402. Left out, it is the limit your balance can pay, half of what is left after the input at most, up to the model's longest answer: Balance and charges |
reasoning | no | how much the model reasons before it answers: {"effort": "low"}, from none through minimal, low, medium, high and xhigh to max, where the model reasons; summary (auto, concise or detailed) for a summary of it |
text | no | the reply's shape: {"format": {"type": "json_object"}} for JSON, or {"format": {"type": "json_schema", ...}} for JSON that follows your schema; verbosity from low to max |
modalities | no | what the reply may hold: text or image, where the model makes them |
image_config | no | a picture model's own settings, when modalities holds image |
include | no | extra parts to return, such as reasoning.encrypted_content to send the model's reasoning back on the next turn |
top_logprobs | no | how many of the likeliest alternatives to list for each token |
truncation | no | auto to let the oldest turns go when the conversation is longer than the model takes, or disabled |
Routing
Show 8 more fields
| Field | Needed | You send |
|---|---|---|
models | no | more models, tried in order when model fails or is limited |
provider | no | which providers may serve it: only, ignore, order, sort (price, throughput, latency or exacto), allow_fallbacks, max_price in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → per million tokens, and the rest of the provider's own preferences. Your account's privacy settings add data_collection: "deny" |
route | no | the older name for choosing between trying models in turn and sorting across them; provider.sort replaces it |
service_tier | no | auto, default, flex, priority or scale, where the provider offers tiers |
session_id | no | your own id, up to 256 characters, that keeps related requests on the same provider |
cache_control | no | {"type": "ephemeral"} to cache the prompt's longest stable part |
prompt_cache_key | no | a name that sends requests sharing a prompt to the same cache |
prompt_cache_options | no | {"mode": "explicit"} to cache only the parts you mark, and how long to keep them, where the model offers it |
Response
200 OK, once the reply is written.
| Field | Holds |
|---|---|
id | the response's id, resp_... |
object | response |
created_at | when the request was taken, in Unix seconds |
completed_at | when the reply was finished, in Unix seconds |
model | the model that answered, lab/model; with models, the one that served |
status | completed, incomplete when it stopped short, or failed |
output | the items the model produced, in order: a message whose content holds the reply as output_text parts, a reasoning item, a function_call with its call_id, name and arguments when the model calls one of your tools, and a helper's call when it used one |
output_text | the reply's text, all output_text parts joined, when the provider sends it |
error | why it failed, when status is failed; else null |
incomplete_details | why it stopped short, such as the max_output_tokens ceiling, when status is incomplete |
instructions · tools · tool_choice · parallel_tool_calls · temperature · top_p · presence_penalty · frequency_penalty · metadata | the settings the request ran with, echoed back |
service_tier | the tier that served it, when the provider names one |
usage | what was counted, and the charge |
input_tokens | every token sent, cached and fresh |
input_tokens_details | cached_tokens read from the cache, and cache_write_tokens written to it |
output_tokens | every token produced, reasoning and reply |
output_tokens_details | reasoning_tokens, the part of output_tokens spent reasoning |
total_tokens | the two together |
server_tool_use_details | the helper calls requested and run, when the model used a helper |
cost | the charge, in DA |
cut_short | "wallet", when the balance set the reply's limit and status is incomplete with max_output_tokens; absent otherwise |
note | with cut_short: The balance set this answer's length limit, and the answer ended at it. |
opendunes_metadata | how the request was routed, when it sent X-OpenDunes-Metadata: enabled |
X-Generation-Id rides the answer: the receipt handle, read back with GET /v1/generation.
X-Balance-Available is your balance after this charge, in µDAµDAA millionth of a DA: 1 DA = 1 000 000 µDA.More on Balance and charges →.
With stream: true. The answer is a stream of server-sent events, each with its event:
name: response.created first, then response.output_text.delta carrying the next piece of the
reply, with the items and their parts opening and closing around it, and last
response.completed, or response.incomplete or response.failed, whose response carries
usage, cost among it. The stream ends with data: [DONE]. A line opening with : is a
keep-alive. A stream carries no X-Balance-Available: its headers leave before the charge
exists. usage.cost in the last event is the charge, and GET /v1/credits, with a management
keyManagement keyThe key that runs your account through the API: the balance, the usage history, your keys, guardrails, observability. It never calls a model.More on API keys →, answers what you have deposited and spent after it.
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, and the counts
in usage add up to it.
- Picks the price:
model, andmodelswhen a fallback answers, at the fallback's own rate;provider, whereonlypins one provider and its rate applies, andmax_pricesets a ceiling. - Moves the count:
inputandinstructions, every token sent;max_output_tokens, the ceiling on what comes back;reasoning, whose tokens count as output;cache_control, a cached part counted at the cache-read rate, and at the cache-write rate the first time where the model has one;tools, whose definitions are sent on every turn;modalities, pictures in the reply counted as output. - Changes the answer, never the bill: the Sampling fields,
text,top_logprobs,tool_choiceandstream.
A stream cut before its last event is charged from the receipt, moments later, and
GET /v1/generation shows it: what the model wrote where the provider stops it, the whole
answer where the provider lets the model finish. Each of these charges nothing: a reply with no output, an error
before any output, a response-cache hit, a model that is not on sale.
Errors
An error keeps the Responses shape: status is failed, error.message says why, and
error_type names the cause in one word.
| Status | When |
|---|---|
| 400 | model or input is missing, a field has the wrong type or is out of range, previous_response_id is sent, a helper is not offered or works on another route only, or the provider refused a field |
| 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 |
| 403 | the key is kept to other models or other addresses, a guardrail's budget is spent, or a guardrail or a filter blocked the request |
| 404 | model is not a model on sale |
| 408 · 504 | the provider did not answer in time |
| 413 | the body is too large |
| 422 | an input_file part names a file that is not yours or has expired |
| 429 | the provider is limiting its rate; Retry-After says how many seconds to wait |
| 500 | an unexpected error |
| 502 | the model is down, or answered with nothing usable |
| 503 | no provider meets the provider routing you asked for |
Last modified on