Message

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

# 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

role · string · required

The role of the message sender. One of:

• "user" - Message from the user
• "assistant" - Message from the AI
• "tool" - Tool execution results

content · string | list · required

The message content. Can be:

• A simple string for text-only messages
• A list of content parts for multimodal messages

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

Content Part Types

Text Part

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

Image Part

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

# 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

{"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:

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 - Multi-turn conversation patterns
• Multimodal Chatbot - Complete multimodal examples