向模型发送图像#

提示词中包含图像时，请传入UserMessage。请使用由 TextContent 和 ImageContent 组成的有序列表，而不要使用特定厂商的字典。纯字符串仍然是纯文本请求的简写形式。

使用本指南之前，请先选择一个支持视觉的模型。运行时可以表示图像，但不会给纯文本端点增加视觉支持。

使用图像字节#

from pathlib import Path

from zett_agent.messages import (
    ImageBytesSource,
    ImageContent,
    ImageDetail,
    TextContent,
    UserMessage,
)

message = UserMessage(
    content=[
        TextContent("Describe the layout of this screenshot."),
        ImageContent(
            source=ImageBytesSource(
                data=Path("screenshot.png").read_bytes(),
                media_type="image/png",
            ),
            detail=ImageDetail.HIGH,
        ),
    ],
)
reply = await client.run(message)
print(reply.content)

请在异步函数中运行这段代码，并使用来自连接模型提供商的客户端和一个已有的图像文件。data是编码后的图像文件字节，而不是解码后的像素或 base64 字符串。MIME 类型必须描述该文件，例如image/png或image/jpeg。运行时会检查字节非空，并且 MIME 类型以image/开头；它不会解码或校验图像。

在异步服务中处理大文件上传时，请在请求循环之外读取文件，或者使用工作线程。在构造消息之前，请在应用中校验上传大小和允许的格式。

使用 URL#

from zett_agent.messages import ImageUrlSource

message = UserMessage(
    content=[
        TextContent("What is shown in this image?"),
        ImageContent(source=ImageUrlSource("https://example.com/image.png")),
    ],
)

请把 URL 替换成你的模型提供商可以访问的图像。运行时不会替你下载它，也不会附加你应用的身份验证请求头。ImageUrlSource接受 HTTP、HTTPS 和图像 data URL；不接受本地文件路径。本地文件或私有图像请使用字节。

模型提供商差异#

各适配器支持的图像表示形式#

适配器

注意事项

OpenAI / DeepSeek

接受带类型的字节或 URL，并按所选协议渲染。视觉能力取决于端点和模型。

Anthropic

字节会变成 base64 图像块；HTTP(S) URL 和图像 data URL 会分开表示。

Google

字节会变成内联图像部分；URL 会变成 URI 部分。所选服务必须支持该 URI。

Ollama

请使用字节或 base64 图像 data URL。远程的 HTTP(S) 图像 URL 会被适配器拒绝。

ImageDetail.AUTO是默认值。LOW和HIGH是保真度提示，而不是通用的分辨率保证；只有暴露该设置的协议才能使用它们。alt_text在图像对象上保存一个可选描述，但不要把它当作模型可见的文本来依赖：如果模型需要指令或无障碍描述，请添加一个TextContent部分。

检查并存储多模态消息#

message.parts会按顺序保留各个内容部分。message.text只拼接文本部分，这对显示标签很有用，但并不是完整的记录。内置的 SQLite 存储会保留带类型的图像内容。因此，当历史记录被恢复时，图像可能会出现在后续请求中；请相应地规划存储大小、保留策略和模型提供商成本。

本地工具也可以返回ImageContent或一个由带类型的文本/图像部分组成的列表。关于结果类型，请参见定义并注册工具。MCP 内容遵循它自己的结果映射；不要假定每个 MCP 图像块都会变成视觉输入。

离线验证该消息#

async def main() -> None:
    client = await create_agent(ImageModel())
    message = UserMessage(
        content=[
            TextContent("Describe this image."),
            ImageContent(source=ImageBytesSource(data=PIXEL, media_type="image/png")),
        ]
    )
    reply = await client.run(message)
    assert reply.content == "Received text and image in order."
    print(reply.content)

在源码检出目录中运行uv run python docs/_examples/images.py。预期输出：

Received text and image in order.

完整示例嵌入了一张很小的图像，并用一个确定性的模型验证带类型的请求。它测试的是消息处理，而不是 LLM 解读图像的能力。

下一步：把流式输出接入终端或界面用于显示响应，或者用保存并恢复对话决定要保留什么。