動画生成 API

動画生成 API は、非同期の動画ジョブを作成します。作成リクエストはジョブ ID とともに HTTP 202 を返します。その ID を使い、ジョブが succeeded または failed になるまでポーリングし、完成した MP4 をダウンロードしてください。

以下の例では、ベース URL として https://api.icodeeasy.cc を使用します。以下に記載するすべてのエンドポイント呼び出しには API キーが必要です。成功後に返される署名付き結果ファイル URL のみが例外です。

Authorization: Bearer <your API key>

エンドポイント

5 分クイックスタート

1. ジョブを作成する

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <your API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.5",
    "prompt": "雨の未来都市の通り、カメラがゆっくり前進し、濡れた路面にネオンが反射する",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

作成が受理されると HTTP 202 を返します。

{
  "id": "vid_1785398400000000000",
  "task_id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "queued",
  "model": "doubao-seedance-2.5",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:00Z"
}

ジョブ ID には task_id の使用を推奨します。ポーリング、ダウンロード、削除に使用でき、id は互換期間中、同じ値で残ります。202 はジョブが受理されたことを示すもので、動画がすでに完成していることを示すものではありません。

2. ジョブをポーリングする

作成レスポンスの task_id を TASK_ID に設定します。

TASK_ID='vid_1785398400000000000'
curl "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}" \
  -H 'Authorization: Bearer <your API key>'

約 5 秒に 1 回ポーリングしてください。現在のジョブが queued または running の間は、別のジョブを作成しないでください。

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "running",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:20Z",
  "progress": 42
}

progress は参考値であり、省略される場合があります。進捗値ではなく status を正式な状態として扱ってください。

3. 動画をダウンロードする

status が succeeded になると、レスポンスに url と確定した cost_rmb が含まれます。

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "succeeded",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:01:18Z",
  "progress": 100,
  "url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "cost_rmb": 0.528
}

正式な認証付きコンテンツルートから、リダイレクトを許可してダウンロードしてください。

TASK_ID='vid_1785398400000000000'
curl -L "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}/content" \
  -H 'Authorization: Bearer <your API key>' \
  -o result.mp4

コンテンツルートは HTTP Range と一般的な条件付きダウンロードヘッダーに対応しています。成功前にコンテンツを要求すると 409 video_not_ready を返します。

ジョブのライフサイクルと安全な再試行

再試行のルール：

• HTTP 202 を受け取った後は、返された task_id を引き続きポーリングしてください。作成リクエストを繰り返すと別のジョブが作成される可能性があります。
• ポーリングとダウンロードの GET リクエストは安全に再試行できます。
• 作成時に submission_unknown が返った場合は、別のリクエストを送信しないでください。ジョブがすでに受理されている可能性があります。リクエスト時刻、モデル、プロンプトの概要を添えてサポートにお問い合わせください。
• 終端状態 failed が確認された後は、別の動画を生成する場合にのみ新しいジョブを作成してください。

Webhook と callback_url はサポートされていません。代わりにジョブエンドポイントをポーリングしてください。

作成リクエストのリファレンス

テキスト指示はすべて prompt に指定してください。content は参照画像と参照動画だけに使用します。

参照素材リスト（content）

content は、先頭・末尾フレーム、複数の順序なし参照画像、または Motion Control の画像 1 点と動画 1 点など、1 つのジョブで複数素材を扱うためのリストです。各項目の image_url または video_url に HTTPS URL 文字列を直接指定します。

[
  { "type": "image_url", "image_url": "https://cdn.example.com/first.png", "role": "first_frame" },
  { "type": "image_url", "image_url": "https://cdn.example.com/last.png", "role": "last_frame" }
]

• 画像タイプ：image_url または input_image。
• 動画タイプ：video_url または input_video。
• フレーム役割：first_frame と last_frame。末尾フレームを使う場合は、必ず先頭フレームも必要です。
• モーション役割：reference_image 1 点と reference_video 1 点。
• Grok の参照画像には役割を付けません。reference_image も使用できます。
• 参照音声は現在サポートされていません。
• メディアは、ジョブが読み取る間有効な、公開アクセス可能な HTTPS URL で指定してください。
• 画像は image_url、動画は video_url に指定します。

先頭フレーム + 末尾フレームの完全な呼び出し例

