Chat completions deep-dive
Every field in the chat completion request and response, explained.
Roles
systemSets assistant behavior. Optional but recommended. Placed first.
userEnd-user messages. Can contain text or multimodal content parts.
assistantModel responses. May include tool_calls. Used for multi-turn history.
toolResponse from an external function. Must reference a tool_call_id.
Content shapes
Plain text. Most common shape for user and assistant messages.
Content parts array. Each part has a type: text, image_url, or input_audio. Used for vision and audio inputs.
tool_calls
When the model decides to invoke a function, the assistant message carries a tool_calls array. Each entry has:
id— unique call identifiertype— always "function"function.name— function to callfunction.arguments— JSON string of parameters
tool_choice
autoModel decides whether to call a tool (default).noneModel never calls a tool.requiredModel must call one or more tools.{"type":"function","function":{"name":"x"}}Force a specific function call.finish_reason
stop — natural end or stop sequence hit. length — max_tokens reached. tool_calls — model wants to call a function. content_filter — omitted due to safety flags.