Seedance API の使い方:API キー、リクエスト、ポーリング、参照
Seedance API の使い方を順に解説。API キーの作成、動画タスクの送信、動画 URL を得るためのポーリング、画像・動画・音声の参照、エージェントでの実行まで。
Markdown で読むSeedance API を使うには、API キーを作成し、公式の ModelArk 動画タスクのボディを 1 つのエンドポイントに送信し、返されたタスクを動画 URL が用意されるまでポーリングします。同じ手順は Seedance 2.0、Seedance 2.0 Fast、Seedance 2.0 Mini、Seedance 2.5 のすべてで使えます。変わるのは model の値と、モデル固有のいくつかの制限だけです。
このガイドでは、動作するコードで各ステップを順に説明し、そのあと参照の追加方法、Seedance 2.5 でのクリップの編集、作業をコーディングエージェントに任せる方法を紹介します。
最初のリクエストの前に必要なものは?
- API キー。 API キーのページで作成し、サーバー側に保管してください。ブラウザのコードには決して入れないでください。
- クレジット。 請求ページで残高をチャージします。クレジットに有効期限はなく、失敗したタスクは課金されません。
- モデル ID。 下の表から 1 つ選びます。
| モデル ID | モデル | 解像度 | クリップの長さ |
|---|---|---|---|
dreamina-seedance-2-0 | Seedance 2.0 | 480p〜4K | 4〜15 秒 |
dreamina-seedance-2-0-fast | Seedance 2.0 Fast | 480p、720p | 4〜15 秒 |
dreamina-seedance-2-0-mini | Seedance 2.0 Mini | 480p、720p | 4〜15 秒 |
dreamina-seedance-2-5 | Seedance 2.5 | 480p〜1080p | 4〜30 秒 |
どれにするか迷ったら、Seedance 2.0 vs Fast vs Mini ガイドと Seedance 2.5 vs 2.0 ガイドで比較しています。
export SEEDROUTER_API_KEY="your-key"Seedance のリクエストはどう送る?
タスクを /v1/contents/generations/tasks に POST します。ボディは公式の ModelArk「動画生成タスクの作成」リクエストです:
curl https://api.seedrouter.ai/v1/contents/generations/tasks \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0",
"content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true
}'レスポンスは動画ではなくタスク ID です:
{"id": "task_..."}すでに ModelArk を呼び出しているなら、変更するのはベース URL(https://api.seedrouter.ai/v1)と API キーだけです。未知のフィールドは課金前に拒否され、Fast や Mini での 1080p のようにモデルが対応していない設定も同様に拒否されます。
動画はどう取得する?
status が succeeded、failed、expired のいずれかになるまで、10〜20 秒ごとにタスクをポーリングします。5 秒・720p のクリップは通常 2〜3 分かかります。Python の場合:
import os
import time
import requests
API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
response = requests.post(
f"{API}/contents/generations/tasks",
headers=headers,
json={
"model": "dreamina-seedance-2-0",
"content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
},
timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
result = requests.get(f"{API}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
result.raise_for_status()
task = result.json()
if task["status"] == "succeeded":
print(task["content"]["video_url"])
break
if task["status"] in ("failed", "expired"):
raise RuntimeError(task["error"]["message"])
time.sleep(15)
else:
raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")成功したタスクでは、content.video_url に動画が、usage.completion_tokens に課金対象の動画トークンが入り、モデルが選んだ seed を含め、実際にレンダリングされた設定も返されます。動画は私たちのストレージでホストされています。長期間必要な場合は、ご自身のストレージにダウンロードしてください。
ポーリング中のタイムアウトは、動画の失敗を意味しません。タスク ID を保持して再確認してください。新しいタスクを送信すると、2 本目の動画の料金がかかります。コールバック URL はないため、結果の取得はポーリングで行います。また、送信したタスクはキャンセルできません。
画像・動画・音声はどう追加する?
content に項目を追加します。各項目には公開 URL と role を指定します:
curl https://api.seedrouter.ai/v1/contents/generations/tasks \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0",
"content": [
{"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
{"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
{"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
],
"ratio": "adaptive",
"duration": 8
}'| モード | content に入れるもの |
|---|---|
| テキストから動画 | テキスト項目 1 つ |
| 最初のフレーム(画像から動画) | テキストと、role が first_frame の画像 1 枚 |
| 最初と最後のフレーム | テキストと、first_frame と last_frame の画像を 1 枚ずつ |
| 参照 | テキストと、reference_image・reference_video・reference_audio の任意の組み合わせ |
Seedance 2.0 とその Fast・Mini 版は、参照画像を最大 9 枚、動画を 3 本、音声を 3 本受け付けます。Seedance 2.5 はそれぞれ最大 30、10、10 です。メディアは URL で指定する必要があり、base64 やファイルのアップロードは受け付けません。実在の人物の顔を含む参照画像や参照動画は、モデルがサポートしていません。メディアはタスク開始時にチェックされ、制限に違反するファイルは生成前にタスクが失敗し、課金されません。
Seedance 2.5 でクリップを編集・延長するには?
クリップを reference_video として送り、omni_reference_task_type を設定します:
{
"model": "dreamina-seedance-2-5",
"content": [
{"type": "text", "text": "Change the jacket to red. Keep everything else the same."},
{"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}, "role": "reference_video"}
],
"omni_reference_task_type": "edit"
}映像の内容を変えるには edit、最後のフレームの先へ続けるには extend を使います。edit では duration をデフォルトの -1 のままにし、どちらの場合も ratio は adaptive のままにしてください。入力の秒数は、料金ガイドで説明しているとおり、参照ありのレートで課金されます。
コーディングエージェントに Seedance API を使わせるには?
Claude Code、Codex、Cursor のようなコーディングエージェントは、シェルコマンドや短いスクリプトで API を呼び出せます。SeedRouter は MCP サーバー、パッケージ化されたスキル、ComfyUI ノードを提供していません。このプロンプトが連携のすべてです。まずキーを環境変数に設定してから、次を貼り付けてください:
Use the SeedRouter API to generate a Seedance video for me.
Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.
Goal: [subject, action, camera move, lighting, what the clip is for]
Model: [dreamina-seedance-2-0 | dreamina-seedance-2-0-fast | dreamina-seedance-2-0-mini | dreamina-seedance-2-5]
Resolution: [480p | 720p | 1080p | 4k] Ratio: [16:9 | 9:16 | 1:1 | adaptive] Duration: [seconds]
References: [public image, video or audio URLs with their roles, or none]
Send POST https://api.seedrouter.ai/v1/contents/generations/tasks with
{"model": "...",
"content": [{"type": "text", "text": "..."}],
"resolution": "...", "ratio": "...", "duration": 5}
Media goes in content as image_url, video_url or audio_url items with a role,
never base64. Do not add fields that are not in the API reference.
Before sending, show me the request body and wait for my approval: each
task is charged. Then poll GET https://api.seedrouter.ai/v1/contents/generations/tasks/{id}
every 15 seconds until status is succeeded, failed or expired. If polling
times out, keep checking the same task; never resubmit. Save
content.video_url into ./videos/ and tell me the file path.承認のステップは重要です。エージェントはあなたの残高を使うので、自分の判断で送信させてはいけません。
よくある質問
Seedance の API キーはどう取得しますか?
サインインして API キーのページを開き、キーを作成します。同じキーがすべての Seedance モデルと、SeedRouter のほかのモデルで使えます。
Seedance API のドキュメントはどこにありますか?
Seedance 2.0 と Seedance 2.5 の API リファレンスに、すべてのフィールド、制限、エラーが cURL・Python・Node.js・Go の例とともに記載されており、OpenAPI ファイルとコピー可能な Markdown 版もあります。
複数の動画を同時に生成できますか?
動画 1 本ごとに 1 タスクを送信し、タスクを並行してポーリングしてください。各タスクは動画を 1 本返し、個別に課金されます。最近のタスクを一覧するには、page_num、page_size、filter.status などのフィルタを付けて GET /v1/contents/generations/tasks を呼び出します。
どんなエラーに対応すべきですか?
400 は、未知のフィールドや非対応の解像度など、ボディがルールに違反したことを意味し、何も課金されません。failed または expired で終わったタスクはエラーコードとメッセージを持ち、こちらも課金されません。すべてのコードと再試行すべきタイミングはエラーガイドに記載しています。
最初のリクエストを送る
キーを作成し、少額をチャージして上の Python の例を実行するか、Seedance 2.0 プレイグラウンドでコードを書かずに同じリクエストを試してください。より長いクリップや編集には、モデルを dreamina-seedance-2-5 に変え、Seedance 2.5 のページを参照してください。



