openrouter-video

OpenRouter Video

通过 OpenRouter 的异步 POST /api/v1/videos 使用 curl + jq 生成视频。需要 OPENROUTER_API_KEY（在 https://openrouter.ai/keys 获取）。如果未设置，请停止并询问用户。

三个步骤

视频生成是异步的：提交 → 轮询 → 下载。单个请求无法直接返回视频，因为生成需要 30 秒到几分钟。请告知用户任务已提交，让他们知道需要等待是正常的。

1. POST /api/v1/videos → { id, polling_url, status: "pending" }
2. 每隔约 30 秒 GET <polling_url>，直到 status 为 completed（终止失败状态：failed、cancelled、expired——原样显示 error 字段）
3. GET /api/v1/videos/{id}/content?index=0 并携带认证标头 → MP4 字节数据

从模型端点选择参数，不要猜测

resolution、aspect_ratio、duration 和 frame_images[].frame_type 因模型而异。在首次提交新模型之前（或用户有具体要求时），获取模型的能力信息，并且只发送返回集合中的值：

curl -sS https://openrouter.ai/api/v1/videos/models \
  | jq '.data[] | select(.id == "MODEL_ID")'

每个模型中值得了解的字段：supported_resolutions、supported_aspect_ratios、supported_sizes、supported_durations（通常是离散值，如 [4,6,8]，而非范围）、supported_frame_images（接受哪些 frame_type 值）、generate_audio 和 seed（能力布尔值）、pricing_skus 以及 allowed_passthrough_parameters。超出集合的值会返回 400，因此请在客户端进行验证。

完整工作流（可直接使用）

#!/usr/bin/env bash
set -euo pipefail

PROMPT="a golden retriever playing fetch on a sunny beach"
MODEL="google/veo-3.1"
OUTPUT="video-$(date +%Y%m%d-%H%M%S).mp4"

# Build payload — extend with resolution/aspect_ratio/duration/etc. as needed.
payload=$(jq -n --arg model "$MODEL" --arg prompt "$PROMPT" \
  '{model: $model, prompt: $prompt}')

submit=$(curl -sS -X POST https://openrouter.ai/api/v1/videos \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$payload")

poll_url=$(echo "$submit" | jq -r '.polling_url')
echo "Submitted $(echo "$submit" | jq -r '.id')" >&2

while :; do
  sleep 30
  resp=$(curl -sS "$poll_url" -H "Authorization: Bearer $OPENROUTER_API_KEY")
  # Avoid the name `status` — zsh treats it as read-only.
  st=$(echo "$resp" | jq -r '.status')
  echo "Status: $st" >&2
  case "$st" in
    completed) break ;;
    failed|cancelled|expired)
      echo "Generation $st: $(echo "$resp" | jq -r '.error // "unknown"')" >&2
      exit 1 ;;
  esac
done

curl -sS -L "$(echo "$resp" | jq -r '.unsigned_urls[0]')" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  --output "$OUTPUT"

echo "$resp" | jq --arg out "$(realpath "$OUTPUT")" \
  '{job_id: .id, generation_id, video_saved: $out, usage}'

参数

必填：model、prompt。常见可选字段：

• duration（int）——必须是模型的 supported_durations 中的值。
• resolution（string）/ aspect_ratio（string）/ size（string，"WxH"）——size 可替代 resolution + aspect_ratio。
• generate_audio（bool）——仅当模型的 generate_audio 能力为 true 时才有意义。
• seed（int）——仅当模型的 seed 能力为 true 时才会生效。
• callback_url（HTTPS）——使用 webhook 代替轮询。
• frame_images[]——图像转视频；每个条目的格式为 { type: "image_url", image_url: { url }, frame_type: "first_frame" | "last_frame" }。
• input_references[]——参考图转视频（用于风格指导）；条目格式相同，但不含 frame_type。如果两个数组都存在，则以 frame_images 为准。
• provider.options.<slug>.parameters.<key>——提供商透传参数，见下文。

图像 url 可以是公开的 https:// URL，也可以是本地文件的数据 URL：MIME=image/png; B64=$(base64 < file.png | tr -d '\n'); url="data:${MIME};base64,${B64}"。

提供商透传参数

提供商专属参数放在 provider.options.<slug>.parameters 下。特定模型允许使用的键以扁平列表形式列在模型端点的 allowed_passthrough_parameters 中，但参数的含义、取值范围和必需的组合由上游提供商的 API 文档决定（Google Vertex、Alibaba Dashscope、Kwai、ByteDance Volc Engine、MiniMax、OpenAI 等）。使用不熟悉的键之前，请先阅读上游文档；不同提供商的大小写约定各不相同（Google/OpenAI 使用 camelCase，大多数其他提供商使用 snake_case）。

示例：

{
  "model": "google/veo-3.1",
  "prompt": "a time-lapse of a flower blooming",
  "provider": {
    "options": {
      "google-vertex": {
        "parameters": {
          "personGeneration": "allow",
          "negativePrompt": "blurry, low quality"
        }
      }
    }
  }
}

Webhook（可选）

在提交请求体中传入 callback_url（HTTPS）。进入终止状态时，OpenRouter 会 POST 一个 video.generation.{completed,failed,cancelled,expired} 事件。每次投递都会携带 X-OpenRouter-Idempotency-Key: <job_id>-<status>。如果工作区配置了签名密钥，请验证 X-OpenRouter-Signature: t=<ts>,v1=<hmac>——使用该密钥对 <ts>,<raw_body> 计算 HMAC-SHA256，并拒绝时间戳早于约 5 分钟的请求。

参考资料

• 视频生成指南
• 模型页面（按视频输出筛选）

由于提供商必须暂时保留输出，以便异步下载，因此视频生成不符合 ZDR 条件。