POST /chat/completions Create chat completion
Standalone, static reference for the Chat Completions API. Expanded by default. Deep-link to any parameter via the # anchor.
GET /chat/completions List stored chat completions

Overview

Create model responses to chat-style prompts with rich, multi-modal messages, optional tool calls, streaming, web search, and structured outputs.

POST
/chat/completions — Create chat completion
GET
/chat/completions — List stored completions (when store was true)

Examples

Minimal request
{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Write a haiku about recursion." }
  ]
}
Tools + JSON schema + streaming
{
  "model": "gpt-4o",
  "messages": [
    { "role": "developer", "content": "If a city is mentioned, use the weather tool." },
    { "role": "user", "content": "What's the weather in Rome?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Current weather",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "Weather",
      "schema": {
        "type": "object",
        "properties": { "answer": { "type": "string" } },
        "required": ["answer"]
      },
      "strict": true
    }
  },
  "stream": true,
  "stream_options": { "include_usage": true }
}

Core (Required)

#
model
Path: body.model
string required

Model ID to generate the response (e.g., gpt-4o, o3). Choose based on capabilities, performance, and price.

This page does not enumerate all models; see your model guide for availability.
#
messages
Path: body.messages
array<message> required

Conversation history and inputs. Supports text, images, and audio in user messages; tool and function messaging for tool use; and assistant messages for continued turns.

minItems: 1 discriminator: role
Roles & shapes (expanded)

Jump to: developer · system · user · assistant · tool · function (deprecated)

#
messages[].role = developer
Path: body.messages[developer]
role

Developer instructions the model should always follow (supersedes legacy system for certain models).

#
content
Path: body.messages[developer].content
string | array<text-part>

Text instructions. As an array, provide text parts only.

[ { "type": "text", "text": "You are a careful and concise assistant." } ]
#
name
Path: body.messages[developer].name
stringoptional

Optional participant name for disambiguation.

#
messages[].role = system
Path: body.messages[system]
role

Legacy system instructions. For newer models, prefer developer.

#
content
Path: body.messages[system].content
string | array<text-part>

Text instructions.

#
name
Path: body.messages[system].name
stringoptional

Optional participant name.

#
messages[].role = user
Path: body.messages[user]
role

End-user prompts and context. Supports text, images, audio, and file inputs (model-dependent).

#
content
Path: body.messages[user].content
string | array<part>

As an array, include one or more of the parts below.

text content part
#
type
Path: body.messages[user].content[].type
"text"
#
text
Path: body.messages[user].content[].text
string
image_url content part
#
type
Path: body.messages[user].content[].type
"image_url"
#
image_url.url
Path: body.messages[user].content[].image_url.url
string (URL or base64)
#
image_url.detail
Path: body.messages[user].content[].image_url.detail
auto | low | highdefault: auto
input_audio content part
#
type
Path: body.messages[user].content[].type
"input_audio"
#
input_audio.data
Path: body.messages[user].content[].input_audio.data
base64 string
#
input_audio.format
Path: body.messages[user].content[].input_audio.format
wav | mp3
file content part
#
type
Path: body.messages[user].content[].type
"file"
#
file.filename
Path: body.messages[user].content[].file.filename
string
#
file.file_data
Path: body.messages[user].content[].file.file_data
base64 string
#
file.file_id
Path: body.messages[user].content[].file.file_id
string
#
name
Path: body.messages[user].name
stringoptional
#
messages[].role = assistant
Path: body.messages[assistant]
role

Model messages in multi-turn flows. Provide content when continuing; omit it when including tool_calls or legacy function_call.

#
content
Path: body.messages[assistant].content
string | array<text|refusal> | null
#
refusal
Path: body.messages[assistant].refusal
string | null
#
audio.id
Path: body.messages[assistant].audio.id
stringoptional

Reference a previous audio response from the model.

