コンテンツにスキップ
RouteAPI RouteAPI

Seedance

Seedance は ByteDance の動画生成ファミリーで、Volcengine Ark チャネルから提供されます。RouteAPI はリクエストを Ark の /api/v3/contents/generations/tasks 呼び出しへ変換するため、すべてのタスクは他の動画モデルと同じ「送信 → ポーリング → ダウンロード」の流れになります（タスクの作成、タスクの取得）。このページでは、Seedance アダプターが読むフィールド、モデルごとの制限、Seedance のタスクレコードの読み方、課金の計算方法を説明します。

動画生成は非同期です。送信して task_id を保存し、10〜15 秒ごとにポーリングし、ステータスが SUCCESS になったらダウンロードします。4 秒 480p の動画は通常 1〜5 分かかり、解像度が高いほど、長さが長いほど時間がかかります。

モデル

Section titled “モデル”
モデル IDArk モデル解像度長さ備考
seedance-2.5doubao-seedance-2-5-260628480p / 720p / 1080p4〜30 秒ドラフトプレビュー、参照／編集／延長モード、mov 出力
seedance-2.0doubao-seedance-2-0-260128480p / 720p / 1080p / 4k4〜15 秒画像・動画・音声の参照素材をサポート
seedance-2.0-fastdoubao-seedance-2-0-fast-260128480p / 720p4〜15 秒より高速で安価な 2.0 バリアント
seedance-2.0-minidoubao-seedance-2-0-mini-260615480p / 720p4〜15 秒低コストの 2.0 バリアント

GET /v1/models が返すモデル ID を送信してください。これらのモデルを提供するチャネルは、その ID を 2 列目に対応する Ark モデル名へマッピングするため、アダプターは両方の命名を受け付けます。どのモデルを利用できるか、単価はいくらかは RouteAPI コンソールで決まります。

解像度と長さの列は ByteDance がモデルごとに定めた範囲です。RouteAPI はこれを検証しません。こちら側の唯一の長さチェックは「トップレベルの duration / seconds は 0〜3600 の範囲にあること」という共通ルールです（制限とエラーを参照）。それ以外はすべて Ark が適用します。2.0 モデルへの 30 秒リクエスト、未対応の解像度、参照クリップの過多は、いったん送信されたうえで Ark に拒否され、Ark のステータスとメッセージを伴う fail_to_fetch_task として現れます。RouteAPI は欠けている resolution や duration を補完もしません。既定値は Ark が決めます。その場合のコスト見積もりは 1080p と 5 秒で計算されるため、予約額は見積もりであり、Ark の既定値ではありません。

Seedance 1.x（doubao-seedance-1-0-*、doubao-seedance-1-5-*）は提供を終了しました。1.x の名前にマッピングされるリクエストは、モデルマッピングの後、予約や上流への送信の前に 400 とコード model_not_supported で拒否されます。

共通エンベロープのマッピング

Section titled “共通エンベロープのマッピング”
エンベロープのフィールドSeedance アダプターの処理
promptmetadata.content に text 項目がない場合、または content が 2.5 の draft_task でない場合、末尾の text 項目として追加されます。すべてのリクエストで必須です
images / image画像ごとに role なしの image_url 項目を生成します。metadata.content がある場合は無視されます
ratioArk の ratio として送信されます
resolutionArk の resolution として送信されます
durationArk の duration として送信されます。正の整数にパースできるトップレベルの seconds が上書きします
generate_audiogenerate_audio として送信されます。明示的な false も転送されます
metadata型付き構造へデコードされ、値はトップレベルの同等フィールドより優先されます

size、input_reference、mode は共通エンベロープに含まれますが、Seedance アダプターは読み取りません。代わりに resolution / ratio と、images または content を使用してください。

metadata の型は送信前に検証されます。誤った型（content がオブジェクト、image_url が素の文字列、duration: "abc"）は 400 を返し、課金されません。メッセージは unmarshal metadata failed で始まります。metadata 内の数値・ブール値は文字列形式（"duration": "6"、"watermark": "false"）も受け付けますが、トップレベルのスカラーフィールドは JSON の型で送る必要があります。

