Seedance 2.5 APIの使い方：クイックガイド

APIキーから完成したMP4まで4ステップで進めます。 認証済みの POST リクエストを送信し、request_id を保存し、結果エンドポイントを 10〜20秒ごと にポーリングし、リンクが期限切れになる前に（多くの場合 24時間以内 に）動画をダウンロードします。

短い版が欲しいなら、私が念頭に置くのはこうです。

• 正しいエンドポイントを使う
  • テキストプロンプトには seedance-2.5-text-to-video
  • 公開画像URLをアニメーション化するには seedance-2.5-image-to-video
• 正しいヘッダーを送る
  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json
• 主な出力設定を選ぶ
  • resolution：480p から 4K
  • aspect_ratio：16:9 や 9:16 など
  • duration：最大 16秒
  • generate_audio：音とセリフには true
• 再送信ではなくポーリングする
  • predictions/{request_id}/result を確認する
  • queued、running、succeeded、failed を注視する
• コストを管理する
  • 480p または 720p から始める
  • 同じ seed を保つ
  • ショットが良さそうになったときだけ 1080p または 4K で再実行する

また、最も一般的な失敗ポイントも注視します。不正な認証ヘッダーによる 401、クレジット不足による 402、アクティブなジョブが多すぎることによる 429、不正なJSONやフィールド欠落による 400 です。APIMart では、ジョブ開始時にクレジットが予約され、完了した場合にのみ課金されます。失敗したジョブは返金されます。

モデルを選ぶなら、Seedance 2.5 はこのラインナップで最上位の選択肢です。最大 16秒、最大 3,840 × 2,160、最大 50 の参照入力。Seedance 2.0 は中間に位置し、Seedance 2 Mini は低コストの下書きに向いています。

結論： 有効な POST リクエストを作成し、1つのIDを保存できれば、ワークフロー全体を実行できます。残りはプロンプトの調整、根気強いポーリング、そしてURLがタイムアウトする前のファイルのダウンロードです。ポストプロセスには、AIキャンバス を使って生成したクリップをアップスケールしたり編集したりできます。

ステップ1：APIMart のアクセスを設定し、リクエストを認証する

すべての Seedance 2.5 リクエストには有効なAPIキーと正しいヘッダーが必要です。そこから始めましょう。それが整えば、動画生成のペイロードとジョブトラッキングに進めます。

APIキーを安全に作成して保管する

アカウントダッシュボードの Settings または API Keys でキーを作成します。その後、ソース管理ではなく .env ファイルや環境変数に保管しましょう ^[6][8]。

export APIMART_API_KEY="sk_live_xxxxxx"

キーを紛失した場合は、それを失効させて新しいものを作りましょう ^[3]。統合テストには、本番の使用量に触れないよう別の sk_test_ キーを使いましょう ^[3]。

次に、そのキーをAuthorizationヘッダーですべてのリクエストに含めます。

Authorizationヘッダーを正しく追加する

https://muapi.ai/api/v1/ に次のヘッダーでリクエストを送信します。

• Authorization: Bearer sk_live_xxxxxx
• Content-Type: application/json

小さなフォーマットのミス一つでリクエストが壊れることがあります。最も一般的なのは Bearer プレフィックスを省くこと、またはキーの前のスペースを欠くことです ^[3][7]。それは通常 401 Unauthorized レスポンスにつながります。Content-Type: application/json を省いてもリクエストが失敗することがあります ^[3][7]。

認証が設定できたら、動画リクエストのペイロードに進めます。

ステップ2：Seedance 2.5 の動画生成リクエストを組み立てる

APIキーを設定したら、次の動きは有効なリクエストボディを組み立てることです。すべての Seedance 2.5 ジョブは、何から始めるかに応じて2つのエンドポイントのいずれかへの POST リクエストで始まります。プロンプトのみの生成には https://muapi.ai/api/v1/seedance-2.5-text-to-video を、ソース画像をアニメーション化する場合は https://muapi.ai/api/v1/seedance-2.5-image-to-video を使います ^[1]。

正しい入力モードとパラメーターを選ぶ

入力モードがペイロードの形を決めます。テキストから動画は prompt だけが必要です。画像から動画は、10 MB未満の公開アクセス可能なJPG、PNG、WEBPファイルを指す image_url も必要です ^[1]。

そこから、いくつかの主要フィールドで出力を制御します。