tool_calls (assistant → tool)
#
tool_calls[]
Path: body.messages[assistant].tool_calls[]
function | custom
#
tool_calls[].type = function
Path: body.messages[assistant].tool_calls[].function
object
required: id, type, function
{ "id": "toolcall_1", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Rome\"}" } }
#
tool_calls[].type = custom
Path: body.messages[assistant].tool_calls[].custom
object
required: id, type, custom
{ "id": "toolcall_2", "type": "custom", "custom": { "name": "search", "input": "pizza near 94107" } }
#
function_call
Path: body.messages[assistant].function_call
deprecatedobject | null

Replaced by tool_calls.

#
messages[].role = tool
Path: body.messages[tool]
role
#
content
Path: body.messages[tool].content
string | array<text-part>

Tool output to the model.

#
tool_call_id
Path: body.messages[tool].tool_call_id
stringrequired

Associate the tool’s response with the originating tool_calls[].id.

#
messages[].role = function
Path: body.messages[function]
deprecated

Legacy function channel. Prefer tool messages.

required: content, name

Behavior & Output

#
modalities
Path: body.modalities
array<text|audio> | null

Output types to generate. Text is default; some models can also produce audio.

["text"] or ["text","audio"]
#
verbosity
Path: body.verbosity
low | medium | high default: medium

Guide response length: concise vs. detail. (gpt-5 + reasoning)

#
reasoning_effort
Path: body.reasoning_effort
minimal | low | medium | high default: medium

Constrain reasoning token budget (reasoning models).

#
max_completion_tokens
Path: body.max_completion_tokens
integer | null

Upper bound for generated tokens (includes reasoning tokens).

#
response_format
Path: body.response_format
object

Control the format of the model's output.

Text
{"type":"text"} (default behavior)
JSON schema (Structured Outputs)
#
json_schema
Path: body.response_format.json_schema
object
required: name
#
name
Path: body.response_format.json_schema.name
string
#
schema
Path: body.response_format.json_schema.schema
JSON Schema object
#
strict
Path: body.response_format.json_schema.strict
boolean | nulldefault: false

Enable strict adherence (subset of JSON Schema supported).

JSON object (legacy JSON mode)
{"type":"json_object"}. Prefer json_schema when supported.
#
audio
Path: body.audio
object | null

Required when requesting audio in modalities.

#
voice
Path: body.audio.voice
string

Voices include: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar.

#
format
Path: body.audio.format
wav | aac | mp3 | flac | opus | pcm16

Streaming, Storage & Stops

#
store
Path: body.store
boolean | nulldefault: false

Store the output for distillation/evals. Supports text & image inputs (images > 8MB dropped).

#
stream
Path: body.stream
boolean | nulldefault: false

Return events via Server-Sent Events as tokens are generated.

#
stop
Path: body.stop
string | string[] | null

Up to 4 sequences where generation will stop. Not supported with latest reasoning models o3 and o4-mini.

Default single stop sequence for some text models: <|endoftext|>
#
stream_options
Path: body.stream_options
object | null
#
include_usage
Path: body.stream_options.include_usage
boolean

Emit a final usage summary chunk before [DONE].

#
include_obfuscation
Path: body.stream_options.include_obfuscation
boolean

Normalize SSE payload sizes to mitigate side-channels; disable to save bandwidth.

Sampling & Tuning

#
temperature
Path: body.temperature
number | nulldefault: 1

0–2. Raise for randomness, lower for determinism.

#
top_p
Path: body.top_p
number | nulldefault: 1

Nucleus sampling (0–1). Consider tokens covering the top p probability mass.

#
frequency_penalty
Path: body.frequency_penalty
number | nulldefault: 0

-2 to 2. Reduce repetition proportional to token frequency so far.

#
presence_penalty
Path: body.presence_penalty
number | nulldefault: 0

-2 to 2. Encourage introducing new topics.

#
logit_bias
Path: body.logit_bias
map<tokenId → -100..100> | null

Adjust token selection logit biases. Large magnitudes approximate ban/force.

#
n
Path: body.n
integer | nulldefault: 1

