API reference

Tool calling

Let models call your functions. Works on every model tagged tools in the catalogue, with the OpenAI tools format.

Declare tools in the request

Send a tools array beside your messages using the OpenAI function format. AI Hub translates requests and tool results to the selected provider protocol, and normalizes the answer. Supported schema controls and tool choices depend on the model and route.

json

{
  "model": "deepseek/deepseek-v4-pro",
  "messages": [{"role": "user", "content": "What's 2380 SGD in USD?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "convert_currency",
      "description": "Convert an amount between two currencies",
      "parameters": {
        "type": "object",
        "properties": {
          "amount":  {"type": "number"},
          "from_ccy":{"type": "string"},
          "to_ccy":  {"type": "string"}
        },
        "required": ["amount", "from_ccy", "to_ccy"]
      }
    }
  }]
}

Pick a model that lists tools in supported_parameters. A tool, schema control or tool choice the model does not take is refused. Your application validates arguments and decides which functions may run.

The model asks you to run it

When the model wants a tool, the assistant message carries tool_calls and finish_reason is tool_calls. On a turn that produced only tool calls, content is null or an empty string, depending on the provider; treat both as no text.

json

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_8f2a",
        "type": "function",
        "function": {
          "name": "convert_currency",
          "arguments": "{\"amount\": 2380, \"from_ccy\": \"SGD\", \"to_ccy\": \"USD\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Return the result and continue

Append the assistant message exactly as you received it, then one tool message per call, keyed by tool_call_id. Send the whole conversation back as a fresh request.

json

{
  "model": "deepseek/deepseek-v4-pro",
  "messages": [
    {"role": "user", "content": "What's 2380 SGD in USD?"},
    {"role": "assistant", "tool_calls": [ ...as received... ]},
    {"role": "tool", "tool_call_id": "call_8f2a", "content": "{\"result\": 1845.02}"}
  ]
}

Run the function yourself; the model never executes anything. arguments is a JSON-encoded string, not an object — parse it, and validate it before running.
tool_choice: "auto", "none", "required", or force one with {"type":"function","function":{"name":"…"}}. Omit it and AI Hub sends nothing upstream, so the provider's own default applies. Some thinking models refuse a forced choice; the answer is 400 unsupported_parameter naming tool_choice, and "auto" works.
With streaming, tool calls arrive as deltas: tool_calls fragments carry an index, and the arguments pieces concatenate in arrival order into one JSON string.
Tool-call tokens are metered like any other tokens; the second request in the loop is a normal metered request.
Find capable models by the TOOLS tag on the catalogue, or by supported_parameters containing tools in GET /v1/models.

← PreviousThinking & max_tokens Next →Streaming