Chat Completions

curl --request POST \
  --url https://api.example.com/v1/chat/completions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {}
  ],
  "tools": [
    {}
  ],
  "tool_choice": {},
  "parallel_tool_calls": true,
  "stream": true,
  "stream_options": {},
  "temperature": 123,
  "top_p": 123,
  "max_tokens": 123,
  "max_completion_tokens": 123,
  "response_format": {},
  "stop": {},
  "presence_penalty": 123,
  "frequency_penalty": 123,
  "logprobs": true,
  "top_logprobs": 123,
  "seed": 123,
  "n": 123
}
'

import requests

url = "https://api.example.com/v1/chat/completions"

payload = {
    "model": "<string>",
    "messages": [{}],
    "tools": [{}],
    "tool_choice": {},
    "parallel_tool_calls": True,
    "stream": True,
    "stream_options": {},
    "temperature": 123,
    "top_p": 123,
    "max_tokens": 123,
    "max_completion_tokens": 123,
    "response_format": {},
    "stop": {},
    "presence_penalty": 123,
    "frequency_penalty": 123,
    "logprobs": True,
    "top_logprobs": 123,
    "seed": 123,
    "n": 123
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    messages: [{}],
    tools: [{}],
    tool_choice: {},
    parallel_tool_calls: true,
    stream: true,
    stream_options: {},
    temperature: 123,
    top_p: 123,
    max_tokens: 123,
    max_completion_tokens: 123,
    response_format: {},
    stop: {},
    presence_penalty: 123,
    frequency_penalty: 123,
    logprobs: true,
    top_logprobs: 123,
    seed: 123,
    n: 123
  })
};

fetch('https://api.example.com/v1/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/chat/completions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'messages' => [
        [
                
        ]
    ],
    'tools' => [
        [
                
        ]
    ],
    'tool_choice' => [
        
    ],
    'parallel_tool_calls' => true,
    'stream' => true,
    'stream_options' => [
        
    ],
    'temperature' => 123,
    'top_p' => 123,
    'max_tokens' => 123,
    'max_completion_tokens' => 123,
    'response_format' => [
        
    ],
    'stop' => [
        
    ],
    'presence_penalty' => 123,
    'frequency_penalty' => 123,
    'logprobs' => true,
    'top_logprobs' => 123,
    'seed' => 123,
    'n' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {},\n  \"parallel_tool_calls\": true,\n  \"stream\": true,\n  \"stream_options\": {},\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"max_tokens\": 123,\n  \"max_completion_tokens\": 123,\n  \"response_format\": {},\n  \"stop\": {},\n  \"presence_penalty\": 123,\n  \"frequency_penalty\": 123,\n  \"logprobs\": true,\n  \"top_logprobs\": 123,\n  \"seed\": 123,\n  \"n\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/chat/completions")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {},\n  \"parallel_tool_calls\": true,\n  \"stream\": true,\n  \"stream_options\": {},\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"max_tokens\": 123,\n  \"max_completion_tokens\": 123,\n  \"response_format\": {},\n  \"stop\": {},\n  \"presence_penalty\": 123,\n  \"frequency_penalty\": 123,\n  \"logprobs\": true,\n  \"top_logprobs\": 123,\n  \"seed\": 123,\n  \"n\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/chat/completions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {},\n  \"parallel_tool_calls\": true,\n  \"stream\": true,\n  \"stream_options\": {},\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"max_tokens\": 123,\n  \"max_completion_tokens\": 123,\n  \"response_format\": {},\n  \"stop\": {},\n  \"presence_penalty\": 123,\n  \"frequency_penalty\": 123,\n  \"logprobs\": true,\n  \"top_logprobs\": 123,\n  \"seed\": 123,\n  \"n\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "<string>",
  "created": 123,
  "model": "<string>",
  "choices": [
    {}
  ],
  "usage": {}
}

POST

chat

completions

Chat Completions

