opendunes
Text
Copy page ▾

Messages

POST /v1/messages sends a conversation to a text model in the Anthropic 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 Anthropic shape, so a client library already written for it works unchanged. A field this page does not list still travels to the model as sent. The Text guide walks through a first call.

Messages

FieldNeededYou send
modelyesa text model, lab/model
systemnothe instructions that frame the conversation: a string, or a list of text parts
messagesyesthe turns so far, oldest first: each {"role": ..., "content": ...}, with role user, assistant or system. content is a string, or a list of blocks: text, pictures, documents, and the results of tool calls
max_tokensnothe most tokens the reply may hold, thinking 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
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/messages"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Explain what a prepaid wallet is, in one sentence."

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "max_tokens": 1024,
            "messages": [{"role": "user", "content": PROMPT}],
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

print(answer["content"][0]["text"])
print(answer["usage"]["cost"])

Sampling

Show 4 more fields
FieldNeededYou send
temperaturenohigher 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
stop_sequencesnostrings that end the reply when the model writes one

Tools

Show 6 more fields
FieldNeededYou send
toolsnothe tools the model may call: each with a name, a description and an input_schema. 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; the shell, bash and tool search helpers work here
tool_choiceno{"type": "auto"}, {"type": "any"}, {"type": "none"}, or one tool by name
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
safeguardsnochecks the provider runs beside the reply, each named by its type, such as dangerous_tool_use

Output shape

Show 3 more fields
FieldNeededYou send
thinkingno{"type": "enabled", "budget_tokens": ...} to let the model think before it answers, within that many tokens; {"type": "adaptive"} to let it decide; {"type": "disabled"}
output_confignoeffort, from low to max, and format for a reply that follows your JSON Schema
context_managementnoedits that clear old tool results from a long conversation before it is sent

Routing

Show 7 more fields
FieldNeededYou send
modelsnomore models, tried in order when model fails or is limited
fallbacksnoup to three {"model": ...} entries, tried in order when model fails or refuses; never with models
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_tiernothe provider's processing tier, where it offers tiers
speednofast for a quicker reply where the model offers it, at that speed's own rate; standard otherwise
cache_controlno{"type": "ephemeral"} to cache the prompt's longest stable part; on a block, it marks where the cached part ends

Response

200 OK, once the reply is written.

FieldHolds
idthe receipt handle, read back with GET /v1/generation
typemessage
roleassistant
modelthe model that answered, lab/model; with models or fallbacks, the one that served
providerthe lab that served it
contentthe reply, as blocks: text, thinking, tool_use, and a helper's calls and results
stop_reasonwhy it ended: end_turn, max_tokens, stop_sequence, tool_use, pause_turn or refusal, among others
stop_sequencethe stop sequence that ended it, when one did
containerthe sandbox a helper ran in, under your name for it
usagewhat was counted, and the charge
input_tokensthe fresh tokens sent, outside the cache
cache_read_input_tokensthe tokens read from the cache
cache_creation_input_tokensthe tokens written to the cache
output_tokensevery token produced, thinking and reply
output_tokens_detailsthinking_tokens, the thinking inside the output count
server_tool_usethe helper calls requested and run, and the web searches and fetches
costthe charge, in DA
cut_short"wallet", when the balance set the reply's limit and stop_reason is max_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. 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, named as the Anthropic shape names them: message_start opens it with the input count, the blocks arrive piece by piece, message_delta carries the output count and usage.cost (and cut_short and note, when the balance limited the reply), and message_stop ends it. A stream carries no X-Balance-Available: its headers leave before the charge exists, 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 the balance 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 or fallbacks 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: system and messages, every token sent; max_tokens, the ceiling on what comes back; thinking, 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; tools, whose definitions are sent on every turn; output_config, whose effort moves how much the model writes.
  • Changes the answer, never the bill: the Sampling fields, tool_choice and stream.

A stream cut before message_stop is charged from the receipt, moments later, and GET /v1/generation shows it. Where the provider stops the model when you close the stream, the charge stops there; where it cannot, the model finishes and the whole answer is charged. A provider error mid-stream charges the tokens produced. 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

The body says why.

StatusWhen
400model or messages is missing, a field has the wrong type, a helper is not offered or works on another route only, a sandbox name or a session_id is malformed, 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, or a sandbox a helper names is not yours
408 · 504the provider did not answer in time
413the body is too large
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