Chat completions schemas
The full schema and model definitions referenced by the Create a chat completion endpoint, including the request and response object shapes.
Schemas
Chat Completion Message Tool Call
A function tool call emitted by the model.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier for this tool call. |
type | enum ('function') | Yes | Tool type; always function. |
function | object | Yes | The function the model chose to call. |
function.name | string | Yes | Name of the function to call. |
function.arguments | string | Yes | Call arguments the model generated, as a JSON string. The model can emit invalid JSON or arguments outside your schema, so validate before invoking the function. |
Chat Completion Message Tool Call Chunk
| Field | Type | Required | Description |
|---|---|---|---|
index | integer | Yes | |
id | string | No | Identifier for this tool call. |
type | enum ('function') | No | Tool type; always function. |
function | object | No | |
function.name | string | No | Name of the function to call. |
function.arguments | string | No | Function arguments generated by the model, as a JSON string. The model can produce invalid JSON or arguments outside your schema, so validate before executing. |
Chat Completion Message Tool Calls
The tool calls the model generated, such as function calls.
Type: array of ChatCompletionMessageToolCall
Chat Completion Request Assistant Message
An assistant message holding a previous model response in the conversation.
| Field | Type | Required | Description |
|---|---|---|---|
content | string | array of ChatCompletionRequestAssistantMessageContentPart | null | No | |
refusal | string | null | No | |
reasoning_content | string | null | No | |
reasoning | string | null | No | |
role | enum ('assistant') | Yes | Role of the message author; always assistant. |
name | string | No | Optional name for this participant, used to distinguish participants that share a role. |
tool_calls | ChatCompletionMessageToolCalls | No |
Chat Completion Request Assistant Message Content Part
Type: ChatCompletionRequestMessageContentPartText | ChatCompletionRequestMessageContentPartRefusal
Chat Completion Request Developer Message
Developer-provided instructions that the model should follow, regardless of messages sent by the user. developer messages take precedence over system messages.
| Field | Type | Required | Description |
|---|---|---|---|
content | string | array of ChatCompletionRequestMessageContentPartText | Yes | Developer message content. |
role | enum ('developer') | Yes | Role of the message author; always developer. |
name | string | No | Optional name for this participant, used to distinguish participants that share a role. |
Chat Completion Request Message
Type: ChatCompletionRequestDeveloperMessage | ChatCompletionRequestSystemMessage | ChatCompletionRequestUserMessage | ChatCompletionRequestAssistantMessage | ChatCompletionRequestToolMessage
Chat Completion Request Message Content Part Audio
Audio input content for a message.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_audio') | Yes | The type of the content part. Always input_audio. |
input_audio | object | No | |
input_audio.data | string | Yes | Base64 encoded audio data. |
input_audio.format | enum ('wav', 'mp3') | Yes | The format of the encoded audio data. Currently supports "wav" and "mp3". |
audio_url | string | No | URL of the audio to send to the model. Fully qualified URL or base64-encoded data URL. |
file_id | string | No | Identifier for the uploaded audio file to send to the model. |
Chat Completion Request Message Content Part File
File input content for a message.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('file') | Yes | Content-part type; always file. |
file | object | Yes | |
file.filename | string | No | Filename to associate with file data passed inline. |
file.file_data | string | No | Base64-encoded file contents passed inline. |
file.file_id | string | No | Identifier of an uploaded file to use as input. |
Chat Completion Request Message Content Part Image
Image input content for a message.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('image_url') | Yes | Content-part type; always image_url. |
image_url | object | Yes | |
image_url.url | string (uri) | Yes | Public URL or base64 data URL of the image. |
image_url.detail | enum ('auto', 'low', 'high') | No | Specifies the detail level of the image. (default: auto) |
Chat Completion Request Message Content Part Refusal
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('refusal') | Yes | Content-part type; always refusal. |
refusal | string | Yes | Refusal message generated by the model. |
Chat Completion Request Message Content Part Text
Text input content for a message.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('text') | Yes | Content-part type; always text. |
text | string | Yes | Text of this content part. |
Chat Completion Request Message Content Part Video
A video input to the model. Provided as a URL or a base64 data URI.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('video_url') | Yes | The type of the content part. |
video_url | object | Yes | |
video_url.url | string (uri) | Yes | Either a URL of the video or the base64 encoded video data. |
video_url.fps | number | null | No |
Chat Completion Request System Message
Instructions that the model should follow, regardless of messages sent by the user. developer messages take precedence over system messages.
| Field | Type | Required | Description |
|---|---|---|---|
content | string | array of ChatCompletionRequestSystemMessageContentPart | Yes | System message content. |
role | enum ('system') | Yes | Role of the message author; always system. |
name | string | No | Optional name for this participant, used to distinguish participants that share a role. |
Chat Completion Request System Message Content Part
Type: ChatCompletionRequestMessageContentPartText
Chat Completion Request Tool Message
| Field | Type | Required | Description |
|---|---|---|---|
role | enum ('tool') | Yes | Role of the message author; always tool. |
content | string | array of ChatCompletionRequestToolMessageContentPart | Yes | Tool message content carrying the result of a tool call. |
tool_call_id | string | Yes | Identifier of the tool call this message responds to. |
Chat Completion Request Tool Message Content Part
Type: ChatCompletionRequestMessageContentPartText
Chat Completion Request User Message
A user message carrying end-user input such as a prompt or additional context.
| Field | Type | Required | Description |
|---|---|---|---|
content | string | array of ChatCompletionRequestUserMessageContentPart | Yes | User message content. |
role | enum ('user') | Yes | Role of the message author; always user. |
name | string | No | Optional name for this participant, used to distinguish participants that share a role. |
Chat Completion Request User Message Content Part
Type: ChatCompletionRequestMessageContentPartText | ChatCompletionRequestMessageContentPartImage | ChatCompletionRequestMessageContentPartAudio | ChatCompletionRequestMessageContentPartFile | ChatCompletionRequestMessageContentPartVideo
Chat Completion Response Message
The message the model generated for a choice.
| Field | Type | Required | Description |
|---|---|---|---|
content | string | null | Yes | |
refusal | string | null | Yes | |
tool_calls | ChatCompletionMessageToolCalls | No | |
annotations | array of object | No | Annotations for the message, when applicable, as when using the web search tool. |
annotations[].type | enum ('url_citation') | Yes | Annotation type; always url_citation. |
annotations[].url_citation | object | Yes | Details of a web source cited by the model. |
annotations[].url_citation.end_index | integer | Yes | Character offset in the message content where the cited span ends. |
annotations[].url_citation.start_index | integer | Yes | Character offset in the message content where the cited span begins. |
annotations[].url_citation.url | string (uri) | Yes | URL of the cited source. |
annotations[].url_citation.title | string | Yes | Title of the cited source. |
reasoning_content | string | null | No | |
role | enum ('assistant') | Yes | Role of the message author. |
Chat Completion Stream Options
Type: object | null
Chat Completion Stream Response Delta
An incremental message delta from a streamed completion.
| Field | Type | Required | Description |
|---|---|---|---|
content | string | null | No | |
reasoning_content | string | null | No | |
tool_calls | array of ChatCompletionMessageToolCallChunk | No | |
role | enum ('developer', 'system', 'user', 'assistant', 'tool') | No | Role of the message author. |
refusal | string | null | No |
Chat Completion Token Logprob
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | A single text token. |
logprob | number | Yes | Log probability of this token. Tokens outside the top 20 report -9999.0. |
bytes | array of integer | null | Yes | |
top_logprobs | array of object | Yes | List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested top_logprobs returned. |
top_logprobs[].token | string | Yes | A candidate text token. |
top_logprobs[].logprob | number | Yes | Log probability of this token. Tokens outside the top 20 report -9999.0. |
top_logprobs[].bytes | array of integer | null | Yes |
Chat Completion Tool
A function the model can call.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('function') | Yes | Tool type; always function. |
function | FunctionObject | Yes |
Chat Completion Tool Choice Option
auto lets the model choose between replying with a message and making one or more tool calls. Defaults to auto when tools are supplied.
Type: enum ('auto')
Completion Usage
Token usage for the request.
| Field | Type | Required | Description |
|---|---|---|---|
completion_tokens | integer | Yes | Tokens in the generated completion. (default: 0) |
prompt_tokens | integer | Yes | Tokens in the prompt. (default: 0) |
total_tokens | integer | Yes | Total tokens used, prompt plus completion. (default: 0) |
completion_tokens_details | object | No | Breakdown of the completion tokens. |
completion_tokens_details.reasoning_tokens | integer | No | Tokens the model spent on reasoning. (default: 0) |
prompt_tokens_details | object | No | Breakdown of the prompt tokens. |
prompt_tokens_details.cached_tokens | integer | No | Prompt tokens served from cache. (default: 0) |
Create Chat Completion Request
| Field | Type | Required | Description |
|---|---|---|---|
metadata | Metadata | No | |
top_logprobs | integer | No | An integer between 0 and 20 giving the number of top alternative tokens to return at each position, each with its log probability. Requires logprobs: true. (minimum: 0, maximum: 20) |
temperature | number | null | No | |
top_p | number | null | No | |
user | string | No | Being replaced by safety_identifier and prompt_cache_key; use prompt_cache_key to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse. |
safety_identifier | string | No | A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64) |
prompt_cache_key | string | No | Groups similar requests to improve cache hit rates. Replaces the user field. |
service_tier | ServiceTier | No | |
prompt_cache_retention | enum ('in_memory', '24h') | null | No | |
messages | array of ChatCompletionRequestMessage | Yes | An ordered list of the messages in the conversation. Each message has a role and content, and the model reads them in sequence to produce its reply. (minItems: 1) |
model | string | Yes | ID of the model used to generate the response. |
modalities | ResponseModalities | No | |
reasoning_effort | ReasoningEffort | No | |
max_completion_tokens | integer | No | Upper bound on the tokens the model may generate for a completion, counting both visible output and reasoning tokens. |
frequency_penalty | number | No | Penalizes tokens in proportion to how often they have already appeared, reducing verbatim repetition. Ranges from -2.0 to 2.0; positive values discourage repetition. (minimum: -2, maximum: 2, default: 0) |
presence_penalty | number | No | Penalizes tokens that have already appeared at all, nudging the model toward new topics. Ranges from -2.0 to 2.0; positive values increase that push. (minimum: -2, maximum: 2, default: 0) |
response_format | ResponseFormatText | ResponseFormatJsonSchema | ResponseFormatJsonObject | No | Constrains the format of the model's output. Use { "type": "json_schema", ... } for Structured Outputs, which forces the response to match your JSON schema, or { "type": "json_object" } for the older JSON mode, which only guarantees valid JSON. Prefer json_schema. |
store | boolean | No | Whether or not to store the output of this chat completion request for use in our model distillation or evals products. Supports text and image inputs. Note: image inputs over 8MB will be dropped. (default: false) |
stream | boolean | No | When true, the response is streamed incrementally as server-sent events(opens in new tab) rather than returned in a single payload. (default: false) |
stop | StopConfiguration | No | |
logprobs | boolean | No | When true, returns the log probability of each token in the message content. (default: false) |
max_tokens | integer | No | The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of max_completion_tokens. |
n | integer | No | Number of completions to generate for the input. Only n=1 is supported. (minimum: 1, maximum: 128, default: 1) |
seed | integer | No | If set, the system makes a best-effort attempt to sample deterministically, so repeated requests with the same seed and parameters return similar results. Determinism is not guaranteed. (minimum: -9223372036854776000, maximum: 9223372036854776000) |
stream_options | ChatCompletionStreamOptions | No | |
tools | array of ChatCompletionTool | No | A list of tools the model may call. You can provide either custom tools or function tools. |
tool_choice | ChatCompletionToolChoiceOption | No | |
parallel_tool_calls | ParallelToolCalls | No |
Create Chat Completion Response
A chat completion produced by the model for a given request.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier for this chat completion. |
choices | array of object | Yes | List of completion choices. Only one choice is returned; n greater than 1 returns HTTP 400. |
choices[].finish_reason | enum ('stop', 'length', 'tool_calls', 'content_filter', 'function_call') | Yes | Why the model stopped generating tokens: stop for a natural end, length when the output-token limit was reached, and tool_calls when the model requested a tool. content_filter and the deprecated function_call may also appear. |
choices[].index | integer | Yes | Index of this choice in the choices array. |
choices[].message | ChatCompletionResponseMessage | Yes | |
choices[].logprobs | object | null | Yes | |
created | integer (unixtime) | Yes | Unix timestamp, in seconds, when the chat completion was created. |
model | string | Yes | ID of the model that generated the completion. |
service_tier | ServiceTier | No | |
system_fingerprint | string | No | Identifies the backend configuration the model ran with, for use with seed to detect determinism-affecting changes. Not currently populated. |
object | enum ('chat.completion') | Yes | Object type; always chat.completion. |
usage | CompletionUsage | No |
Create Chat Completion Stream Response
A single streamed chunk of a chat completion, delivered as a server-sent event.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier for this chat completion. Identical across every chunk in the stream. |
choices | array of object | Yes | List of completion choices. Contains a single choice, and is empty on the final chunk when stream_options.include_usage is set. |
choices[].delta | ChatCompletionStreamResponseDelta | Yes | |
choices[].logprobs | object | No | Log-probability data for this choice. |
choices[].logprobs.content | array of ChatCompletionTokenLogprob | Yes | Content tokens with their log probabilities. |
choices[].logprobs.refusal | array of ChatCompletionTokenLogprob | Yes | Refusal tokens with their log probabilities. |
choices[].finish_reason | enum ('stop', 'length', 'tool_calls', 'content_filter', 'function_call') | Yes | Why the model stopped generating tokens: stop for a natural end, length when the output-token limit was reached, and tool_calls when the model requested a tool. content_filter and the deprecated function_call may also appear. |
choices[].index | integer | Yes | Index of this choice in the choices array. |
created | integer (unixtime) | Yes | Unix timestamp, in seconds, when the chat completion was created. Identical across every chunk in the stream. |
model | string | Yes | ID of the model that generated the completion. |
service_tier | ServiceTier | No | |
system_fingerprint | string | No | Identifies the backend configuration the model ran with, for use with seed to detect determinism-affecting changes. Not currently populated. |
object | enum ('chat.completion.chunk') | Yes | Object type; always chat.completion.chunk. |
usage | CompletionUsage | No | Token usage for the entire request. Present only when stream_options.include_usage is set, and populated only on the final chunk; null on all earlier chunks. An interrupted or cancelled stream may omit this chunk. |
Create Model Response Properties
| Field | Type | Required | Description |
|---|---|---|---|
metadata | Metadata | No | |
top_logprobs | integer | No | An integer between 0 and 20 giving the number of top alternative tokens to return at each position, each with its log probability. (minimum: 0, maximum: 20) |
temperature | number | null | No | |
top_p | number | null | No | |
user | string | No | Being replaced by safety_identifier and prompt_cache_key; use prompt_cache_key to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse. |
safety_identifier | string | No | A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64) |
prompt_cache_key | string | No | Groups similar requests to improve cache hit rates. Replaces the user field. |
service_tier | ServiceTier | No | |
prompt_cache_retention | enum ('in_memory', '24h') | null | No |
Function Object
| Field | Type | Required | Description |
|---|---|---|---|
description | string | No | Tells the model what the function does, so it can decide when and how to call it. |
name | string | Yes | Name of the function to call. May contain letters, digits, underscores, dashes, and at most one dot. |
parameters | FunctionParameters | No | |
strict | boolean | null | No |
Function Parameters
The parameters the functions accepts, described as a JSON Schema object. See the JSON Schema reference(opens in new tab) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
Type: object
Metadata
Type: object | null
Model Response Properties
| Field | Type | Required | Description |
|---|---|---|---|
metadata | Metadata | No | |
top_logprobs | integer | null | No | |
temperature | number | null | No | |
top_p | number | null | No | |
user | string | No | Being replaced by safety_identifier and prompt_cache_key; use prompt_cache_key to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse. |
safety_identifier | string | No | A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64) |
prompt_cache_key | string | No | Groups similar requests to improve cache hit rates. Replaces the user field. |
service_tier | ServiceTier | No | |
prompt_cache_retention | enum ('in_memory', '24h') | null | No |
Parallel Tool Calls
Whether to enable parallel function calling during tool use.
Type: boolean
Reasoning Effort
Type: enum ('none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max') | null
Response Format Json Object
JSON mode: forces the output to be valid JSON. Prefer json_schema where supported. The model only emits JSON if a system or user message instructs it to.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('json_object') | Yes | Response-format type; always json_object. |
Response Format Json Schema
JSON Schema response format. Used to generate structured JSON responses.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('json_schema') | Yes | Response-format type; always json_schema. |
json_schema | object | Yes | Structured Outputs settings, including the JSON Schema to enforce. |
json_schema.description | string | No | Describes what the format is for; the model uses it to decide how to respond. |
json_schema.name | string | Yes | Name of the response format. Allowed characters: a-z, A-Z, 0-9, underscores, and dashes, up to 64 characters. |
json_schema.schema | ResponseFormatJsonSchemaSchema | No | |
json_schema.strict | boolean | null | No |
Response Format Json Schema Schema
The response-format schema, expressed as a JSON Schema object. See the JSON Schema reference(opens in new tab) for the format.
Type: object
Response Format Text
Plain-text response format (the default).
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('text') | Yes | Response-format type; always text. |
Response Modalities
Type: array of enum ('text', 'audio') | null
Service Tier
Type: enum ('auto', 'default', 'flex', 'scale', 'priority') | null
Stop Configuration
Not supported with reasoning models. Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
Type: string | array of string