動画生成

POST /v1/videos

非同期の動画生成インターフェースです。レンダリングには時間がかかる(通常は数十秒〜数分)ため、送信 + ポーリング方式を採用します:送信すると即座にタスク ID を返し、その後ポーリングで結果を取得します。

テキストから動画、画像から動画(単一画像を先頭フレーム / 先頭・末尾フレーム / 複数画像参照)、さらに参照動画・参照音声などの高度な使い方に対応します。

1. 送信: `POST /v1/videos`

1.1 リクエストパラメータ

パラメータ	型	必須	説明
`model`	string	はい	動画モデル ID。1.2 モデルを参照。
`prompt`	string	はい	プロンプト。参照素材があるときは `@Image1` / `@Video1` / `@Audio1` で明示的に指定する必要があります。1.4 @ 参照構文を参照。
`seconds`	string	はい	長さ(秒)。文字列型、範囲 `"5"`〜`"15"`。
`aspect_ratio`	string	いいえ	アスペクト比。デフォルト `16:9`。値は 1.3 取りうる値を参照。
`resolution`	string	いいえ	解像度。選択したモデルで決まります(1.2 モデル参照)。通常は送る必要はありません。
`size`	string	いいえ	標準パラメータ。ピクセル文字列で、`1280x720` / `1920x1080` / `720x1280` / `1080x1920` のいずれか。向き(横縦)と解像度を1つのフィールドでまとめて指定できます(ゲートウェイが対象モデルの上流が求める形式に自動変換します)。`aspect_ratio` + `resolution` はより細かく指定できる任意の代替表現です。両方を送った場合は明示された `aspect_ratio` / `resolution` が優先されます。
`image_url`	string	いいえ	単一の参照画像。`https://` URL または base64 `data:` URL。画像から動画では先頭フレームとして使われます。`asset://` のアセット参照も指定できます(その場合はキャラクター参照扱いで先頭フレームにはなりません。1.5 バーチャルヒューマン・アセットライブラリ参照)。画像が 1 枚のときはこのフィールド。画像入力は課金トークンを増やしません。
`reference_image_urls`	string[]	いいえ	複数の参照画像(最大 9 枚)。スタイルやキャラクターの一貫性などの複数画像参照に使います。各項目は URL、data URL、または `asset://` のアセット参照(1.5 バーチャルヒューマン・アセットライブラリ参照)。`@ImageN` は配列の N 番目に対応。
`reference_video`	string	いいえ	参照動画(`reference_videos` と同時に送る。値は配列の先頭)。
`reference_videos`	string[]	いいえ	参照動画の配列(最大 3 本、合計長 ≤ 15s)。注意:参照動画の内容は課金トークンに加算されます(例:5 秒の参照動画で約 108,900 トークン増)。ただし動画入力を含むリクエストはより安い「動画入力あり」の単価で課金されます。両方の単価はコンソールのモデルカタログを参照してください。
`audio_url`	string	いいえ	参照音声(声・ナレーションのスタイル指定など。`reference_audios` と同時に送る。値は配列の先頭)。音声を使うときは参照画像が 1 枚以上必須。
`reference_audios`	string[]	いいえ	参照音声の配列(最大 3 本、合計長 ≤ 15s)。mp3 / wav / m4a / aac / ogg / flac など。
`video_config`	object	いいえ	高度な設定。現在は `reference_mode` をサポート。1.3 取りうる値を参照。
`generate_audio`	boolean	いいえ	モデル生成の BGM・効果音を付けるかどうか。デフォルト `true`。`false` にすると無音の動画になります。
`seed`	integer	いいえ	乱数シード。同じ `seed` と同じパラメータであれば、同じ生成結果を再現できます。

動画生成には有効なサブスクリプションが必要です(トークン単位課金、3. 課金について参照)。ない場合は 402 を返します。

1.2 モデル