トップレベルパラメータ

Section titled “トップレベルパラメータ”

これらはボディのトップレベルから読み取られるため、他のプロバイダへ送るのと同じ形式で、metadata に包まずに送信できます：

フィールド型説明
ratiostringアスペクト比：16:9、4:3、1:1、3:4、9:16、21:9、adaptive
resolutionstring480p、720p、1080p、4k（モデルが対応する場合）
durationinteger秒単位の長さ。0 は「未設定」とみなされ送信されません。明示的に 0 を転送したい場合は metadata を使用してください
generate_audiobooleanサウンドトラックを生成するか。false は明示的に転送されます
secondsstring長さの旧形式。正の整数にパースできる場合、duration と metadata.duration の両方を上書きします。数値でない値は無視されます

metadata パラメータ

Section titled “metadata パラメータ”
フィールド型説明
contentarray入力素材。images を置き換えます。metadata.contentを参照
ratio、resolution、duration、generate_audioトップレベルと同じトップレベルの値より優先されます。正のトップレベル seconds は最終的な duration よりさらに優先されます
seedinteger乱数シード。0 は明示的な値として転送されます
framesintegerフレーム数。指定するとコスト見積もりで duration の代わりに使われ、Ark も duration の代わりに使用します
camera_fixedbooleanカメラを固定します
watermarkboolean出力にプロバイダ側のウォーターマークを付けます。ByteDance は既定値を false としています
return_last_frameboolean最後のフレームも画像として返します
service_tierstringプロバイダのサービスティア（例：default）。そのまま転送されます
execution_expires_afterintegerタスクの有効期限（秒）。ByteDance は 3600〜259200、既定 172800 と記載しており、Ark が適用します
priorityintegerプロバイダ側のキュー優先度。0〜9 で、大きいほど先に実行されます。Ark は自分のアカウント内でのみ並べ替えます
safety_identifierstringエンドユーザー識別子。最大 64 文字。Ark に転送され、長さは Ark が検証します
draftbooleanSeedance 2.5 のドラフトプレビュー。ドラフトプレビューを参照
output_formatstring出力コンテナ。そのまま転送されます。Seedance 2.5 は mp4（デフォルト）または mov を受け付けます
omni_reference_task_typestringSeedance 2.5 の参照モード。そのまま転送されます：auto、reference、edit、extend

callback_url は転送されず、コールバックも送信されません。結果はポーリングしてください。tools も破棄されます。この API 経由では上流のウェブ検索は利用できません。これらを含む不明なキーはエラーにならず、無視されます。metadata.model は読み取られません。ボディの model は常にチャネルの上流モデル名です。

metadata.content

Section titled “metadata.content”

content は入力項目の順序付き配列です。各項目には type、対応するペイロードフィールド、および任意の role があります：

typeペイロードrole の値
texttext—
image_urlimage_url.urlfirst_frame、last_frame、reference_image
video_urlvideo_url.urlreference_video
audio_urlaudio_url.urlreference_audio
draft_taskdraft_task.id—

RouteAPI は項目の形状を検証します（誤ったペイロード型は 400）が、role 名は検証しません。不明な role は転送され、拒否するかどうかは Ark が判断します。URL は公開 http(s) リンク、画像と音声の data: URI、または asset://<asset_id> 参照にできます。素材のアップロードと、検証済みアセットグループからのみ取得できる実在人物の画像の参照については Assets を参照してください。

