openrouter-video

OpenRouter Video

OpenRouter の非同期 POST /api/v1/videos を curl と jq で使用して動画を生成します。OPENROUTER_API_KEY が必要です（https://openrouter.ai/keys で取得できます）。設定されていない場合は、処理を停止してユーザーに確認してください。

3 つのステップ

動画生成は非同期です。送信 → ポーリング → ダウンロードの順に行います。生成には 30 秒から数分かかるため、1 回のリクエストで動画を返すことはできません。ジョブが送信されたことをユーザーに伝え、待ち時間が発生するのは想定どおりであると知らせてください。

1. POST /api/v1/videos → { id, polling_url, status: "pending" }
2. status が completed になるまで、約 30 秒ごとに GET <polling_url> を実行します（終了状態での失敗：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 は video.generation.{completed,failed,cancelled,expired} イベントを POST します。各配信には X-OpenRouter-Idempotency-Key: <job_id>-<status> が含まれます。ワークスペースに署名シークレットが設定されている場合は、X-OpenRouter-Signature: t=<ts>,v1=<hmac> を検証してください。これはシークレットを使用した <ts>,<raw_body> の HMAC-SHA256 です。約 5 分より古いタイムスタンプは拒否してください。

参考資料

• 動画生成ガイド
• モデル一覧（動画出力で絞り込み）

非同期ダウンロードの手順でプロバイダーが出力を一時的に保持する必要があるため、動画生成は ZDR の対象外です。