国内ラインと**海外ライン(-hw サフィックス)**の 2 つのプロダクトラインがあり、能力と価格は独立しています。海外ラインはバーチャルヒューマン・アセットライブラリ(asset://)に対応し、国内ラインは非対応です。 各モデルの単価はコンソールのモデルカタログを参照してください。

モデル	出力	ライン	アセットライブラリ	説明
`doubao-seedance-2-0`	720p	国内	✗	標準画質。オムニ参照(画像 + 動画 + 音声)と極端なアスペクト比に対応。
`doubao-seedance-2-0-1080p`	1080p	国内	✗	高画質。能力は同じで解像度のみ向上(レンダリングは遅め、消費トークン数は多め)。
`doubao-seedance-2-0-hw`	720p	海外	✓	標準画質。国内 720p と同能力に加え、バーチャルヒューマン・アセットライブラリに対応。
`doubao-seedance-2-0-1080p-hw`	1080p	海外	✓	高画質の海外ライン。
`doubao-seedance-2-0-fast-hw`	720p	海外	✓	高速版。生成がより速く、トークン単価はより低め。

1.3 取りうる値

パラメータ	取りうる値 / 制限
`seconds`	整数の文字列、`"5"`〜`"15"`(両端含む)。
`aspect_ratio`	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9`(デフォルト `16:9`)。
`resolution`	モデルで決まります:720p 階層(`doubao-seedance-2-0` / `-hw` / `-fast-hw`)→ `720p`、1080p 階層(`doubao-seedance-2-0-1080p` / `-1080p-hw`)→ `1080p`。
`size`	標準値:`1280x720` / `720x1280`(720p モデル)、`1920x1080` / `1080x1920`(1080p モデル)。21:9 の `1680x720` など標準外のアスペクト比は引き続き `aspect_ratio` + `resolution` で指定してください。
`video_config.reference_mode`	`auto`(デフォルト、複数画像参照)/ `start_frame`(先頭フレーム、画像ちょうど 1 枚)/ `start_end`(先頭・末尾フレーム、画像ちょうど 2 枚、参照動画は不可)。
参照画像の枚数	最大 9 枚。
参照動画の本数	最大 3 本、合計長 ≤ 15s。
参照音声の本数	最大 3 本、合計長 ≤ 15s、かつ参照画像が 1 枚以上必須。

縦型:size:"720x1280" を送るだけで OK(推奨)。同等の aspect_ratio:"9:16" + resolution:"720p" でも指定できます。両方送った場合は明示された aspect_ratio / resolution が優先されます。 画像から動画:image_url(単一)または reference_image_urls(複数)を送信し、prompt 内で @Image1 と指定すること。指定しないとモデルは参照画像を条件に使いません。

1.4 @ 参照構文

参照素材があるとき、モデルは prompt 内の @ImageN / @VideoN / @AudioN で各素材の役割を認識します。素材は種類 + 番号で参照し(例:Image 1 / Video 1 / Audio 1)、番号はリクエスト内での出現順です:

@Image1 = reference_image_urls[0](単一画像のときは image_url)、@Image2 = reference_image_urls[1]、以下同様
@Video1 = reference_videos[0]、以下同様
@Audio1 = reference_audios[0]、以下同様

複数素材を組み合わせるときは @ で明示的に指定する必要があります。さもないとモデルはどの画像がどの役割か推測してしまいます。

1.5 バーチャルヒューマン・アセットライブラリ

参照画像フィールドには、https:// URL や base64 data: URL のほかに、asset://<アセット ID> 形式のアセット参照も指定できます——これはあなたの組織のプライベートなバーチャルヒューマン素材で、事前に自分のアセットライブラリにアップロードしておくものです。まずアセットライブラリ APIでアップロードして asset:// ID を取得し、動画リクエストで参照します:

{ "image_url": "asset://asset-20260713-xyz" }

ルール:

アセットは組織のプライベート:自分の asset:// ID を参照できるのは作成した組織だけです。他組織(または存在しない)の ID を参照すると 400 が返ります。アップロード/照会/削除はアセットライブラリ APIを参照。
asset:// 参照は image_url にも reference_image_urls の任意の項目にも指定でき、通常の URL / data URL と混在できます(例:「ライブラリの人物 + 自前の背景画像」)。
asset:// 素材は常にキャラクター(人物)参照として扱われます。image_url フィールドに入れても先頭フレームにはなりません。先頭フレームとして使いたい場合は通常の URL / data URL を使ってください。
prompt 内では 1.4 @ 参照構文のとおり @ImageN で指定します。番号の付き方は通常の参照画像と同じ(リクエスト内での出現順)です。
通常の参照画像と同様、アセット参照は課金トークンを増やさず、「参照画像は最大 9 枚」の上限にはカウントされます。
海外ライン(-hw シリーズ)のみ対応:doubao-seedance-2-0-hw / -1080p-hw / -fast-hw。国内ライン(doubao-seedance-2-0 / -1080p)は asset:// 非対応です。

1.6 レスポンス

送信が成功すると即座に返ります(タスクはキュー登録済み、動画はまだ未生成):

{ "id": "task_xxxxxxxx", "status": "queued", "seconds": 5 }

id フィールドを後続のポーリング用タスク ID として使います。

送信成功 = 動画生成完了ではありません。キュー中のタスクも失敗し得ます(コンテンツ安全性による拒否など)。ポーリングで終了状態を待ってください。

1.7 例

テキストから動画(`size` のみ、標準的な使い方)

size だけ送れば向きと解像度が確定します。aspect_ratio / resolution を別途送る必要はありません:

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "a red fox running in snow, cinematic",
    "seconds": "10",
    "size": "720x1280"
  }'

テキストから動画(横)

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-1080p",
    "prompt": "A cinematic tracking shot through a neon-lit rainy street at night, slow dolly-in, 35mm grain",
    "aspect_ratio": "16:9",
    "size": "1920x1080",
    "seconds": "10"
  }'

テキストから動画(縦)

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "a red fox running in snow, cinematic",
    "seconds": "10",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "size": "720x1280"
  }'

画像から動画(単一画像を先頭フレーム)

参照画像は https:// URL でも base64 data: URL でも可。prompt 内で @Image1 と指定すること。

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 を先頭フレームに、カメラをゆっくり前進、人物が振り返って遠くを見る",
    "seconds": "10",
    "size": "720x1280",
    "image_url": "https://example.com/start-frame.jpg",
    "video_config": { "reference_mode": "start_frame" }
  }'

画像から動画(複数画像:キャラクター + 背景)

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 のキャラクターが白いドレスを着て、@Image2 の背景で踊る、anamorphic lens",
    "aspect_ratio": "21:9",
    "resolution": "720p",
    "size": "1680x720",
    "seconds": "15",
    "reference_image_urls": [
      "https://example.com/character.jpg",
      "https://example.com/setting.jpg"
    ]
  }'

画像から動画(先頭・末尾フレーム:画像ちょうど 2 枚)

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "1 枚目から 2 枚目へ滑らかに遷移、自然なカメラワークと光の変化",
    "seconds": "10",
    "size": "1280x720",
    "reference_image_urls": [
      "https://example.com/start-frame.jpg",
      "https://example.com/end-frame.jpg"
    ],
    "video_config": { "reference_mode": "start_end" }
  }'

バーチャルヒューマン・アセットライブラリ(asset:// 参照)

ライブラリの人物 + 自前の背景画像の組み合わせ。@Image1 がアセット、@Image2 が背景を指します。model は海外の -hw 名である必要があります(国内ラインは asset:// 非対応):

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-hw",
    "prompt": "@Image1 の人物が @Image2 の場所に立ち、カメラに向かって手を振って微笑む、自然光",
    "seconds": "5",
    "size": "1280x720",
    "reference_image_urls": [
      "asset://asset-20260713-xyz",
      "https://example.com/scene.jpg"
    ]
  }'

オムニ参照(画像 + 動画 + 音声)

audio_url / reference_audios を使うときは参照画像を 1 枚以上同時に送る必要があります。さもないとエラーになります。

curl https://api.portal.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 のキャラが @Audio1 のリズムで踊り、カメラワークは @Video1 を参照、強いビートでカット",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "size": "1280x720",
    "seconds": "10",
    "reference_image_urls": [
      "https://example.com/character.jpg",
      "https://example.com/scene.jpg"
    ],
    "reference_video": "https://example.com/camera-motion.mp4",
    "reference_videos": ["https://example.com/camera-motion.mp4"],
    "audio_url": "https://example.com/track.mp3",
    "reference_audios": ["https://example.com/track.mp3"]
  }'

2. ポーリング: `GET /v1/videos/{id}`

curl https://api.portal.aiin1.ai/v1/videos/task_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

status は queued → processing → completed(または failed)と遷移します。レンダリングは遅いため、数秒ごとにポーリングしてください。

処理中:

{ "id": "task_xxxxxxxx", "status": "processing" }

完了:

{
  "id": "task_xxxxxxxx",
  "status": "completed",
  "video_url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
  "usage": { "total_tokens": 108900 }
}

失敗:

{ "id": "task_xxxxxxxx", "status": "failed" }

video_url について:完了時にダウンロードリンクを返しますが、有効期限は限られています。速やかにダウンロード・転送してください。安定して動画ファイルを取得したい場合は、下記の /content エンドポイントの利用を推奨します。

フィールド説明

フィールド	説明
`id`	ポーリング用タスク ID。API キーの所属組織に紐づき、他者はアクセスできません。
`status`	`queued` / `processing` / `completed` / `failed`。
`video_url`	完了時のダウンロードリンク(利便性のための補助フィールド、有効期限は限られています)。
`usage.total_tokens`	完了時に返る、このタスクで実際に課金されるトークン数。請求額の照合に使えます。

動画のダウンロード: `GET /v1/videos/{id}/content`

ポーリングレスポンスの video_url に加えて、標準エンドポイントから動画の生バイト列を直接取得することもできます(OpenAI SDK の .download_content() と互換)。タスクが completed になって初めて利用可能です:

curl https://api.portal.aiin1.ai/v1/videos/task_xxxxxxxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

Content-Type: video/mp4 のバイナリを返します。用途に応じて使い分けてください:video_url は直接配信・プレビューに便利ですが有効期限があります。/content は期限切れの心配がなく、本番環境で安定して動画ファイルを取得する方法として推奨します。

3. 課金について

生成されたトークン数で課金します:費用 = 生成トークン数 × 100 万トークンあたりの単価。各モデルの単価はコンソールのモデルカタログを参照してください。
トークン数は解像度と長さで一意に決まります:720p は動画 1 秒あたり約 21,780 トークン(5 秒で約 108,900)、1080p は 1 秒あたり約 49,005 トークン(5 秒で約 245,025)。doubao-seedance-2-0-fast-hw のトークン数は 720p と同じで、単価がより低くなります。
参照画像は課金トークンを増やしません。参照動画を含むリクエストは、動画の内容がトークン数に加算されます(例:5 秒の参照動画で約 108,900 トークン増)が、リクエスト全体がより安い「動画入力あり」の 100 万トークンあたり単価で課金されます。両方の単価はコンソールのモデルカタログで確認できます。
ポーリングレスポンスの usage.total_tokens が実際に課金されるトークン数そのものです。請求額の照合にご利用ください。
動画完了時に確定します。失敗 / 放棄したタスクは課金されません。

4. よくあるエラー

HTTP	状況	説明
400	`model` がない	リクエストが不完全。
400	`seconds` の型エラー	`seconds` は文字列必須(例: `"10"`、数値は不可)。
400	`seconds` が範囲外	範囲は `"5"`〜`"15"`。
400	フィールドの型エラー	例: `size` を数値で送る、`reference_image_urls` が文字列配列でない。
400	`size` の値が非対応	対応するのは `1280x720` / `1920x1080` / `720x1280` / `1080x1920` のみ。それ以外のアスペクト比は `aspect_ratio` + `resolution` を使用してください。
400	解像度がモデルの階層と不一致	解像度は選択したモデルで決まります(720p 階層 `doubao-seedance-2-0` / `-hw` / `-fast-hw` は 720p のみ、1080p 階層 `-1080p` / `-1080p-hw` は 1080p のみ)。階層をまたぐ `size` / `resolution` は拒否されます。対応するモデルに切り替えてください。
400	参照素材が多すぎる	画像 ≤ 9 / 動画 ≤ 3 / 音声 ≤ 3。
400	音声を使うが参照画像がない	音声参照には参照画像が 1 枚以上必要。
401	API キーが無効	`Authorization` ヘッダーを確認。
402	有効なサブスクリプションがない	動画はトークン単位課金。先にサブスクリプションが必要。
403	このキーで許可されていないモデル	キーの利用可能モデルを確認。
404	タスクが存在しない / 自組織でない	ポーリングした `id` が誤りか、現在のキーの組織に属さない。
413	リクエストボディが大きすぎる	参照画像は `https://` URL を推奨。大きな data URL は URL に切り替える。
503	一時的に利用不可	上流のタイムアウトまたは利用可能チャネルなし。後でリトライ。