変換に由来するルール：

  • content が存在する場合、それはそのまま使用されます。トップレベルの images はマージされずに無視されます。空の content 配列は未指定とみなされ、トップレベルの images が有効になります。
  • content に text 項目がない場合、トップレベルの prompt が末尾のテキスト項目として追加されます。唯一の例外は content が draft_task である 2.5 リクエストです。プロンプトは追加されませんが、ボディには prompt が引き続き必要です。
  • プロンプト内で素材は序数で参照します（「image 1」「video 1」）。content の順序に従い、タイプごとに数えます。
  • 最初のフレーム、最初と最後のフレーム、マルチ参照は 3 つの異なるモードです。モデルがその組み合わせを受け付けることを確認しない限り混在させないでください。

以下の参照素材の制限は Ark が適用するもので、RouteAPI の検証ではありません。上限を超えたリクエストは送信され、上流で拒否されます。

項目Seedance 2.52.0 シリーズ
参照画像1〜301〜9
参照動画最大 10 本、合計 30 秒以内最大 3 本、合計 15 秒以内
参照音声最大 10 本、合計 30 秒以内最大 3 本、合計 15 秒以内で、画像か動画を併せて指定する必要あり
単一画像30MB 未満、各辺 300〜6000 px同じ
単一動画mp4 / mov、200MB 未満同じ
単一音声wav / mp3、15MB 未満同じ

Seedance 2.x は実在人物の顔を含む参照画像・参照動画を拒否します。実在人物の肖像を使う場合は、先に本人確認を完了し、検証済みの素材を asset:// で参照してください。本人確認セッション、検証済みグループ、リクエストのルールは Assets にまとめています。

テキストから動画

Section titled “テキストから動画”
Terminal window
curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "A paper boat drifting down a rain-soaked street, cinematic lighting",
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": false
  }'

最初のフレームと最初＋最後のフレーム

Section titled “最初のフレームと最初＋最後のフレーム”

images の単一画像は role なしの画像項目になり、Seedance はそれを最初のフレームとして扱います：

Terminal window
curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "The camera slowly pushes in as the person looks up and smiles",
    "images": ["https://cdn.example.com/first.jpg"],
    "ratio": "adaptive",
    "resolution": "720p",
    "duration": 5
  }'

最初と最後のフレームを明示的に制御するには、content を使用し、その中にプロンプトを記述します：

Terminal window
curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "The bud slowly opens into a full bloom",
    "metadata": {
      "content": [
        { "type": "text", "text": "The bud slowly opens into a full bloom" },
        { "type": "image_url", "image_url": { "url": "https://cdn.example.com/bud.jpg" }, "role": "first_frame" },
        { "type": "image_url", "image_url": { "url": "https://cdn.example.com/flower.jpg" }, "role": "last_frame" }
      ],
      "ratio": "adaptive",
      "resolution": "720p",
      "duration": 5
    }
  }'

マルチモーダル参照

Section titled “マルチモーダル参照”

参照画像・動画・音声は reference_* 系の role を使い、1 つの content 配列に混在させます。タイプごとに、content の順序で番号を振り、プロンプトではその番号で参照します：

Terminal window
curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "The person in image 1 dances following the moves in video 1, with audio 1 as background music",
    "metadata": {
      "content": [
        { "type": "text", "text": "The person in image 1 dances following the moves in video 1, with audio 1 as background music" },
        { "type": "image_url", "image_url": { "url": "https://cdn.example.com/person.jpg" }, "role": "reference_image" },
        { "type": "video_url", "video_url": { "url": "https://cdn.example.com/dance.mp4" }, "role": "reference_video" },
        { "type": "audio_url", "audio_url": { "url": "https://cdn.example.com/bgm.mp3" }, "role": "reference_audio" }
      ],
      "ratio": "16:9",
      "resolution": "720p",
      "duration": 10
    }
  }'

動画入力を含むリクエストはそのモデルの動画入力料率で課金されます。課金を参照してください。参照素材の数、長さ、形式は Ark が適用します。metadata.content の制限表を参照してください。

ベンダー固有モード（Seedance 2.5）

Section titled “ベンダー固有モード（Seedance 2.5）”

Seedance 2.5 はモード選択とコンテナ選択を追加します。どちらもすべての Seedance モデルにそのまま転送され、受け付けるかどうかは Ark が判断します：

