Api
Object Definitions
Review the field structures of Message, Choice, Usage, Tool, and Tool Call objects.
This page describes common Chat Completions objects. Unused optional fields may be absent or null.
Message
| Field | Type | Description |
|---|---|---|
role | string | Message author role. |
content | string, array, or null | Content; may be empty during tool calling. |
name | string | Optional participant name; model-dependent. |
tool_calls | array | Assistant-generated tool calls. |
tool_call_id | string | Call ID associated with a tool result. |
Choice
| Field | Type | Description |
|---|---|---|
index | integer | Candidate index in the array. |
message | object | Complete assistant message for non-streaming responses. |
delta | object | Incremental content for streaming responses. |
finish_reason | string or null | Why generation stopped. |
Common finish_reason values
| Value | Meaning | Recommended handling |
|---|---|---|
stop | Completed normally or matched a stop condition. | Display the result. |
length | Reached an output or context limit. | Warn of truncation; shorten input or continue if needed. |
tool_calls | The model proposes tool calls. | Inspect message.tool_calls and enter the tool-execution flow. |
content_filter | Output stopped due to safety policy. | Show a safe message without exposing internal policy details. |
null | Streaming generation is still in progress. | Continue reading chunks. |
Usage
| Field | Type | Description |
|---|---|---|
prompt_tokens | integer | Input tokens used by the request. |
completion_tokens | integer | Model output tokens. |
total_tokens | integer | Combined input and output usage. |
Function Tool
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get the current weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["city"],
"additionalProperties": false
}
}
}Tool Call
{
"id": "call_weather_01",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\"city\":\"Beijing\",\"unit\":\"celsius\"}"
}
}arguments is a JSON string, not a parsed object. Your application must parse and validate it and confirm the function name is allowlisted.