Number of choices to generate (1–128). Billing is proportional to total output tokens.

#
logprobs
Path: body.logprobs
boolean | nulldefault: false

Include log probabilities for output tokens.

#
top_logprobs
Path: body.top_logprobs
integer | null

Top-K (0–20) alternatives per token. Requires logprobs: true.

Tools & Function Calling

#
tools
Path: body.tools
array<tool>

Allow the model to call custom tools or function tools.

Function tool
#
type = "function"
Path: body.tools[].function
object
required: name

parameters is a JSON Schema describing the call signature. strict enforces schema (subset supported).

Custom tool
#
type = "custom"
Path: body.tools[].custom
object

Define a named tool with an input format: free-form text or a grammar (with definition and syntax = lark|regex).

#
tool_choice
Path: body.tool_choice
"none" | "auto" | "required" | object

Control tool use. Defaults to none if no tools; auto if tools present.

Allowed tools

Constrain to a pre-defined set with mode = auto or required, and tools = tool definitions.

Force a specific tool

Function: {"type":"function","function":{"name":"get_weather"}}

Custom: {"type":"custom","custom":{"name":"search"}}

#
parallel_tool_calls
Path: body.parallel_tool_calls
booleandefault: true

Permit parallel function calling.

Prediction, Safety & Caching

#
prediction
Path: body.prediction
object | null

Provide static predicted content to accelerate responses when large parts are known.

{ "type": "content", "content": "Constant file text…" }
#
safety_identifier
Path: body.safety_identifier
string

Stable, hashed identifier to help detect policy violations.

#
prompt_cache_key
Path: body.prompt_cache_key
string

Used for prompt caching in place of legacy user.

#
service_tier
Path: body.service_tier
auto | default | flex | scale | prioritydefault: auto

Request processing tier. Response echoes the tier actually used.

#
metadata
Path: body.metadata
map<string → string> | null

Up to 16 key/value pairs (keys ≤ 64 chars; values ≤ 512 chars) for your own labeling and filtering.

Web Search

#
web_search_options
Path: body.web_search_options
object
#
user_location
Path: body.web_search_options.user_location
object | null
#
type
Path: body.web_search_options.user_location.type
"approximate"
#
approximate
Path: body.web_search_options.user_location.approximate
object
#
country
Path: ...approximate.country
ISO-3166-1 alpha-2
#
region
Path: ...approximate.region
string
#
city
Path: ...approximate.city
string
#
timezone
Path: ...approximate.timezone
IANA TZ
#
search_context_size
Path: body.web_search_options.search_context_size
low | medium | highdefault: medium

Deprecated controls

#
user
Path: body.user
deprecatedstring

Replaced by prompt_cache_key (caching) and used historically as a safety identifier.

#
seed
Path: body.seed
deprecatedinteger | null

Best-effort determinism (Beta). Use system_fingerprint in responses to detect backend changes.

#
max_tokens
Path: body.max_tokens
deprecatedinteger | null

Replaced by max_completion_tokens. Not supported by o‑series reasoning models.

#
function_call
Path: body.function_call
deprecated"none" | "auto" | {"name":string}

Use tool_choice instead.

#
functions
Path: body.functions
deprecatedarray<function>

Replaced by tools.

GET /chat/completions — List stored completions

Returns only completions generated with store: true.

#
Query parameters
Path: GET /chat/completions?…
query
#
model
Path: model=
string

Filter by model ID.

#
metadata
Path: metadata[key]=value
map | null

Filter by metadata pairs. Example: metadata[key1]=v1&metadata[key2]=v2

#
after
Path: after=
string

Use the last completion ID from a previous page to paginate.

#
limit
Path: limit=
integerdefault: 20
#
order
Path: order=
asc | descdefault: asc

Sort by timestamp ascending or descending.

Full Parameter Index (A–Z by path)

Each item links to its definition above.

This page is fully static and linkable. Use the # anchors to deep-link any parameter path.