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
| Field | Needed | You send |
|---|---|---|
tools | no | the functions the model may call, a list |
type | yes | in each tool: function |
name | yes | in each tool: the function's name, which the model's call repeats |
description | no | in each tool: what it does and when to use it, for the model to read |
parameters | no | in each tool: a JSON Schema for its arguments |
tool_choice | no | auto, the model decides; none, no call; required, at least one call; or {"type": "function", "name": ...} to force one |
parallel_tool_calls | no | false 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.
| Field | Needed | You send |
|---|---|---|
function_call | yes | the item the model answered with, as it came |
function_call_output | yes | an item for each call: {"type": "function_call_output", "call_id": ..., "output": ...} |
call_id | yes | in the output: the call_id of the call it answers |
output | yes | in 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:
{
"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:
{
"type": "function_call",
"id": "fc_7c3a91e4",
"call_id": "toolu_01A9",
"name": "check_stock",
"arguments": "{\"size\": \"M\"}",
"status": "completed"
}| Field | Holds |
|---|---|
type | function_call |
id | the item's id |
call_id | the call's id, which your function_call_output repeats |
name | the function the model calls, one of your tools |
arguments | its arguments, a JSON string that follows your parameters schema; parse it before use |
status | completed 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; thefunction_callandfunction_call_outputitems sent back, counted as input; the call the model writes, counted as output. - Changes the answer, never the bill:
tool_choiceandparallel_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.
| Status | When |
|---|---|
| 400 | a 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 |
| 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 |
| 404 | model is not a model on sale |
Last modified on