Tool Calling

The OpenResponses API supports tool calling to give models access to external functions. Define tools in your request with a name, description, and JSON schema for parameters. When the model determines it needs a tool to answer the user's question, it returns a function_call output with the tool name and arguments for you to execute.

PythonTypeScript

import requests
import json

url = "https://llm.siraya.pro/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_KEY>",
}

data = {
    "model": "google/gemini-3-flash",
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": "What is the weather like in New York?",
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get the current weather in a location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA",
                        },
                    },
                    "required": ["location"],
                },
            },
        }
    ],
    "tool_choice": "auto",
}

response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
result = response.json()

print(json.dumps(result, indent=2))

const response = await fetch('https://llm.siraya.pro/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer <API_KEY>`,
  },
  body: JSON.stringify({
    model: 'google/gemini-3-flash',
    input: [
      {
        type: 'message',
        role: 'user',
        content: 'What is the weather like in New York?',
      },
    ],
    tools: [
      {
        type: 'function',
        function: {
          name: 'get_weather',
          description: 'Get the current weather in a location',
          parameters: {
            type: 'object',
            properties: {
              location: {
                type: 'string',
                description: 'The city and state, e.g. San Francisco, CA',
              },
            },
            required: ['location'],
          },
        },
      },
    ],
    tool_choice: 'auto',
  }),
});

Tool call response

When the model decides to call a tool, the response includes a function_call output:

{
  "id": "resp_ec75a438e41a466293d1b8a310ada9da",
  "object": "realtime.response",
  "created_at": 1771666969,
  "status": "completed",
  "error": null,
  "output_text": "",
  "output": [
    {
      "type": "message",
      "id": "item_e9e961c320be4bc381793e9bab887997",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "As of Saturday afternoon, October 26, 2024, the weather in **New York City** is very pleasant and typical for autumn:\n\n*   **Current Temperature:** 61\u00b0F (16\u00b0C)\n*   **Conditions:** Sunny with clear blue skies.\n*   **High/Low:** A high of 64\u00b0F (18\u00b0C) and a low tonight of 46\u00b0F (8\u00b0C).\n*   **Wind:** 8 mph, making it feel slightly crisp.\n*   **Humidity:** 31% (very dry and comfortable).\n\n**Forecast for tomorrow (Sunday, Oct 27):** It will stay sunny but become a bit cooler, with a high of 58\u00b0F (14\u00b0C) and a low of 40\u00b0F (4\u00b0C).\n\nIf you meant **Upstate New York** (like Albany or Buffalo), it is slightly cooler, with temperatures in the mid-50s and similar sunny conditions.",
          "annotations": null
        }
      ]
    }
  ],
  "model": "gemini-3-flash-preview",
  "incomplete_details": null,
  "max_tool_calls": null,
  "tools": null,
  "tool_choice": null,
  "parallel_tool_calls": false,
  "max_output_tokens": null,
  "temperature": null,
  "top_p": null,
  "metadata": null,
  "background": false,
  "previous_response_id": null,
  "service_tier": "",
  "truncation": null,
  "store": false,
  "instructions": null,
  "reasoning": null,
  "safety_identifier": null,
  "prompt_cache_key": null,
  "user": null,
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 219,
    "total_tokens": 551,
    "completion_tokens_details": {
      "reasoning_tokens": 323
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "ttft": 0,
    "server_tool_use": {
      "web_search_requests": ""
    }
  }
}

Tool choice options

• auto - The model decides whether to call a tool
• required - The model must call at least one tool
• none - The model cannot call any tools