POST
/
v1
/
chat
/
completions
Chat Completions Function Calling
curl --request POST \
  --url https://api.example.com/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {}
  ],
  "tools": [
    {}
  ],
  "tool_choice": {},
  "temperature": 123,
  "max_tokens": 123
}
'
Enable the model to call functions and use external tools during chat completions.

​
Overview

Function calling allows you to describe functions to the model and have it intelligently choose to output a JSON object containing arguments to call those functions. This enables integration with external APIs, databases, and other tools.

​
Authentication

All requests require a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Request Parameters

​
model
string
required
ID of the model to use. Example: gpt-4, gpt-4-turbo, gpt-4o
​
messages
array
required
A list of messages comprising the conversation so far.
​
tools
array
required
A list of tools the model may call. Currently, only functions are supported.
​
tool_choice
string | object
default:"auto"
Controls which tool is called. Options: none, auto, required, or specify a function.
​
temperature
number
default:"1"
Sampling temperature between 0 and 2.
​
max_tokens
integer
Maximum number of tokens to generate.

​
Request Example

curl -X POST https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "What is the weather like in Boston?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

​
Response Example

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Boston, MA\", \"unit\": \"fahrenheit\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 18,
    "total_tokens": 100
  }
}

​
Tool Choice Options

ValueDescription
noneModel will not call any tools
autoModel decides whether to call tools (default)
requiredModel must call one or more tools
{"type": "function", "function": {"name": "my_function"}}Force a specific function

​
Available Models

  • gpt-4
  • gpt-4-turbo
  • gpt-4o
  • gpt-4o-mini
  • gpt-3.5-turbo