curl --request POST \
  --url https://api.example.com/v1/chat/completions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {}
  ],
  "tools": [
    {}
  ],
  "tool_choice": {},
  "parallel_tool_calls": true,
  "stream": true,
  "stream_options": {},
  "temperature": 123,
  "top_p": 123,
  "max_tokens": 123,
  "max_completion_tokens": 123,
  "response_format": {},
  "stop": {},
  "presence_penalty": 123,
  "frequency_penalty": 123,
  "logprobs": true,
  "top_logprobs": 123,
  "seed": 123,
  "n": 123
}
'

import requests

url = "https://api.example.com/v1/chat/completions"

payload = {
    "model": "<string>",
    "messages": [{}],
    "tools": [{}],
    "tool_choice": {},
    "parallel_tool_calls": True,
    "stream": True,
    "stream_options": {},
    "temperature": 123,
    "top_p": 123,
    "max_tokens": 123,
    "max_completion_tokens": 123,
    "response_format": {},
    "stop": {},
    "presence_penalty": 123,
    "frequency_penalty": 123,
    "logprobs": True,
    "top_logprobs": 123,
    "seed": 123,
    "n": 123
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    messages: [{}],
    tools: [{}],
    tool_choice: {},
    parallel_tool_calls: true,
    stream: true,
    stream_options: {},
    temperature: 123,
    top_p: 123,
    max_tokens: 123,
    max_completion_tokens: 123,
    response_format: {},
    stop: {},
    presence_penalty: 123,
    frequency_penalty: 123,
    logprobs: true,
    top_logprobs: 123,
    seed: 123,
    n: 123
  })
};

fetch('https://api.example.com/v1/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/chat/completions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'messages' => [
        [
                
        ]
    ],
    'tools' => [
        [
                
        ]
    ],
    'tool_choice' => [
        
    ],
    'parallel_tool_calls' => true,
    'stream' => true,
    'stream_options' => [
        
    ],
    'temperature' => 123,
    'top_p' => 123,
    'max_tokens' => 123,
    'max_completion_tokens' => 123,
    'response_format' => [
        
    ],
    'stop' => [
        
    ],
    'presence_penalty' => 123,
    'frequency_penalty' => 123,
    'logprobs' => true,
    'top_logprobs' => 123,
    'seed' => 123,
    'n' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {},\n  \"parallel_tool_calls\": true,\n  \"stream\": true,\n  \"stream_options\": {},\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"max_tokens\": 123,\n  \"max_completion_tokens\": 123,\n  \"response_format\": {},\n  \"stop\": {},\n  \"presence_penalty\": 123,\n  \"frequency_penalty\": 123,\n  \"logprobs\": true,\n  \"top_logprobs\": 123,\n  \"seed\": 123,\n  \"n\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/chat/completions")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {},\n  \"parallel_tool_calls\": true,\n  \"stream\": true,\n  \"stream_options\": {},\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"max_tokens\": 123,\n  \"max_completion_tokens\": 123,\n  \"response_format\": {},\n  \"stop\": {},\n  \"presence_penalty\": 123,\n  \"frequency_penalty\": 123,\n  \"logprobs\": true,\n  \"top_logprobs\": 123,\n  \"seed\": 123,\n  \"n\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/chat/completions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"tool_choice\": {},\n  \"parallel_tool_calls\": true,\n  \"stream\": true,\n  \"stream_options\": {},\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"max_tokens\": 123,\n  \"max_completion_tokens\": 123,\n  \"response_format\": {},\n  \"stop\": {},\n  \"presence_penalty\": 123,\n  \"frequency_penalty\": 123,\n  \"logprobs\": true,\n  \"top_logprobs\": 123,\n  \"seed\": 123,\n  \"n\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "<string>",
  "created": 123,
  "model": "<string>",
  "choices": [
    {}
  ],
  "usage": {}
}

Overview

The /v1/chat/completions endpoint provides full OpenAI Chat Completions API compatibility. It accepts chat-formatted messages and maps them internally to the Responses API format while preserving streaming behavior and tool calling capabilities.

