> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynito.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Message format

> The message object, its roles, and the content-part shapes.

## 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "type": "text", "text": "Describe this image.", "cache_control": { "type": "ephemeral" } }
```

`cache_control` is optional and forwarded to the provider when supported.

### Image part

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "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](/api/features/tool-calling).

## Related

* [Chat Completions API](/api/api-reference/chat-and-text/chat-completions)
* [Fusion](/api/api-reference/chat-and-text/chat-fusion)
* [Tool calling](/api/features/tool-calling)
* [Multimodal](/api/features/multimodal)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.