Terminal window
curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "Continue the scene as the camera pulls back over the harbour",
    "metadata": {
      "omni_reference_task_type": "extend",
      "output_format": "mov",
      "content": [
        { "type": "text", "text": "Continue the scene as the camera pulls back over the harbour" },
        { "type": "video_url", "video_url": { "url": "https://cdn.example.com/scene.mp4" }, "role": "reference_video" }
      ],
      "ratio": "16:9",
      "duration": 8
    }
  }'

omni_reference_task_type は auto（デフォルト）、reference、edit、extend のいずれかです。各モードが期待する入力の組み合わせは ByteDance の契約で決まっており、RouteAPI は値を転送するだけです。

ドラフトプレビュー

Section titled “ドラフトプレビュー”

ドラフトは低コストのプレビューです。そこから最終動画を生成するのは 2 つ目のタスクで、別途課金されます。

  1. "metadata": { "draft": true, ... } を付けて送信し、SUCCESS を待ちます。
  2. タスクレコードから上流のタスク ID を読み取ります：GET /v1/video/generations/{task_id} → data.data.id。
  3. content を単一の draft_task にした新しいタスクを送信します。

ステップ 1：

Terminal window
curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "An astronaut walks slowly on the moon",
    "metadata": { "draft": true, "duration": 5, "ratio": "16:9" }
  }'

ステップ 2 は、ドラフトタスクが SUCCESS になってから実行します。data.data.id は Ark のタスク ID で、外側の data.task_id とは異なります：

Terminal window
curl -s https://api.routeapi.ai/v1/video/generations/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY" | jq -r .data.data.id

ステップ 3：

Terminal window
curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "x",
    "metadata": {
      "content": [ { "type": "draft_task", "draft_task": { "id": "cgt-xxxxxxxx" } } ],
      "resolution": "1080p",
      "duration": 5
    }
  }'

prompt は引き続き必須ですが、この形式ではテキストとして送信されないため、空でないプレースホルダーなら何でも構いません。duration を明示しないドラフト継続は、モデルの自動長さ上限（2.5 は 30 秒、2.0 は 15 秒）で予約され、実際の使用量で精算されます。

ドラフト ID は Ark に属します。ByteDance は有効期間を 7 日と記載していますが、RouteAPI は検証しないため、期限切れのドラフト ID は上流で失敗します。

タスクの照会

Section titled “タスクの照会”
Terminal window
curl https://api.routeapi.ai/v1/video/generations/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY"
{
  "code": "success",
  "message": "",
  "data": {
    "id": 4512,
    "created_at": 1792048450,
    "updated_at": 1792048569,
    "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
    "platform": "54",
    "user_id": 1024,
    "group": "default",
    "channel_id": 18,
    "quota": 108900,
    "action": "generate",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "result_url": "https://ark-content.example/xxxx.mp4",
    "submit_time": 1792048458,
    "start_time": 1792048461,
    "finish_time": 1792048569,
    "properties": {
      "input": "{\"model\":\"doubao-seedance-2-0-fast-260128\",\"content\":[{\"type\":\"text\",\"text\":\"An orange cat stretching on a windowsill at sunrise\"}],\"generate_audio\":false,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"duration\":5}",
      "origin_model_name": "seedance-2.0-fast",
      "upstream_model_name": "doubao-seedance-2-0-fast-260128"
    },
    "data": {
      "id": "cgt-20261023100444-9kz46",
      "model": "doubao-seedance-2-0-fast-260128",
      "status": "succeeded",
      "content": { "video_url": "https://ark-content.example/xxxx.mp4" },
      "seed": 8202,
      "resolution": "720p",
      "duration": 5,
      "ratio": "16:9",
      "framespersecond": 24,
      "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
      "created_at": 1792048458,
      "updated_at": 1792048569
    }
  }
}

