---
title: "Message"
description: "Represents a message in a conversation"
---

Messages represent individual turns in a conversation history. They support both simple text content and multimodal content (text, images, files).

## Structure

```python
# Simple text message
{"role": "user", "content": "Hello!"}

# Multimodal message
{
    "role": "user",
    "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image", "image": image_data, "media_type": "image/png"}
    ]
}
```

## Fields

<ParamField path="role" type="string" required>
  The role of the message sender. One of:
  - `"user"` - Message from the user
  - `"assistant"` - Message from the AI
  - `"tool"` - Tool execution results
</ParamField>

<ParamField path="content" type="string | list" required>
  The message content. Can be:
  - A simple string for text-only messages
  - A list of content parts for multimodal messages
</ParamField>

<Note>
System instructions should use the `system` parameter in `generate_text()`, not a message with `role: "system"`.
</Note>

## Content Part Types

### Text Part

```python
{"type": "text", "text": "Your text here"}
```

### Image Part

Images can be **base64-encoded data**, **raw bytes**, or a **URL**:

```python
# Base64-encoded image
{"type": "image", "image": base64_string, "media_type": "image/png"}

# Image URL
{"type": "image", "image": "https://example.com/image.jpg"}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | `"image"` | Required literal |
| `image` | `str \| bytes` | Base64 string, bytes, or URL |
| `media_type` | `str` | Optional MIME type (e.g., `"image/png"`) |

### File Part

```python
{"type": "file", "data": base64_string, "media_type": "application/pdf"}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | `"file"` | Required literal |
| `data` | `str \| bytes` | Base64 string or bytes |
| `media_type` | `str` | MIME type (e.g., `"application/pdf"`) |

## Using the Message Class

While the dict interface is recommended, you can also use the `Message` class:

```python
from ai_query import Message, TextPart, ImagePart, FilePart

# Dict style (recommended)
message = {"role": "user", "content": "Hello!"}

# Class style
message = Message(role="user", content="Hello!")
```

## Provider Support

| Feature | OpenAI | Anthropic | Google |
|---------|--------|-----------|--------|
| Text | Yes | Yes | Yes |
| Images (base64) | Yes | Yes | Yes |
| Images (URL) | Yes | Yes | Yes |
| Files/PDFs | Limited | Yes | Yes |

## See Also

- [Conversations Guide](/core/conversations) - Multi-turn conversation patterns
- [Multimodal Chatbot](/cookbook/multimodal-chatbot) - Complete multimodal examples