Authentication

string

required

Bearer token for API authentication. Format: Bearer YOUR_API_KEY

Request Body

string

required

ID of the model to use. Must be a valid model slug from the /v1/models endpoint.Example: "gpt-4.1", "gpt-5.2"

array

required

Array of message objects representing the conversation history. Must contain at least one message.Each message object has:

role (string, required): One of "system", "developer", "user", "assistant", or "tool"
content (string | array): Message content. For system/developer roles, must be text-only.
tool_calls (array, optional): For assistant messages, array of tool call objects
tool_call_id (string, required for tool role): ID of the tool call this message responds to

array

Array of tool definitions available to the model.Each tool object:

type (string): "function" or "web_search"
function (object): For function tools, contains name, description, and parameters

Supported tool types:

function: Custom function calls
web_search or web_search_preview: Web search capability

Unsupported types (will return error):

file_search, code_interpreter, computer_use, computer_use_preview, image_generation

string | object

Controls which tool the model should use.Options:

"none": Model will not call tools
"auto": Model decides whether to call tools
"required": Model must call at least one tool
Object with {"type": "function", "function": {"name": "tool_name"}}: Force specific tool

boolean

Whether to enable parallel tool calling. When true, the model can call multiple tools simultaneously.

boolean

default:false

Whether to stream the response as server-sent events.

true: Returns text/event-stream with chat.completion.chunk objects
false: Returns a single chat.completion object

object

Options for streaming responses.Properties:

include_usage (boolean): Include token usage in final chunk
include_obfuscation (boolean): Include obfuscation data in stream

number

Sampling temperature between 0 and 2. Higher values make output more random.

number

Nucleus sampling parameter. Alternative to temperature.

integer

Maximum number of tokens to generate. Alias for max_completion_tokens.

integer

Maximum number of tokens in the completion.

object

Format for the model’s output.Options:

{"type": "text"}: Plain text (default)
{"type": "json_object"}: Valid JSON object
{"type": "json_schema", "json_schema": {...}}: JSON matching provided schema

For json_schema type:

json_schema.name (string): Schema name, 1-64 chars, alphanumeric/underscore/hyphen
json_schema.schema (object): JSON Schema definition
json_schema.strict (boolean): Enable strict schema adherence

string | array

Stop sequence(s). Generation stops when these tokens are encountered.

number

Penalty for token presence. Range: -2.0 to 2.0.

number

Penalty for token frequency. Range: -2.0 to 2.0.

boolean

Whether to return log probabilities of output tokens.

integer

Number of most likely tokens to return at each position (requires logprobs: true).

integer

Random seed for deterministic sampling.

integer

default:1

Number of completions to generate. Must be 1 (only value supported).

Response (Non-Streaming)

When stream is false or omitted, returns a chat.completion object:

string

Unique identifier for the completion.

string

Always "chat.completion".

integer

Unix timestamp of creation.

string

Model used for completion.

array

Array of completion choices (always contains one choice).Each choice object:

index (integer): Choice index (always 0)
message (object): The assistant’s message
- role (string): Always "assistant"
- content (string | null): Text content of the message
- refusal (string | null): Refusal message if model declined
- tool_calls (array | null): Tool calls made by the model
finish_reason (string): Why generation stopped
- "stop": Natural completion
- "length": Max tokens reached
- "tool_calls": Model called tools
- "content_filter": Content filtered

object

Token usage information.Properties:

prompt_tokens (integer): Tokens in the prompt
completion_tokens (integer): Tokens in the completion
total_tokens (integer): Total tokens used
prompt_tokens_details (object | null):
- cached_tokens (integer): Cached prompt tokens
completion_tokens_details (object | null):
- reasoning_tokens (integer): Tokens used for reasoning

Response (Streaming)

When stream is true, returns text/event-stream with chat.completion.chunk objects:

string

Unique identifier for the chunk stream.

string

Always "chat.completion.chunk".

integer

Unix timestamp of creation.

string

Model being used.

