opendunes
Text
Copy page ▾

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

FieldNeededYou send
modelyesa text model, lab/model
inputyesa 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
instructionsnothe system prompt: how the model should answer, ahead of input
streamnotrue 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
FieldNeededYou send
temperatureno0 to 2: higher is more varied, lower more predictable
top_pno0 to 1: sample only from the likeliest tokens that together reach this share
top_knosample only from this many likeliest tokens; 1 always takes the likeliest
frequency_penaltyno-2 to 2: above 0, a token is less likely the more often it has appeared
presence_penaltyno-2 to 2: above 0, a token is less likely once it has appeared at all

Tools

Show 6 more fields
FieldNeededYou send
toolsnothe 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_choicenoauto, none, required, or one tool by name
parallel_tool_callsnofalse to have the model call one tool at a time
max_tool_callsno1 to 30: the most helper steps one request may take
stop_server_tools_whennoconditions that end the helper steps early; when set, it takes over from max_tool_calls
pluginsnothe plugins to run on this request, each with its settings

Output shape

Show 8 more fields
FieldNeededYou send
max_output_tokensnothe 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
reasoningnohow 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
textnothe 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
modalitiesnowhat the reply may hold: text or image, where the model makes them
image_confignoa picture model's own settings, when modalities holds image
includenoextra parts to return, such as reasoning.encrypted_content to send the model's reasoning back on the next turn
top_logprobsnohow many of the likeliest alternatives to list for each token
truncationnoauto to let the oldest turns go when the conversation is longer than the model takes, or disabled

Routing

Show 8 more fields
FieldNeededYou send
modelsnomore models, tried in order when model fails or is limited
providernowhich 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"
routenothe older name for choosing between trying models in turn and sorting across them; provider.sort replaces it
service_tiernoauto, default, flex, priority or scale, where the provider offers tiers
session_idnoyour own id, up to 256 characters, that keeps related requests on the same provider
cache_controlno{"type": "ephemeral"} to cache the prompt's longest stable part
prompt_cache_keynoa name that sends requests sharing a prompt to the same cache
prompt_cache_optionsno{"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.

FieldHolds
idthe response's id, resp_...
objectresponse
created_atwhen the request was taken, in Unix seconds
completed_atwhen the reply was finished, in Unix seconds
modelthe model that answered, lab/model; with models, the one that served
statuscompleted, incomplete when it stopped short, or failed
outputthe 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_textthe reply's text, all output_text parts joined, when the provider sends it
errorwhy it failed, when status is failed; else null
incomplete_detailswhy 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 · metadatathe settings the request ran with, echoed back
service_tierthe tier that served it, when the provider names one
usagewhat was counted, and the charge
input_tokensevery token sent, cached and fresh
input_tokens_detailscached_tokens read from the cache, and cache_write_tokens written to it
output_tokensevery token produced, reasoning and reply
output_tokens_detailsreasoning_tokens, the part of output_tokens spent reasoning
total_tokensthe two together
server_tool_use_detailsthe helper calls requested and run, when the model used a helper
costthe charge, in DA
cut_short"wallet", when the balance set the reply's limit and status is incomplete with max_output_tokens; absent otherwise
notewith cut_short: The balance set this answer's length limit, and the answer ended at it.
opendunes_metadatahow 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, and models when a fallback answers, at the fallback's own rate; provider, where only pins one provider and its rate applies, and max_price sets a ceiling.
  • Moves the count: input and instructions, 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_choice and stream.

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.

StatusWhen
400model 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
401the key is missing, wrong, disabled or expired
402your 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
403the key is kept to other models or other addresses, a guardrail's budget is spent, or a guardrail or a filter blocked the request
404model is not a model on sale
408 · 504the provider did not answer in time
413the body is too large
422an input_file part names a file that is not yours or has expired
429the provider is limiting its rate; Retry-After says how many seconds to wait
500an unexpected error
502the model is down, or answered with nothing usable
503no provider meets the provider routing you asked for

Last modified on