外側のフィールドは RouteAPI のもので、タスクの取得 にすべて記載されています。Seedance では data.status、data.progress、data.result_url、data.fail_reason、data.quota を読んでください。data.quota は現時点の課金額で、成功後は精算後の金額になります。data.properties.input は RouteAPI が Ark へ実際に送った JSON のスナップショットです（512 バイトを超えるメディア URL は [omitted, N bytes] に置き換えられます）。意図した解像度で本当に送信されたかを確認する最短の方法です。data.platform はチャネル種別で、Doubao 動画チャネルは 54、Volcengine チャネルは 45 です。

data.data は Ark 自身のタスクボディで、返されたまま保存され、タスク完了前は不完全なことがあります。チャネルの上流がゲートウェイのエンベロープ（{"code": 200, "data": {...}}）で返す場合、以下のフィールドはさらに 1 階層深い data.data.data に入ります。完了判定はフィールドの有無ではなく data.status で行ってください。読む価値のあるフィールド：

フィールド意味
data.data.idArk のタスク ID。外側の data.task_id とは異なり、2.5 のドラフト本生成で使う
data.data.content.video_urlArk が返した動画 URL。外側の data.result_url と同じ値
data.data.content.last_frame_url最後のフレーム画像。return_last_frame を有効にした場合のみ存在。RouteAPI はこのペイロードをそのまま保存するだけで、content.video_url しか解析しません
data.data.duration / resolution / ratio / framespersecond / seed実際の生成パラメータ
data.data.usage.completion_tokens / total_tokensArk が計量したトークン数。精算には total_tokens を使用
data.data.error失敗時の Ark のエラーコードとメッセージ

Ark のステータスは次のようにタスクレコードへ対応します。RouteAPI が認識しないステータスは実行中として扱います：

Ark の statusタスクレコードのステータス進捗
pending、queuedQUEUED10%
processing、runningIN_PROGRESS50%
succeededSUCCESS100%
failed、expired、cancelledFAILURE100%
それ以外IN_PROGRESS30%

Ark が video_url を持たないまま succeeded を返した場合、RouteAPI はタスクを IN_PROGRESS のまま再ポーリングし、結果のないタスクを精算しません。FAILURE のとき fail_reason は Ark のエラーメッセージで、欠けている場合は task failed になります。error オブジェクトのない expired / cancelled タスクは task expired / task cancelled と報告されます。RouteAPI 自身のタスクタイムアウト（既定 24 時間）が先に発火した場合も FAILURE になり、プラットフォームのメッセージが付きます。いずれの場合も予約額は返金されます。

動画のダウンロード

Section titled “動画のダウンロード”

data.result_url は Ark 自身の URL で、Ark の都合で失効します（ByteDance のドキュメントでは約 24 時間）。早めにダウンロードしてください。RouteAPI の content エンドポイントは呼び出し時に保存済みの URL を取り直すため、失効しそうなリンクを自分で管理せずに済みますが、すでに失効した URL を復活させることはできません：

Terminal window
curl -L -o out.mp4 \
  https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV/content \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

content エンドポイントは呼び出し元自身の完了済みタスクのみを返します。未完了のタスクは現在のステータスを示す 400、未知または他人の task_id は 404、Ark からの取得失敗は 502 です。こちらのエラーは {"error": {"message": "...", "type": "..."}} 形式で、code フィールドはありません。return_last_frame を有効にした場合、data.data.content.last_frame_url も Ark の都合で失効するため、あわせてダウンロードしてください。

課金

Section titled “課金”

Seedance モデルはリクエスト単位でも秒単位でもなく、トークン単位で課金されます。コンソールの単価は解像度ティアごとの出力 100 万トークンあたりの価格で、動画入力を含むリクエストはそのモデルの動画入力料率で課金されます。

送信時に、RouteAPI は要求された解像度とフレーム数から出力トークンを見積もります：

frames  = 24 × duration + 1        (frames replaces duration when metadata.frames is set)
tokens  = pixels × frames / 1024
pixels  = 480p: 864×496, 720p: 1280×720, 1080p: 1920×1080, 4k: 3840×2160

