视频输入

如何向 OpenRouter 模型发送视频文件

OpenRouter 支持通过 API 向兼容模型发送视频文件。本指南介绍如何通过 API 处理视频。

OpenRouter 的视频同时支持直接 URL 和 Base64 编码的 Data URL：

• URL：对于可公开访问的视频更高效，因为不需要在本地编码
• Base64 Data URL：本地文件或无法公开访问的私有视频必须使用

视频输入

你可以通过 /api/v1/chat/completions API，使用 video_url 内容类型向兼容模型发送视频文件。url 可以是 URL，也可以是 Base64 编码的 Data URL。只有具备视频处理能力的模型会处理这类请求。

你可以在模型页面上按视频输入模态筛选，查找支持视频的模型。

使用视频 URL

以下是使用 URL 发送视频的方法。请注意，对于 AI Studio 上的 Google Gemini，仅支持 YouTube 链接：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const result = await openRouter.chat.send({
  model: "google/gemini-2.5-flash",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "请描述这段视频中发生了什么。",
        },
        {
          type: "video_url",
          videoUrl: {
            url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
          },
        },
      ],
    },
  ],
  stream: false,
});

console.log(result);

使用 Base64 编码的视频

对于本地存储的视频，可以将其以 Base64 编码的 Data URL 形式发送：

import { OpenRouter } from '@openrouter/sdk';
import * as fs from 'fs';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

async function encodeVideoToBase64(videoPath: string): Promise<string> {
  const videoBuffer = await fs.promises.readFile(videoPath);
  const base64Video = videoBuffer.toString('base64');
  return `data:video/mp4;base64,${base64Video}`;
}

// 读取视频并进行编码
const videoPath = 'path/to/your/video.mp4';
const base64Video = await encodeVideoToBase64(videoPath);

const result = await openRouter.chat.send({
  model: 'google/gemini-2.5-flash',
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: '这段视频里有什么？',
        },
        {
          type: 'video_url',
          videoUrl: {
            url: base64Video,
          },
        },
      ],
    },
  ],
  stream: false,
});

console.log(result);

支持的视频格式

OpenRouter 支持以下视频格式：

• video/mp4
• video/mpeg
• video/mov
• video/webm

常见用途

视频输入可覆盖广泛的应用场景：

• 视频摘要：生成视频内容的文本摘要
• 物体与活动识别：识别视频中的物体、人物和动作
• 场景理解：描述环境、场景和上下文
• 体育分析：分析比赛、动作和战术
• 安防监控：监控并分析安防录像
• 教育内容：分析教学视频并提供见解

最佳实践

文件大小注意事项

视频文件可能很大，这会影响上传时间和处理费用：

• 压缩视频，在不明显损失质量的前提下减小文件体积
• 裁剪视频，只保留相关片段
• 考虑分辨率：较低分辨率（例如 720p 相对 4K）可以减小文件体积，同时对大多数分析任务仍可用
• 帧率：对于时间分辨率要求不高的视频，较低帧率可以减小文件体积

合适的视频时长

不同模型对视频时长可能有不同限制：

• 查阅特定模型的文档以了解最大视频长度
• 对于长视频，考虑拆成较短片段
• 聚焦关键时刻，而不是发送整段长内容

质量与体积的权衡

在视频质量与实际因素之间取得平衡：

• 高质量（1080p 以上、高比特率）：最适合精细视觉分析、物体检测、文字识别
• 中等质量（720p、中等比特率）：适合大多数通用分析任务
• 较低质量（480p、较低比特率）：可用于基本的场景理解和动作识别

各模型服务提供商的视频 URL 支持情况

视频 URL 支持因模型服务提供商不同而差异很大：

• Google Gemini（AI Studio）：仅支持 YouTube 链接（例如 https://www.youtube.com/watch?v=...）
• Google Gemini（Vertex AI）：不支持视频 URL。请改用 Base64 编码的 Data URL
• 其他模型服务提供商：查阅特定模型的文档以了解视频 URL 支持情况

故障排除

视频未被处理？

• 确认模型支持视频输入（检查 input_modalities 是否包含 "video"）
• 如果使用视频 URL，确认该模型服务提供商支持视频 URL（参见上文「各模型服务提供商的视频 URL 支持情况」）
• 对于 AI Studio 上的 Gemini，确保使用的是 YouTube 链接，而不是直接的视频文件 URL
• 如果视频 URL 不起作用，尝试改用 Base64 编码的 Data URL
• 检查视频格式是否受支持
• 确认视频文件未损坏

大文件错误？

• 压缩视频以减小文件体积
• 降低视频分辨率或帧率
• 将视频裁剪为更短时长
• 查阅特定模型的文件大小限制
• 对于大文件，考虑使用视频 URL（如果该模型服务提供商支持），而不是 Base64 编码

分析结果不佳？

• 确保视频质量足以完成该任务
• 提供清晰、具体的提示词，说明要分析的内容
• 考虑视频时长是否适合该模型
• 检查视频内容是否清晰可见、光照是否充足