opendunes
Overview
Copy page ▾

Responses · tool calls

POST /v1/responses with your functions in tools lets the model ask for one: it answers with a function_call, your code runs it, and the next request carries the result.

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, like any request on the route: Responses lists every field. Tools and function calling walks through the same loop on Chat.

The tools

FieldNeededYou send
toolsnothe functions the model may call, a list
typeyesin each tool: function
nameyesin each tool: the function's name, which the model's call repeats
descriptionnoin each tool: what it does and when to use it, for the model to read
parametersnoin each tool: a JSON Schema for its arguments
tool_choicenoauto, the model decides; none, no call; required, at least one call; or {"type": "function", "name": ...} to force one
parallel_tool_callsnofalse to have the model call one function at a time; else it may ask for several at once

A request with tools goes to the model's providers that take tools. On a model none of whose providers do, tools is ignored and the model answers in words.

Souk Bot lets the model check the stock before it answers:

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"
CHECK_STOCK = {
    "type": "function",
    "name": "check_stock",
    "description": "How many jackets of one size the Oran shop holds.",
    "parameters": {
        "type": "object",
        "properties": {"size": {"type": "string"}},
        "required": ["size"],
    },
}

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "input": "Do you have this jacket in size M?",
            "tools": [CHECK_STOCK],
        }
    ).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"] == "function_call":
        print(item["call_id"], item["name"], item["arguments"])
print(answer["usage"]["cost"])

The next turn

The route keeps nothing between requests. Your code runs the function, then sends the whole conversation again with two more items in input: the model's call, as it came, and your result. The model then writes its reply.

FieldNeededYou send
function_callyesthe item the model answered with, as it came
function_call_outputyesan item for each call: {"type": "function_call_output", "call_id": ..., "output": ...}
call_idyesin the output: the call_id of the call it answers
outputyesin the output: the result, a string, or a list of input_text, input_image and input_file parts, where the model reads them

Souk Bot's second request, illustrative:

JSON
{
  "model": "anthropic/claude-sonnet-4.5",
  "input": [
    {"role": "user", "content": "Do you have this jacket in size M?"},
    {
      "type": "function_call",
      "call_id": "toolu_01A9",
      "name": "check_stock",
      "arguments": "{\"size\": \"M\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "toolu_01A9",
      "output": "{\"size\": \"M\", \"in_stock\": 4}"
    }
  ],
  "tools": [{"type": "function", "name": "check_stock"}]
}

Response

200 OK. When the model calls a function, output holds a function_call item and status is completed: the turn is the model's request to you. Illustrative:

JSON
{
  "type": "function_call",
  "id": "fc_7c3a91e4",
  "call_id": "toolu_01A9",
  "name": "check_stock",
  "arguments": "{\"size\": \"M\"}",
  "status": "completed"
}
FieldHolds
typefunction_call
idthe item's id
call_idthe call's id, which your function_call_output repeats
namethe function the model calls, one of your tools
argumentsits arguments, a JSON string that follows your parameters schema; parse it before use
statuscompleted once the arguments are whole

Several calls in one turn are several function_call items, each with its own call_id: run them all and send every result back.

With stream: true. response.output_item.added opens the function_call item, response.function_call_arguments.delta carries each next piece of its arguments, response.function_call_arguments.done the whole of them, and response.completed ends the stream with usage, cost among it.

What it cost

Charged in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → from your balanceBalanceWhat you can spend, in DA.More on Balance and charges → on each request: the tokens the model reports, at the model's rates, which its model page shows. usage.cost carries the charge. A call and its result take two requests, each charged.

  • Moves the count: tools, whose definitions are sent as input on every turn; the function_call and function_call_output items sent back, counted as input; the call the model writes, counted as output.
  • Changes the answer, never the bill: tool_choice and parallel_tool_calls.

Running your function costs nothing here: it runs in your code.

Errors

An error keeps the Responses shape: Responses · errors lists every status and every word.

StatusWhen
400a tool has no type or name, a field has the wrong type, or the provider refused a tool or a result, such as one whose call_id matches no call in input
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

Last modified on