多模态

除了纯文本对话之外，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`	基于任务的生成流程，先创建任务，再轮询结果。

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

通过 Chat Completions 发送图片输入

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

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"
            }
          }
        ]
      }
    ]
  }'

生成结果通常位于：

choices[0].message.content

Base64 图片输入

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

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,<BASE64_IMAGE>"
  }
}

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

Python 示例

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, 前缀。

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。
Claude：使用 document 内容块和 media_type: "application/pdf"，见 Anthropic Messages。

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

Gemini 原生多模态

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

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 查看接口页。

Claude 原生 Messages

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

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 查看接口页。

视频生成任务

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

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 查询状态：

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

完整任务流请参考 Ark 文生视频。

集成建议

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

快速开始

模型 API

路由与稳定性

API 参考

功能

法律

应该使用哪个 API？

通过 Chat Completions 发送图片输入

Base64 图片输入

Python 示例

PDF / 文档输入

Gemini 原生多模态

Claude 原生 Messages

视频生成任务

集成建议

​应该使用哪个 API？

​通过 Chat Completions 发送图片输入

​Base64 图片输入

​Python 示例

​PDF / 文档输入

​Gemini 原生多模态

​Claude 原生 Messages

​视频生成任务

​集成建议

应该使用哪个 API？

通过 Chat Completions 发送图片输入

Base64 图片输入

Python 示例

PDF / 文档输入

Gemini 原生多模态

Claude 原生 Messages

视频生成任务

集成建议