Seedance 2.0 FastAPI
コードからSeedance 2.0 Fastを呼び出すために必要なすべて：3ステップのクイックスタート、各フィールドとその制限、料金の計算式、Webhookとべき等性。MCPツールも同じ/v1 APIで動作します。MCPでログインした場合はクリエイティブ残高、APIキーの場合は開発者API残高を使います。
開発者APIは申請制です。
クイックスタートは3回の
キーを設定し、価格上限を付けてジョブを送信し、結果を読み取ります。
- 01
キーを
設定 する 開発者APIは申請制です。スタジオの「APIキー」から申請してください。キーは1回だけ表示されるため、環境変数に保存してください。
export API_KEY="sk_test_…" - 02
ジョブを
送信 する Idempotency-Keyとmax_creditsの上限（またはquote_id）を付けてクリップをPOSTします。すぐに202と待機中のジョブが返り、クレジットが保留されます。
curl https://api.pershot.app/v1/videos/generations \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.0-fast", "prompt": "Perfume mist in hard side light. Slow push-in, black background, grain.", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9", "generate_audio": true, "max_credits": 34 }'{ "id": "job_01J9ZK4T8W", "object": "job", "kind": "video", "status": "queued", "money_status": "reserved", "queue_position": 2, "requested_model": "seedance-2.0-fast", "credits_quoted": 34, "credits_charged": null } - 03
結果を
読み 取る statusがsucceededになるまでジョブをGETします。outputs[].urlは署名付きで24時間後に期限切れになるため、残したいものはダウンロードしてください。
curl https://api.pershot.app/v1/jobs/job_01J9ZK4T8W \ -H "Authorization: Bearer $API_KEY"
パラメーターと制限
APIが検証に使うのと同じスキーマから生成されたOpenAPIドキュメントから読み込んでいます。不明なフィールドは拒否されます。
| フィールド | 型 | 許可される値 | 備考 |
|---|---|---|---|
model必須 | string | seedance-2.0-fast · seedance-2.0-mini · auto | モデルID。 |
prompt必須 | string | 2–2,000文字 | 生成する内容：被写体、カメラ、光。 |
durationデフォルト：5 | integer | 4–15 | 出力の長さ（整数の秒数、最大15）。 |
resolutionデフォルト："720p" | string | 480p · 720p | 出力の解像度。試作は480p、納品は720pです。解像度ごとに別々に生成されます。 |
aspect_ratioデフォルト："16:9" | string | 16:9 · 9:16 · 1:1 | フレームの形状。 |
generate_audioデフォルト：true | boolean | – | ネイティブ音声。オンでもオフでも価格は同じです。 |
image_url任意 | string | httpsのURL | 動画の開始フレーム。編集モデルでは元画像。公開されているhttpsのURL、またはアップロードURL。 |
reference_image_urls任意 | string[] | 最大9 · httpsのURL | 被写体やスタイルの参照画像。プロンプト内では@image1、@image2のように参照します。 |
seed任意 | integer | 0–2,147,483,647 | 受け付けますが無視します：Seedance 2.0はシードを受け付けません。 |
quote_id任意 | string | qt_… | POST /v1/quotesの見積もりで実行します。見積もりの有効期間は10分です。 |
max_credits任意 | number | > 0 | このジョブの費用の上限。上限を超える場合、ジョブは拒否され、課金されることはありません。 |
webhook_url任意 | string | httpsのURL | ジョブのイベントを受信するhttpsのURL。 |
end_user_id任意 | string | 1–128文字 | 承認済みの開発者アカウント向け（申請制）：このリクエストに付けるご自身のユーザーID。使用状況に表示されます。 |
project_id任意 | string | prj_… | |
shot_id任意 | string | sht_… | |
routing_preference任意 | string | stability · speed | |
enhance任意 | object | – |
quote_idとmax_creditsのどちらか一方だけを送信してください。このエンドポイントはmodel "auto"を受け付けません。動画の場合は、先にPOST /v1/auto/planを呼び出し、選ばれたモデルをmax_creditsとともに送信してください。
- レートと同時実行数
- キーごとに毎分60リクエスト、同時実行はデフォルトでアカウントごとに3ジョブです。キーを増やしても同時実行数は増えません。
制限
APIが照合するのと同じ表から読み込んでいます。各行に、その制限を誰が確認するのか、超えた場合にどうなるのかを記載しています。
- 当社が確認当社が確認し、見積もりや保留の前に400を返します。
- 提供元が確認仕入れ先が確認します。拒否されたジョブは失敗となり、課金されません。
- 推奨誰も確認しません。範囲内に収めると、より良い結果が得られます。
| 制限 | 値 | 単位 | 確認する側 | 制限を超えた場合 |
|---|---|---|---|---|
| リクエスト | ||||
プロンプトの長さprompt | 2〜2,000 | 文字 | 当社が確認 | 見積もりや保留の前に、promptに対して400 invalid_requestを返します。 |
英語のプロンプトprompt | 最大1,000 | 語 | 推奨 | 受け付けます。プロンプトが長いと、モデルが指示に従いにくくなる場合があります。 |
中国語のプロンプトprompt | 最大500 | 文字（中国語） | 推奨 | 受け付けます。プロンプトが長いと、モデルが指示に従いにくくなる場合があります。 |
長さduration | 4〜15デフォルト：5 | 秒 | 当社が確認 | durationに対して400 invalid_requestを返します。1秒単位のみです。 |
解像度resolution | 480p, 720pデフォルト：720p | – | 当社が確認 | resolutionに対して400 invalid_requestを返します。 |
アスペクト比aspect_ratio | 16:9, 9:16, 1:1デフォルト：16:9 | – | 当社が確認 | aspect_ratioに対して400 invalid_requestを返します。 |
シードseed | 無視 | – | 提供元が確認 | 受け付けますが送信はしません：Seedance 2.0はシードを受け付けないため、シードを指定しても同じ結果は再現されません。 |
入力動画の長さinput_video_seconds | 2〜15 | 秒 | 当社が確認 | POST /v1/quotesで400 invalid_requestを返します。APIの生成は入力動画を受け付けません。 |
| 送信する画像 | ||||
参照画像reference_image_urls | 最大9 | 枚 | 当社が確認 | reference_image_urlsに対して400 invalid_requestを返します。 |
開始フレームまたは参照画像reference_image_urls | image_urlまたはreference_image_urls（両方は不可） | – | 当社が確認 | reference_image_urlsに対して400 invalid_requestを返します。Seedance 2.0は、ジョブごとに2つのモードのいずれかで実行されます。 |
画像の辺image_urlreference_image_urls | 300〜6,000 | px（1辺あたり） | アップロード時に当社が確認 | アップロード：見積もりや保留の前に、image_urlまたはreference_image_urls.Nに対して400 invalid_requestを返します。その他のリンク：仕入れ先がジョブを拒否し、課金されません。 |
画像の形状image_urlreference_image_urls | 0.4〜2.5 | 幅 ÷ 高さ | アップロード時に当社が確認 | アップロード：見積もりや保留の前に、image_urlまたはreference_image_urls.Nに対して400 invalid_requestを返します。その他のリンク：仕入れ先がジョブを拒否し、課金されません。 |
アップロードサイズfile | 最大10 | MB | 当社が確認 | POST /v1/uploadsはfileに対して400 invalid_requestを返します。 |
アップロード形式file | JPEG, PNG, WebP | – | 当社が確認 | ファイル名ではなく、ファイルの中身から判定します。それ以外の形式：fileに対して400 invalid_requestを返します。 |
リンク画像のサイズimage_urlreference_image_urls | 最大30 | MB | 提供元が確認 | 他のホストからリンクした画像が対象です。仕入れ先がジョブを拒否し、課金されません。 |
リンク画像の形式image_urlreference_image_urls | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF | – | 提供元が確認 | 他のホストからリンクした画像が対象です。仕入れ先がジョブを拒否し、課金されません。 |
| 出力 | ||||
| 出力ピクセル数 | 480p16:9864×4969:16496×8641:1640×640720p16:91280×7209:16720×12801:1960×960 | px | 提供元が確認 | 解像度とアスペクト比ごとにモデルが決定します。 |
| フレームレート | 24 | fps | 提供元が確認 | すべての動画で同じです。 |
| 出力形式 | MP4 | – | 提供元が確認 | すべての動画はMP4で、generate_audioがオンの場合は音声付きです。 |
| リンク | ||||
| アップロードリンク | 7 | 日 | 当社が確認 | 期限を過ぎるとリンクは403を返します。ファイルを再度アップロードしてください。 |
| 出力リンク | 24 | 時間 | 当社が確認 | 期限を過ぎるとリンクは403を返します。ジョブを再度GETすると新しいリンクを取得できます。ファイル自体は12か月間保持されます（日付はジョブのoutputs_expire_at）。アセットに保存したもの、プロジェクトで使用中のものはそれ以降も保持されます。 |
当社は他のホストから画像を取得しないため、そうしたリンクのサイズは仕入れ先が確認します。仕入れ先が拒否したジョブには課金されません。 同じ制限はJSONでも取得できます：GET /v1/modelsは、すべてのモデルについてlimitsオブジェクトを返します。
料金をオープンに
すべてのジョブは実行前にクレジットで見積もられます（US$1 = 100クレジット）。秒単位の料金は予算の目安で、正確な金額はPOST /v1/quotesが返します。
クレジット = ceil(BytePlusの定価 × 0.55 × 100)。ここで、定価 = (入力の秒数 + 出力の秒数) × 幅 × 高さ × 24 ÷ 1024 × 定価単価| 仕様 | 1秒あたり（API） | 5 s | 10 s | 15 s |
|---|---|---|---|---|
| 480p動画入力なし | $0.031入力動画あり：$0.019/s$10で約322 s | 16 cr≈ $0.16 | 31 cr≈ $0.31 | 47 cr≈ $0.47 |
| 720p動画入力なし | $0.067入力動画あり：$0.040/s$10で約149 s | 34 cr≈ $0.34 | 67 cr≈ $0.67 | 100 cr≈ $1.00 |
拒否または失敗したジョブには課金されません。
Webhookとべき
再試行で二重に課金されることはなく、ポーリングも不要です。
- べき等性
- 生成のPOSTにはすべてIdempotency-Key（表示可能なASCII文字で1〜255文字）が必要です。24時間以内に同じキーを送るとHTTP 200で同じジョブが返されるため、タイムアウト後に再試行しても、2つ目のジョブが作成されたり課金されたりすることはありません。
- 拒否されたプロンプト
- 事前チェックで拒否されたプロンプト（422 content_rejected）では何も作成されないため、同じキーを新しいプロンプトで再利用できます。
- イベント
job.queuedjob.processingjob.succeededjob.failedjob.cancelled- 署名
- X-Signatureには、UNIX時刻のtと、tとドットと生のボディをwhsec_シークレットで鍵付けしたHMAC-SHA256であるv1が含まれます。5分より古いタイムスタンプは拒否し、X-Event-Idで重複を排除してください。
- 配信
- 10秒以内に2xxが返れば配信済みとみなします。失敗した配信は、1 min、5 min、30 min、2 h、6 hの後に再試行されます。リダイレクトには従いません。
{
"id": "evt_01J9ZKB1QX",
"type": "job.succeeded",
"created_at": "2026-09-29T14:02:31Z",
"data": {
"job": {
"id": "job_01J9ZK4T8W",
"object": "job",
"kind": "video",
"status": "succeeded",
"money_status": "settled",
"requested_model": "seedance-2.0-fast",
"credits_charged": 34,
"outputs": [
{
"kind": "video",
"url": "https://…/job_01J9ZK4T8W.mp4?sig=…"
}
]
}
}
}import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyWebhook(header, rawBody, secret, toleranceSec = 300) {
let t = null;
const signatures = [];
for (const item of (header ?? "").split(",")) {
const [key, value] = item.split("=", 2);
if (key === "t") t = Number(value);
if (key === "v1") signatures.push(Buffer.from(value, "hex"));
}
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
return signatures.some((s) => s.length === expected.length && timingSafeEqual(s, expected));
}
// verifyWebhook(req.headers["x-signature"], rawBody, process.env.WEBHOOK_SECRET)
// Answer 2xx quickly, and skip an X-Event-Id you have already handled.エラーと対処法
すべてのエラーは同じ形式です：code、message、param、request_idを含むerrorオブジェクト。よく発生するものは次のとおりです：
| コード | HTTP | 対処法 |
|---|---|---|
invalid_request | 400 | paramに示されたフィールドを修正してください。 |
unauthorized | 401 | キーとBearerヘッダーを確認してください。 |
insufficient_credits | 402 | チャージしてから、同じIdempotency-Keyで再試行してください。 |
forbidden_model | 403 | スタジオでキーの許可リストにモデルまたはツールを追加するか、別のキーを使用してください。高画質化などのツールには、個別の登録が必要です。 |
quote_expired | 409 | 新しい見積もりを取得してください。見積もりの有効期間は10分です。 |
price_changed | 409 | 価格が上限を超えました。再度見積もるか、max_creditsを引き上げてください。 |
content_rejected | 422 | 課金はされていません。プロンプトまたは画像を変更してください。 |
rate_limited | 429 | Retry-Afterの時間だけ待ってから、再試行してください。 |
upstream_unavailable | 503 | モデルを利用できません。後で再試行してください。開始されなかったジョブには課金されません。 |