• resolution：480p、720p、1080p、または 4K
• aspect_ratio：16:9、9:16、1:1、4:3、3:4、または 21:9
• duration：Muapi では最大16秒
• generate_audio：true に設定すると、同期した環境音、効果音、セリフをオンにするブール値 ^[1]

賢い進め方は、固定した seed で 480p から始めることです。モーション、ペーシング、フレーミングが良さそうなら、同じシードを最終版のために 1080p または 4K で再実行します。

プロンプトには、このフローを使います：被写体 → アクション → カメラ → 設定 → ムード ^[4]。モーション、カメラの方向、ムードを prompt 自体の中に保ち、バリエーションをテストする間は seed を変えないでおきましょう。リップシンクが必要な場合は、話すセリフをプロンプト文字列の中の二重引用符で囲んで置きます。例えば：she turns and says "We launch at dawn." その場合、generate_audio が true に設定されていることを確認してください ^[1]。

ペイロードが良さそうになったら、ジョブを送信し、返されたリクエストIDを保存します。ポーリングに必要になります。

cURL、Postman、Python、JavaScriptでのサンプルリクエスト

以下は、4つの一般的なツールで示した同じテキストから動画のペイロードです。

cURL

curl -X POST https://muapi.ai/api/v1/seedance-2.5-text-to-video \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true,
    "seed": 42
  }'

Postman - 新しい POST リクエストを作成し、エンドポイントURLを貼り付け、Headers タブに Authorization: Bearer <your_key> と Content-Type: application/json を追加し、上のJSONを Body → raw → JSON に貼り付けます。Send をクリックし、レスポンスから request_id を保存します。

Python

import os, requests

payload = {
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": True,
    "seed": 42
}

response = requests.post(
    "https://muapi.ai/api/v1/seedance-2.5-text-to-video",
    headers={
        "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())  # save request_id here

JavaScript (fetch)

const response = await fetch("https://muapi.ai/api/v1/seedance-2.5-text-to-video", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    aspect_ratio: "16:9",
    resolution: "1080p",
    duration: 8,
    generate_audio: true,
    seed: 42
  })
});

const data = await response.json();
console.log(data.request_id); // use this to poll for results

いくつかのミスが素早くつまずきの元になります。公開アクセスできない image_url を送らないでください。同じプロンプト内で互いに矛盾するカメラの方向を重ねないでください。そして画像から動画モードでは、ソース画像がすでに被写体を定義しているなら、被写体を再度記述しないでください ^[1]。

送信後は、MP4のURLが準備できるまでジョブのステータスをポーリングします。

APIMartの動画モデルラインナップでSeedance 2.5をいつ使うか

このクイック比較は、プロンプトの調整や解像度の引き上げを始める前に、適切なモデルを選ぶのに役立ちます。Seedance 2.5 はネイティブ4K、最大50の参照入力、より長いクリップサポートを提供します。Seedance 2 Mini は軽量な下書きに向いており、一方 Seedance 2.0 は汎用の選択肢として中間に位置します ^[1][9][4]。

プロジェクトが最終成果物（商品ローンチ動画、ブランドのシネマティックシーケンス、または放送に向かうもの）なら、Seedance 2.5 がより良い選択です。高品質音声付きAI動画生成 が必要なプロジェクトには、Google の Veo 3.1 がもう一つの強力な候補です。まだアイデアをテストしているなら、Mini から始めて低コストでモーションを確認しフレーミングを固定し、その後で最終レンダリングのために 2.5 に移りましょう。

ステップ3：ジョブを送信し、ステータスを追跡し、レスポンスを読む

POST リクエストを送ると、APIは request_id を返します。それを保存しましょう。生成は非同期で走るため、後でジョブを確認するのにそのIDを使います。

作成から完了まで非同期ジョブを扱う

ジョブを送信した後、次のステップはシンプルです。最終的な動画が準備できるまでポーリングします。

https://muapi.ai/api/v1/predictions/{request_id}/result に GET リクエストを送ります。最初のポーリングの前に送信後約10秒待ち、その後10〜20秒ごとに再度確認します。5秒より頻繁にポーリングすると、レート制限に当たる可能性があります ^[1][3]。

各レスポンスには status フィールドが含まれます。そのフィールドが、何が起きているか、次に何をすべきかを教えてくれます。

ジョブが succeeded に達したら、出力URLが期限切れになる前に取得しましょう。