長さを省略すると 5 秒とみなし、content が draft_task で長さが明示されていない場合はモデルの自動長さ上限（2.5 は 30 秒、2.0 は 15 秒）とみなします。解像度が省略または認識できない場合は 1080p として見積もります。ByteDance の自動長さ（-1）はトップレベルでは 0〜3600 のチェックに弾かれますが、metadata 内で文字列 "-1" として送ると転送され、見積もりは同じ自動長さの上限を使います。見積もりにモデル倍率・グループ倍率・動画入力倍率を掛けた額が予約されます。倍率で課金されるモデルでは、この見積もりを通常の事前課金と比較し、大きい方を予約します。完了時のトークン精算はモデル倍率が設定されている場合のみ実行されます。倍率がないモデルでは予約額がそのまま確定額になります（倍率も固定価格もないモデルの場合、アカウントで未設定倍率のモデルが許可されていなければリクエストは拒否されます）。

リクエスト送信時の予約成功時
duration を指定見積もりトークン数 × 単価Ark の usage.total_tokens × 単価、差額を追加請求または返金
duration を省略見積もりは 5 秒同じ精算
metadata.frames を指定見積もりはフレーム数を使用同じ精算
draft_task で duration なし見積もりは 30 秒 / 15 秒同じ精算
タスク単位の固定価格を設定固定価格変更なし。トークン精算なし
SUCCESS だが usage なし—予約額のまま
FAILURE、expired、cancelled—予約額を返金
400予約なし課金なし

トークン単価は出力解像度ティア、動画入力の有無、そして価格表がその次元を定義しているモデルでは音声生成の有無に依存します。モデルの価格表が使われ、算出された倍率が 1.0 でない場合、送信レスポンスの X-New-Api-Other-Ratios ヘッダーに video_input 項目として含まれます。組み込みのフォールバック表は 2.0 モデルに base（480p / 720p）、1080p、4k の各ティアと各ティアの動画入力料率を定義し、fast バリアントは base ティアのみで動画入力倍率は 22/37 です。seedance-2.5 と seedance-2.0-mini には組み込みの価格表がなく、ティアはコンソール設定から取得します。チャネルは、リクエストしたモデル ID をキーにした VideoPrice テーブルで倍率を上書きすることもできます。コンソールに表示される価格とティアが正式です。

計算例（価格はすべて仮定です。実際の価格はコンソールを参照してください）。seedance-2.0-fast の 720p ティアが 出力 100 万トークンあたり $2、グループ倍率が 1 とします：

  1. 720p、duration: 5 で送信。見積もり：1280 × 720 = 921,600 ピクセル、24 × 5 + 1 = 121 フレーム、921,600 × 121 / 1024 = 108,900 トークン、予約額は $0.2178。
  2. Ark が usage.total_tokens: 105000 を返したので、精算額は $0.21、$0.0078 が返金されます。
  3. 同じリクエストに reference_video 項目があれば、組み込みの fast 用価格表が 22/37 ≈ 0.5946 の動画入力倍率を見積もりと精算の両方に適用します。予約額は約 $0.1295、精算額は約 $0.1249。

残高や Key のクォータが予約額に満たないリクエストは、上流へ送信される前に拒否されます。ウォレット残高不足は 403 insufficient_user_quota、Key のクォータ不足は 403 pre_consume_token_quota_failed です。

制限とエラー

