OpenRouter 通过 /api/v1/videos 提供异步视频生成能力。由于视频生成耗时较长，工作流为：提交请求 → 获取 job ID → 轮询状态 → 下载视频。支持文生视频、图生视频（指定首末帧）和参考图风格迁移，分辨率最高 4K，可配置 Webhook 回调替代轮询。

查找视频生成模型

通过专用端点：

curl "https://openrouter.ai/api/v1/videos/models"

通过 Models API：

curl "https://openrouter.ai/api/v1/models?output_modalities=video"

完整工作流

1. POST /api/v1/videos          → 提交任务，获取 job ID
2. GET  /api/v1/videos/{jobId}  → 轮询状态直到 completed
3. GET  /api/v1/videos/{jobId}/content  → 下载视频

基本示例

import requests, time

url = "https://openrouter.ai/api/v1/videos"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 第一步：提交任务
payload = {
    "model": "google/veo-3.1",
    "prompt": "A golden retriever playing fetch on a sunny beach"
}
result = requests.post(url, headers=headers, json=payload).json()
job_id = result["id"]
polling_url = result["polling_url"]

# 第二步：轮询等待完成
while True:
    time.sleep(30)  # 每 30 秒轮询一次
    status = requests.get(polling_url, headers=headers).json()
    print(f"Status: {status['status']}")

    if status["status"] == "completed":
        # 第三步：下载视频
        content_url = status["unsigned_urls"][0]
        video_data = requests.get(content_url).content
        with open("output.mp4", "wb") as f:
            f.write(video_data)
        print("Video saved to output.mp4")
        break
    elif status["status"] == "failed":
        print(f"Failed: {status.get('error')}")
        break

请求参数

参数	类型	必填	说明
model	string	是	视频生成模型 ID
prompt	string	是	视频内容描述
duration	integer	否	视频时长（秒）
resolution	string	否	输出分辨率（如 720p、1080p）
aspect_ratio	string	否	宽高比（如 16:9、9:16）
size	string	否	精确像素尺寸（如 1280x720）
frame_images	array	否	指定首帧或末帧图片（图生视频）
input_references	array	否	风格参考图片（参考图生视频）
generate_audio	boolean	否	是否同时生成音频，默认 true（支持的模型）
callback_url	string	否	Webhook 回调 URL（必须 HTTPS）
seed	integer	否	确定性生成种子（不保证所有提供商支持）

支持的分辨率

480p / 720p / 1080p / 1K / 2K / 4K

支持的宽高比

16:9（横屏）/ 9:16（竖屏）/ 1:1（方形）/ 4:3 / 3:4 / 21:9（超宽）/ 9:21（超高）

图生视频

使用首帧图片（image-to-video）

{
  "model": "alibaba/wan-2.7",
  "prompt": "A character walking through a forest",
  "frame_images": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.png" },
      "frame_type": "first_frame"
    }
  ],
  "resolution": "1080p"
}

使用参考图风格迁移（reference-to-video）

{
  "model": "alibaba/wan-2.7",
  "prompt": "A colossal solar flare beside a planet",
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/style-ref.png" }
    }
  ],
  "resolution": "1080p"
}

同时提供 frame_images 和 input_references 时，frame_images 优先，请求按图生视频处理。

任务状态

状态	说明
pending	已提交，等待处理
in_progress	生成中
completed	生成完成，可下载
failed	生成失败（检查 error 字段）

Webhook 回调

可以用 Webhook 替代轮询，任务完成时 OpenRouter 主动推送通知：

1. 每次请求：在请求体中传 callback_url
2. 工作区默认：在工作区设置中配置默认回调 URL

回调请求包含 X-OpenRouter-Idempotency-Key（格式：<job_id>-<status>）用于去重。支持签名验证（在工作区设置中配置 signing secret），验签方式：提取 X-OpenRouter-Signature 中的 t= 和 v1=，用原始 body 计算 HMAC-SHA256 后比对。

注意事项

• 不支持 Zero Data Retention (ZDR)：视频生成是异步的，生成结果必须短暂保留供下载，无法绕过。如果账号开启了 ZDR 强制模式，视频生成请求将不会被路由。
• 轮询间隔：建议 30 秒轮询一次，避免频繁请求。视频生成通常需要 30 秒到几分钟不等。

常见问题

Q: 任务一直停在 pending？

A: 视频生成本来就需要较长时间，继续按间隔轮询即可，不要频繁请求。

Q: 如何查看某模型支持哪些分辨率？

A: 调用 GET /api/v1/videos/models，响应中 supported_resolutions 字段列出了每个模型的可用分辨率。

Q: 生成失败怎么排查？

A: 查看 poll 响应的 error 字段，检查 prompt 是否符合内容策略，确认参考图片格式和可访问性。