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 | Assistant message content. Required unless the message includes tool_calls. |
refusal | string | null | No | Refusal message issued by the assistant. |
reasoning_content | string | null | No | Reasoning (chain-of-thought) content the model produced on this assistant turn, replayed back so the model retains its prior reasoning across turns of a multi-turn conversation. |
reasoning | string | null | No | Alias of reasoning_content (Llama API convention). When both are present, reasoning_content takes precedence. |
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 | Frames per second at which to sample the video. |
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 | Text content of the message. |
refusal | string | null | Yes | Refusal message generated by the model. |
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 | The reasoning content generated by the model when using a reasoning model. This field does not carry the model's reasoning across turns; for multi-turn reasoning continuity, use the Responses API. |
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 | Text carried in this streamed delta. |
reasoning_content | string | null | No | The reasoning content chunk generated by the model when using a reasoning model. This field does not carry the model's reasoning across turns; for multi-turn reasoning continuity, use the Responses API. |
tool_calls | array of ChatCompletionMessageToolCallChunk | No | |
role | enum ('developer', 'system', 'user', 'assistant', 'tool') | No | Role of the message author. |
refusal | string | null | No | Refusal text carried in this streamed delta. |
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 | UTF-8 byte values for this token, used to reconstruct text when a character spans multiple tokens. null when no byte representation exists. |
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 | UTF-8 byte values for this token, used to reconstruct text when a character spans multiple tokens. null when no byte representation exists. |
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 | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1) |
top_p | number | null | No | Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1) |
user | string | No | Deprecated. 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 | The retention policy for the prompt cache. |
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. |
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 a 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 | Deprecated. 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 | Deprecated. 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 | Log-probability data for this choice. |
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 | Deprecated. 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 | Deprecated. 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 | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1) |
top_p | number | null | No | Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1) |
user | string | No | Deprecated. 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 | The retention policy for the prompt cache. |
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 | When true, the model must produce arguments that match the parameters schema exactly. Only a subset of JSON Schema is supported in this mode. Defaults to false. (default: false) |
Function Parameters
The parameters the functions accepts, described as a JSON Schema object. See the JSON Schema reference (opens in a 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 | An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. (minimum: 0, maximum: 20) |
temperature | number | null | No | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1) |
top_p | number | null | No | Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1) |
user | string | No | Deprecated. 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 | The retention policy for the prompt cache. |
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 | When true, the model's output strictly conforms to the JSON Schema defined in the schema field. Only a subset of JSON Schema is supported in strict mode. (default: false) |
Response Format Json Schema Schema
The response-format schema, expressed as a JSON Schema object. See the JSON Schema reference (opens in a 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
Mirrored from dev.meta.ai/docs/api-reference/chat-completions/schemas (synced Oct 30, 2026). Text and examples © Meta. Live demos run on Muse Muse's key.