はじめに

動画生成

POST /v1/creative/video-router/generate にモデルと入力を送り、動画生成ジョブを作成します。長い処理はポーリングまたは Webhook で追跡し、自分のプログラムの待機時間を超えても同じジョブを確認し続けます。

対応入力を確認する

GET /v1/creative/video-router/models または /{model_id} の capabilities、constraints、pricing で、モデルが受け付ける長さ、解像度、参照入力を確認します。例の seedance-2.5 と kling-3 は公開カタログのモデル ID です。利用可能なモデルはワークスペースのカタログで確認してください。

入力用途と制約
model必須。カタログのモデル ID。
promptシーンや動き、編集内容。通常の文章生成では指定し、モデルが不要とする処理では省略します。
duration_seconds出力の秒数。共通スキーマは2〜600秒でも、モデル別の範囲が適用されます。
resolution・aspect_ratioモデルが受け付ける解像度と縦横比。
image_url・end_image_url最初と最後のフレーム。最後のフレームには最初の画像も必要です。
video_url編集や延長の元となる動画の公開 HTTPS URL。
audio_url対応するリップシンクモデルで使用する音声。
reference_images参照画像。URL または種類付きオブジェクトで指定し、共通上限は9件。
reference_videos・reference_audio参照動画と音声。URL または種類付きオブジェクトで指定し、それぞれ共通上限は3件。
generate_audio音声生成に対応するモデルで有効にします。
seed0〜4,294,967,295 の乱数シード。
model_params予約領域。現在は省略または {} のみ。

参照入力の件数はモデル固有の制約を優先します。すべての URL は、生成が終わるまで認証なしで取得できる必要があります。ローカルの入力は先にアップロードします。

文章から動画を作る

export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.orchestor.io/v1/creative/video-router/generate \
  -H "Authorization: Bearer $ORCHESTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "夕方の草原を流れる雲を固定カメラで撮影、風で草が揺れる",
    "duration_seconds": 5,
    "resolution": "480p",
    "aspect_ratio": "16:9",
    "mode": "async"
  }'

画像から動画を作る

最初のフレームを image_url に指定します。Python の例では requests を使用します(pnpm の依存関係とは別に、実行環境へ導入してください)。INPUT_IMAGE_URL はアップロード後の public_url です。

import os
import requests

response = requests.post(
    "https://api.orchestor.io/v1/creative/video-router/generate",
    headers={
        "Authorization": f"Bearer {os.environ['ORCHESTOR_API_KEY']}",
        "Idempotency-Key": os.environ["IDEMPOTENCY_KEY"],
    },
    json={
        "model": "kling-3",
        "prompt": "風に揺れる木の葉、ゆっくり近づくカメラ",
        "image_url": os.environ["INPUT_IMAGE_URL"],
        "duration_seconds": 5,
        "mode": "async",
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()["data"]
print(data["job"]["id"], data["status_url"])

モデル固有の設定

対応しないモデルへ送ると入力エラーになるため、必要な項目だけ指定します。

フィールド対応する処理
taskauto- の自動モデル選択へ渡す制作意図。
frame_images・input_referencesauto- の開始・終了フレーム(最大2件)と参照入力(最大20件)。
draft・draft_job_idseedance-2.5 の480p下書きと、その下書きの1080p仕上げ。仕上げ時は model、draft_job_id と任意の resolution: "1080p" だけを送ります。下書きは作成後14日以内に使用します。
extend・source_durationseedance-2.5 で video_url の続きを生成。追加部分の duration_seconds は4〜30秒、元動画の秒数を切り上げて source_duration(1〜30)に指定します。
prompt_enhancementheygen-video-1 の文章補正。15秒超では turbo、quality、default を使います。
end_user_id・callback_idheygen-video-1 の利用者識別と追跡。個人情報を含めず、各128文字・256文字以内で指定します。
dubbing・captions対応モデルの吹替言語と字幕スタイル。
upscaletopaz-video の拡大倍率(1〜4)と補間後の fps(16〜60)。
background・depth対応モデルの背景除去と深度マップ描画の設定。
bitrate_mode対応モデルの standard または high。

たとえば開始フレームを構造付きで送る場合は、frame_images に { "type": "image_url", "image_url": { "url": "https://example.com/first.png" }, "frame_type": "first_frame" } を指定します。参照入力も type と同じ名前のオブジェクトに url を入れます。

長いジョブを追跡する

受付時の 200 OK から job.id と status_url を保存します。next_poll_after_seconds に従って待ち、result_ready が true になったら result_url を取得します。動画は result.artifacts の URL からダウンロードします。

長い待機には mode: "webhook" と webhook_url を使用できます。通知に加えて低頻度の状態確認を残すと、受信先の停止中にも完了を確認できます。

sync の待機は最大30秒です。時間内に完了しなかった場合も、受付済みジョブは継続します。新しい生成を送り直すと別ジョブになるため、元の ID を追跡してください。