array

Array of delta choices.Each choice contains:

index (integer): Always 0
delta (object): Incremental content
- role (string | null): Role (only in first chunk)
- content (string | null): Content delta
- refusal (string | null): Refusal delta
- tool_calls (array | null): Tool call deltas
finish_reason (string | null): Reason when complete

object | null

Token usage (only in final chunk when stream_options.include_usage is true).

Examples

Basic Chat Completion

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

Streaming Response

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "Write a haiku about coding"}
    ],
    "stream": true
  }'

Streaming with Usage

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      {"role": "user", "content": "Explain quantum computing"}
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

Tool Calling

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City name"
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Web Search Tool

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What are the latest news about AI?"}
    ],
    "tools": [
      {"type": "web_search"}
    ]
  }'

JSON Schema Response Format

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "Generate a person profile"}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person_profile",
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "age": {"type": "number"},
            "city": {"type": "string"}
          },
          "required": ["name", "age"]
        },
        "strict": true
      }
    }
  }'

Multi-turn Conversation

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "system", "content": "You are a helpful math tutor."},
      {"role": "user", "content": "What is 25 * 4?"}
    ]
  }'

Content Type Restrictions

System and Developer Messages

Must contain text-only content
Cannot include images, files, or other media types
Violations return 400 with invalid_request_error

User Messages

Supported content types:

Text: String or {"type": "text", "text": "..."}
Images: {"type": "image_url", "image_url": {"url": "..."}}
- Data URLs and HTTP(S) URLs supported
- Images over 8MB are automatically dropped
Files: {"type": "file", "file": {...}}
- file_id is not supported and will return error

Unsupported:

Audio input: input_audio type returns 400 error

Assistant Messages

Can include content (text) and/or tool_calls
Tool calls must have valid id and function with name

Tool Messages

Must include tool_call_id matching a previous assistant tool call
Content becomes the tool output

Error Handling

All errors return OpenAI-compatible error envelopes:

{
  "error": {
    "message": "Error description",
    "type": "invalid_request_error",
    "code": "error_code",
    "param": "field_name"
  }
}

Common error codes:

invalid_request_error: Invalid request parameters
model_not_allowed: API key lacks access to requested model
no_accounts: No upstream accounts available
upstream_error: Upstream service error

For streaming requests, errors are emitted as error chunks followed by data: [DONE].

Model Restrictions

If your API key has allowed_models configured, only those models can be used. Requests for other models return:

{
  "error": {
    "message": "This API key does not have access to model 'gpt-5.2'",
    "type": "invalid_request_error",
    "code": "model_not_allowed"
  }
}

Check available models at /v1/models.

⌘I

Overview

OpenAI-Compatible Endpoints

Codex Endpoints

Management API

Chat Completions

Overview

Authentication

Request Body

Response (Non-Streaming)

Response (Streaming)

Examples

Basic Chat Completion

Streaming Response

Streaming with Usage

Tool Calling

Web Search Tool

JSON Schema Response Format

Multi-turn Conversation

Content Type Restrictions

System and Developer Messages

User Messages

Assistant Messages

Tool Messages

Error Handling

Model Restrictions

​Overview

​Authentication

​Request Body

​Response (Non-Streaming)

​Response (Streaming)

​Examples

​Basic Chat Completion

​Streaming Response

​Streaming with Usage

​Tool Calling

​Web Search Tool

​JSON Schema Response Format

​Multi-turn Conversation

​Content Type Restrictions

​System and Developer Messages

​User Messages

​Assistant Messages

​Tool Messages

​Error Handling

​Model Restrictions

Overview

Authentication

Request Body

Response (Non-Streaming)

Response (Streaming)

Examples

Basic Chat Completion

Streaming Response

Streaming with Usage

Tool Calling

Web Search Tool

JSON Schema Response Format

Multi-turn Conversation

Content Type Restrictions

System and Developer Messages

User Messages

Assistant Messages

Tool Messages

Error Handling

Model Restrictions