2 枚の画像を公開 HTTPS URL に配置し、その URL を content に直接指定します。

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <API キー>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "先頭フレームから末尾フレームへ滑らかにカメラを移動する",
    "content": [
      {"type":"image_url","image_url":"https://cdn.example.com/first.png","role":"first_frame"},
      {"type":"image_url","image_url":"https://cdn.example.com/last.png","role":"last_frame"}
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

先頭フレームだけを指定することはできます。末尾フレームは、同じリクエストに先頭フレームがない場合は指定できません。

モデル別レシピ

Seedance：テキスト、先頭フレーム、末尾フレーム

Seedance 2.5、Seedance 2.0 Standard、Fast、Mini、および Seedance 1.5 Pro は、テキストからの動画生成と先頭・末尾フレームによる生成に対応しています。参照画像には明示的なフレーム役割が必要です。Seedance 2.5 はこのファミリーの先頭に記載しています。

{
  "model": "doubao-seedance-2.5",
  "prompt": "the camera circles a glass sculpture as morning light changes",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-last.png", "role": "last_frame" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 6,
  "generate_audio": true
}

Seedance 2.5 の既定値は 480p、9:16、4 秒、生成音声オンです。先頭フレームまたは先頭・末尾フレームを指定すると、比率は adaptive に正規化されます。

MiniMax H3：テキスト、先頭フレーム、末尾フレーム

MiniMax-H3 は、同じ公開リクエストでテキストからの動画生成と先頭・末尾フレームによる生成に対応します。768P または 2K、4～15 秒、21:9、16:9、4:3、1:1、3:4、9:16 の比率を使用できます。既定値は 768P、9:16、5 秒です。generate_audio は指定しないでください。H3 の公開契約には生成音声のリクエスト切替はありません。

Kling：フレームに基づく生成

{
  "model": "kling-v3",
  "prompt": "a train enters the station through light fog",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-last.png", "role": "last_frame" }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}

Kling の主な違い：

• kling-v2-6：末尾フレームには 1080p が必要です。生成音声は 1080p でのみ利用でき、末尾フレームとは併用できません。
• kling-3.0-turbo：先頭フレームのみ対応し、生成音声は非対応です。
• kling-v3 と kling-v3-omni：先頭・末尾フレームと生成音声に対応しています。
• kling-v3-omni：役割なしの参照画像も最大 2 点まで使用できますが、1 つのリクエストで役割なし画像とフレーム役割付き画像を混在させないでください。
• kling-video-o1：先頭・末尾フレームに対応し、生成音声は非対応です。

Grok：順序なしの参照画像

Grok は参照画像 URL を最大 7 点まで使用できます。first_frame または last_frame の役割を指定しないでください。

{
  "model": "grok-imagine-1.5-video",
  "prompt": "clouds roll over a canyon while the camera rises",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/grok-reference.png" }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 6
}

Grok の既定値は 480p、9:16、6 秒です。生成音声はサポートされていません。

Kling Motion Control

公開 HTTPS 画像 1 点と、公開 HTTPS の 3～30 秒 MP4 動画 1 点を指定します。

{
  "model": "kling-v3-motion-control",
  "prompt": "preserve the character identity and follow the reference motion",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/character.png", "role": "reference_image" },
    { "type": "video_url", "video_url": "https://cdn.example.com/motion.mp4", "role": "reference_video" }
  ],
  "motion_mode": "std",
  "character_orientation": "image",
  "keep_original_sound": true
}

• character_orientation: "image"：参照動画は 3～10 秒である必要があります。
• character_orientation: "video"：参照動画は 3～30 秒である必要があります。
• Motion Control モデルには resolution、ratio、duration、generate_audio を指定しないでください。

モデル機能表

標準モデルでは、省略したオプション値に上記の各モデルの既定値が適用されます。model 自体は常に必須です。サービスはジョブ開始前に指定された組み合わせを検証します。

レスポンスとダウンロードの動作

すべてのジョブレスポンスは次の形式を使用します。

返された URL の形式を前提として保存するのではなく、GET /v1/videos/tasks/{id}/content を優先してください。-L を使用するか、HTTP クライアントでリダイレクトを有効にしてください。認証付きコンテンツエンドポイントは 200、206 Partial Content、またはリレー管理ストレージへのリダイレクトを返す場合があります。

署名付きリレーファイル URL は API キーなしで開くことができ、完全な URL を知っている人はその動画へアクセスできます。公開ログ、公開ページ、クライアント側の分析に露出させないでください。

安全な終端状態のジョブを削除すると HTTP 204 が返り、リレー管理の動画ファイルも削除される場合があります。必要な結果は、ジョブを削除する前にダウンロードして保存してください。ジョブが実行中または精算未完了の場合、削除は 409 video_delete_unsafe で拒否されます。ローカルジョブ記録を削除しても、開始済みの動画生成はキャンセルされません。

エラー処理

HTTP エラーは次の形式を使用します。

{
  "error": {
    "type": "invalid_request",
    "message": "model is not supported"
  }
}

失敗したジョブのレスポンス例：

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "failed",
  "model": "doubao-seedance-2.0",
  "error": { "code": "generation_failed" }
}

課金

動画生成では、月間クォータではなくアカウント残高を使用します。

タスク料金 = 選択したモデル／仕様の表示 RMB 単秒価格 × 課金秒数

料金ページ で現在の単秒価格を確認してください。解像度、生成音声、または Motion Control モードによって、適用される表示単秒価格が異なる場合があります。標準モデルの課金秒数は指定した duration です。Motion Control の課金秒数は、検出された参照動画の長さを整数秒に切り上げた値です。

ジョブ作成時に、その料金を支払える残高が必要です。残高不足の場合は、生成開始前に 402 を返します。成功したジョブの cost_rmb が正式な最終料金です。明確に失敗したジョブには料金がかかりません。