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

# 多模态

> 通过 YouRouter 调用视觉、图片输入和视频生成模型 API。

除了纯文本对话之外，YouRouter 也支持多模态模型调用。当你的集成需要图片、视觉理解、上游提供商原生多模态格式或视频生成任务时，请使用本页。

## 应该使用哪个 API？

| 使用场景               | 推荐 API                                                                                    | 说明                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| 文本对话               | `POST /v1/chat/completions`                                                               | 标准 OpenAI 兼容调用。                                                    |
| 图片理解               | `POST /v1/chat/completions`                                                               | 发送文本加 `image_url` 内容块。                                             |
| PDF / 文档理解         | `POST /v1/chat/completions`、`POST /v1/projects/...:generateContent` 或 `POST /v1/messages` | 取决于目标模型和上游格式。OpenAI 兼容格式可用 `file` 内容块；Gemini 和 Claude 可使用各自原生文档格式。 |
| Gemini 原生多模态       | `POST /v1/projects/...:generateContent`                                                   | 当你需要 Google 原生 `contents` / `parts` 结构时使用。                         |
| Claude 原生 messages | `POST /v1/messages`                                                                       | 当你需要 Anthropic 原生 Messages 格式时使用。                                  |
| 文生视频 / 图生视频        | `POST /api/v3/contents/generations/tasks`                                                 | 基于任务的生成流程，先创建任务，再轮询结果。                                             |

<Note>
  对于大多数聊天和视觉集成，建议先从 `https://api.yourouter.ai/v1` 和 OpenAI 兼容的 Chat Completions 格式开始。
</Note>

## 通过 Chat Completions 发送图片输入

把 `messages[].content` 设为内容块数组，通常包含一个 `text` 块和一个或多个 `image_url` 块。

```bash theme={null}
curl https://api.yourouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Describe this image in one sentence."
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.jpg"
            }
          }
        ]
      }
    ]
  }'
```

生成结果通常位于：

```text theme={null}
choices[0].message.content
```

## Base64 图片输入

如果图片是私有的，可以直接发送 data URL：

```json theme={null}
{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,<BASE64_IMAGE>"
  }
}
```

尽量控制 payload 大小。对于超大图片，优先使用临时 HTTPS URL。

## Python 示例

```python theme={null}
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YOUROUTER_API_KEY"],
    base_url="https://api.yourouter.ai/v1",
)

with open("image.jpg", "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("utf-8")

completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is shown in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{encoded}"
                    },
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)
```

## PDF / 文档输入

PDF 支持取决于目标模型和上游提供商。发送请求前，请确认你选择的模型支持文档或视觉理解能力；不支持 PDF 的模型会返回上游错误。

对于支持 OpenAI 兼容文件内容块的模型，可以在 `messages[].content` 中加入 `file` 块。这里的 `file_data` 是 PDF 原始字节的 base64 编码内容，不需要加 `data:application/pdf;base64,` 前缀。

```bash theme={null}
curl https://api.yourouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "file",
            "file": {
              "filename": "document.pdf",
              "file_data": "<BASE64_PDF>"
            }
          },
          {
            "type": "text",
            "text": "Summarize the key points in this PDF."
          }
        ]
      }
    ]
  }'
```

如果你的场景明确依赖某个上游提供商的文档能力，建议使用 provider-native 格式：

* Gemini：使用 `inlineData.mimeType: "application/pdf"`，见 [Gemini Generate Content](/zh/api-reference/google/generate-content)。
* Claude：使用 `document` 内容块和 `media_type: "application/pdf"`，见 [Anthropic Messages](/zh/api-reference/messages/create)。

<Warning>
  PDF 通常会占用更多上下文窗口和请求体大小。生产环境中请限制文件大小和页数；大文件建议先拆分，或确认目标上游的文件上传能力可用后再采用上传式流程。
</Warning>

## Gemini 原生多模态

当你的集成依赖 Gemini 原生字段时，使用 Google 的 `generateContent` 格式。

```bash theme={null}
curl https://api.yourouter.ai/v1/projects/cognition/locations/us/publishers/google/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "vendor: google" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Describe this image in one sentence." },
          {
            "inlineData": {
              "mimeType": "image/jpeg",
              "data": "<BASE64_IMAGE>"
            }
          }
        ]
      }
    ]
  }'
```

参考 [Google Generate Content](/zh/api-reference/google/generate-content) 查看接口页。

## Claude 原生 Messages

当你需要 Claude 原生请求行为时，使用 Anthropic 的 Messages 格式。

```bash theme={null}
curl https://api.yourouter.ai/v1/messages \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "vendor: anthropic" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 300,
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe this image in one sentence." },
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/jpeg",
              "data": "<BASE64_IMAGE>"
            }
          }
        ]
      }
    ]
  }'
```

参考 [Anthropic Messages](/zh/api-reference/messages/create) 查看接口页。

## 视频生成任务

视频生成采用任务式流程：先创建任务，再轮询直到任务完成。

```bash theme={null}
curl -X POST https://api.yourouter.ai/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {
        "type": "text",
        "text": "A cinematic product shot with soft studio lighting --duration 5 --resolution 1080p"
      }
    ]
  }'
```

创建接口会返回任务 `id`。随后使用该 `id` 查询状态：

```bash theme={null}
curl https://api.yourouter.ai/api/v3/contents/generations/tasks/{id} \
  -H "Authorization: Bearer $YOUROUTER_API_KEY"
```

完整任务流请参考 [Ark 文生视频](/zh/guides/ark-video)。

## 集成建议

* 将模型 ID 做成配置项，便于随时切换视觉或多模态模型。
* 只有在你明确需要上游提供商特有格式或行为时，才使用 `vendor`。
* 大文件优先使用 HTTPS URL 或拆分处理；私有、本地测试图片和小型 PDF 适合用 base64。
* PDF 支持随模型和上游能力变化，发布前请用目标模型跑一次真实文件测试。
* 在排查上游提供商特定的多模态问题时，请保留请求 ID。