Message format

The message object

Field	Type	Notes
`role`	string	Required. One of `system`, `developer`, `user`, `assistant`, `tool`.
`content`	string or array	The message body. A string, or an array of content parts (see below).
`tool_call_id`	string	Required on `tool` messages. Pairs the result with the originating tool call.
`tool_calls`	array	Optional. Carried on `assistant` messages that request tool calls.

Roles

Role	Use
`system`	Instructions that set behavior for the whole conversation.
`user`	Input from the end user.
`assistant`	A prior model turn. May carry `tool_calls`.
`tool`	The result of a tool call. Requires `tool_call_id`.
`developer`	Accepted. Use it where your target model expects it.

Content

A plain string:

{ "role": "user", "content": "Explain a gateway in one sentence." }

Or an array of parts. The part kinds are text, image_url, and file (or input_file).

Text part

{ "type": "text", "text": "Describe this image.", "cache_control": { "type": "ephemeral" } }

cache_control is optional and forwarded to the provider when supported.

Image part

{ "type": "image_url", "image_url": { "url": "https://example.org/photo.png", "detail": "auto" } }

Field	Notes
`image_url.url`	An `https` URL or a data URL.
`image_url.detail`	Optional detail hint.
`image_url.media_type`	Optional. Combined with raw base64 to assemble a data URL.

The model must support image inputs. URL attachments must be https, carry no credentials, and must not point at private or loopback hosts.

File part

{ "type": "file", "file": { "file_url": "https://example.org/report.pdf", "filename": "report.pdf" } }

Files are parsed request-locally to text before the model sees them (text, PDF, DOCX, PPTX, XLSX, XLS). Supply file_url or file_data with filename, nested under file, or at the top level of an input_file part. file_id is rejected; there is no Files API.

Rejected part kinds

Part	Result
`audio` / `audio_url` / `input_audio`	Rejected.
`video*`	Rejected.

Tool Pairing

An assistant message that requests tools carries tool_calls. Each result goes back as a tool message whose tool_call_id matches. See Tool calling.

Basics

Features

Server-Side Tools

Multimodal

Best Practices

SDKs

API Reference

Message format

The message object

Roles

Content

Text part

Image part

File part

Rejected part kinds

Tool Pairing

​The message object

​Roles

​Content

​Text part

​Image part

​File part

​Rejected part kinds

​Tool Pairing

​Related

The message object

Roles

Content

Text part

Image part

File part

Rejected part kinds

Tool Pairing

Related