opendunes
Overview
Copy page ▾

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.

FieldNeededYou send
modelyesa text model, lab/model
inputyesa 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": ...}
instructionsnothe system prompt: how the model should answer, ahead of input
max_output_tokensnothe most tokens the reply may hold, reasoning included
streamnotrue to receive the reply as it is written, as server-sent events
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
storenofalse, or leave it out: nothing is stored, and true gets a 400
previous_response_idnonever: 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:

JSON
{
  "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
  }
}
FieldHolds
idthe response's id, resp_...
objectresponse
created_atwhen the request was taken, in Unix seconds
modelthe model that answered, lab/model
statuscompleted, incomplete when it stopped short, or failed
outputthe items the model produced, in order; the reply is the item whose type is message
contentin the message item: the reply's parts, each an output_text
output_texta part holding the reply's text
annotationsin each output_text part: the sources it cites, empty when it cites none
usagewhat was counted, and the charge
input_tokensevery token sent: instructions and the whole of input
output_tokensevery token produced
total_tokensthe two together
costthe 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: input and instructions, 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_p and stream.

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.

StatusWhen
400model 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
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
404model is not a model on sale
429the provider is limiting its rate; Retry-After says how many seconds to wait
502the model is down, or answered with nothing usable

Last modified on