# Responses

`POST /v1/responses` sends a conversation to a [text model](/docs/text) in the Responses shape and
returns its reply, with what it cost.

## Request

Send it with an API key, 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 |

```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"

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"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/responses";
const MODEL = "anthropic/claude-sonnet-4.5";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    input: "Explain what a prepaid wallet is, in one sentence.",
  }),
});
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"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model": model,
		"input": "Explain what a prepaid wallet is, in one sentence.",
	})
	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"'",
    "input": "Explain what a prepaid wallet is, in one sentence."
  }'
```

### Sampling

<details>
<summary>Show 5 more fields</summary>

| 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 |

</details>

### Tools

<details>
<summary>Show 6 more fields</summary>

| 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 helper 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 |

</details>

### Output shape

<details>
<summary>Show 8 more fields</summary>

| 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 balance 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](/docs/balance-and-charges#how-a-request-is-charged) |
| `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` |

</details>

### Routing

<details>
<summary>Show 8 more fields</summary>

| 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 DA 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 |

</details>

## 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.

**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
key, 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.

| 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 |