Section titled “制限とエラー”
ステータスコード意味
400invalid_requestprompt の欠落・空、JSON の形式エラー、または metadata フィールドの型エラー
400invalid_secondsトップレベルの duration / seconds、または数値の metadata.duration が負か 3600 超
400model_not_supportedリクエストが提供終了した Seedance 1.x モデルにマッピングされた
400task_not_existtask_id が不明、または別のアカウントのもの
403insufficient_user_quota、pre_consume_token_quota_failedウォレット残高または Key のクォータが予約額に満たない
429—上流の容量が枯渇。メッセージは Upstream load is saturated, please try again later に置き換わります
500build_request_failed、do_request_failed、invalid_response変換の失敗、上流に到達できない、または Ark がタスク ID を返さない
500get_channel_failedリレー段階でチャネル選択に失敗（リクエスト中にチャネルが削除された場合など）
503get_channel_failedチャネルが上流で資格情報または課金のハード障害に遭遇。詳細は隠されます
上流のステータスfail_to_fetch_taskArk が送信を拒否。HTTP ステータスとメッセージは Ark のもの

よく返る 400 メッセージ（実際の戻り値どおり）：

message原因
prompt is requiredprompt が欠落、空、または空白のみ
seconds must be between 1 and 3600トップレベルの duration / seconds、または数値の metadata.duration が負か過大
unmarshal metadata failed: ...metadata フィールドの型エラー。メッセージの後半が該当フィールドを示す
model <id> is not supported by this channelオリジンまたは上流のモデル名が提供終了した Seedance 1.x に一致
task_not_existタスク ID が不明、または別のアカウントのもの

送信後に起きる失敗（コンテンツモデレーション、プロバイダのタイムアウト、キャンセル）は HTTP エラーとしては現れません。タスクレコード上で fail_reason を伴う FAILURE として現れ、予約額は返金されます。expired と cancelled も同じ扱いです。

Volcengine Ark API との違い

Section titled “Volcengine Ark API との違い”
  • エンドポイントが異なります。RouteAPI は /api/v3/contents/generations/tasks を公開していないため、Volcengine SDK のベース URL をこちらに向けても動作しません。
  • Ark 固有のパラメータは metadata に入れます。共通フィールド（prompt、images、ratio、resolution、duration、generate_audio）はトップレベルにも書け、マッピングされます。
  • 返される task_id は RouteAPI の ID で、Ark のものではありません。Ark の ID はタスクレコードの data.data.id です。
  • 送るのはカタログのモデル ID で、チャネルが Ark のモデル名へマッピングします。Ark のエンドポイント ID（ep-...）を直接扱う必要はありません。
  • タスク一覧、タスクのキャンセル、コールバック通知、ウェブ検索はサポートされません。callback_url と tools は破棄されます。
  • 課金は Ark 自身の方式ではなく、コンソールの価格表に基づくトークン精算です。

完全なスクリプト

Section titled “完全なスクリプト”

bash、curl、jq が必要です。

#!/usr/bin/env bash
set -euo pipefail
: "${ROUTEAPI_KEY:?set ROUTEAPI_KEY first}"
BASE="${ROUTEAPI_BASE:-https://api.routeapi.ai}"
AUTH="Authorization: Bearer $ROUTEAPI_KEY"


TASK_ID=$(curl -sS -X POST "$BASE/v1/video/generations" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-fast","prompt":"An orange cat stretching on a windowsill at sunrise","duration":5,"resolution":"720p","ratio":"16:9","generate_audio":false}' \
  | jq -er .task_id)
echo "task: $TASK_ID"


for _ in $(seq 1 60); do
  RESP=$(curl -sS "$BASE/v1/video/generations/$TASK_ID" -H "$AUTH")
  STATUS=$(printf '%s' "$RESP" | jq -r .data.status)
  echo "status: $STATUS $(printf '%s' "$RESP" | jq -r .data.progress)"


  case "$STATUS" in
    SUCCESS)
      curl -sSL -o "$TASK_ID.mp4" "$BASE/v1/videos/$TASK_ID/content" -H "$AUTH"
      echo "saved: $TASK_ID.mp4"
      exit 0
      ;;
    FAILURE)
      echo "failed: $(printf '%s' "$RESP" | jq -r .data.fail_reason)"
      exit 1
      ;;
  esac
  sleep 15
done


echo "timed out waiting for the task"
exit 1

ループは 15 分待機します。長時間・高解像度のタスクでは回数を増やしてください。