出力フィールドを読み、結果を保存する

ステータスが succeeded に変わったら、出力ペイロードを読んで結果を保存します。

成功したレスポンスには video_url が含まれます。要求した場合は last_frame_url も含まれることがあります。video_url、任意の last_frame_url、そして seed、duration、resolution、aspect_ratio、usage のようなメタデータを保存しましょう。そのデータは課金と、後で同じ実行を再現するために重要です ^[11][13]。

出力URLはしばしば24時間以内に期限切れになるので、ファイルをすぐに自分のストレージにダウンロードしましょう ^[11][12][13]。ジョブが失敗したら、error.code と error.message をログに記録します。そして失敗が安全性チェックに関連している場合は、自動的に再試行しないでください ^[2][11][12]。

ステップ4：エラーのトラブルシューティング、コスト管理、まとめ

認証、検証、レート制限のエラーを修正する

ジョブを送信して結果をポーリングした後、いくつかのシンプルなチェックが本番の実行が脱線するのを防げます。ほとんどの Seedance の失敗は、同じ一握りの形で現れる傾向があります。

参照アセットについては、URLが公開されていること、ファイルがJPG、PNG、またはWEBPであること、そして記載されたサイズ制限内に収まっていることを確認しましょう ^[12][4]。

コストを削減し、信頼性を高める

エラー処理が設定できたら、次のステップはシンプルです。安くテストし、それから大きくレンダリングする です。

プロンプトを480pまたは720pから始めましょう。これは、フレーミング、モーション、そしてプロンプトが望みどおりに動いているかを確認する低コストな方法を与えてくれます。ショットが良さそうなら、同じ seed の値を最終出力のために4Kで再実行します ^[1][4]。

クリップの長さも重要です。短い動画ほどコストが低いので、それでも役目を果たす最小限に長さを抑えましょう ^[1][10]。

チームがお金を無駄にする、こっそりした方法もあります。ネットワークタイムアウト後の重複送信です。クリーンな修正の一つは、各POSTリクエストの前にプロンプト、モデルID、メディアURLをハッシュ化することです。そのハッシュがすでにタスクIDにマッピングされているなら、新しい送信をまるごとスキップします ^[11]。そしてジョブが succeeded になったら、完成したファイルを永続ストレージに保存し、後でタスクの記録に依存しなくて済むようにしましょう ^[12][11]。

結論：APIドキュメントから動く動画生成へ

認証、ペイロード、ポーリング、エラー処理が整い、あなたは今、APIMart 上で完全な Seedance 2.5 のワークフローを手にしています。

よくある質問

::: faq

Seedance 2.5 が動画を仕上げるのにどれくらいかかりますか？

Seedance 2.5 は最大 30秒 の1本の連続した動画クリップを生成できます。ただし、ドキュメントは正確な仕上げ時間を記載していません。

APIは非同期で走ります。タスクを送信し、タスクIDを受け取り、その後ステータスエンドポイントをポーリングするか、Webhookを待って完成した動画を取得します。

処理時間は、解像度やシーンの複雑さのようなものによって変わり得ます。 :::

::: faq

ダウンロードする前に動画URLが期限切れになったらどうすればよいですか？

ダウンロードする前に動画URLが期限切れになると、そのリンクからファイルを取得できなくなります。Seedance はこれらの一時的なURLを 24時間 アクティブに保ちます。

安全な手はシンプルです。タスクが完了と表示されたらすぐに、動画を自分の安全なオブジェクトストレージにコピーしましょう。APIは非同期で走り、出力を永久には保持しないため、あなたのアプリは動画を取得してすぐに長期ストレージに移すべきです。 :::

::: faq

失敗したリクエストを再試行する際に重複課金を避けるにはどうすればよいですか？

HTTPクライアントだけでなく、自分の永続的なジョブ記録に結び付けた 冪等なリクエスト処理 を使いましょう。

何かを送信する前に、プロンプト、モデルID、アセットID、ユーザー識別子のような入力から決定的なリクエストハッシュを作ります。その後、そのハッシュを submitting ステータスとともに自分のデータベースに保存します。

同じハッシュが再び現れたら、新しいものを作る代わりに 既存のジョブを返します。

プロバイダーのジョブIDを保存したら、リクエストを再送信しないでください。そのジョブIDでポーリングを再開するだけにしましょう。 :::