チュートリアル
seedance-2.5-flash 画像から動画生成 API チュートリアル:curl と Python Requests
開発者向けの実践的な統合演習:リクエスト構造、最初/最後のフレーム入力、非同期ポーリング、エラートラブルシューティング
このページの内容
画像から動画生成の呼び出しが実際に行うこと
最初のコードを書く前に、API が裏側で何を行っているかを理解しておくと役立ちます。seedance-2.5-flash/image-to-video の呼び出しは、動画ファイルが返るまでブロックする同期リクエストではありません。2 段階の非同期ワークフローです。まずジョブを送信し、次にその結果をポーリングします。
送信フェーズ
入力画像と生成設定を含む POST リクエストを送信します。API はリクエストボディを検証し、ジョブをキューに入れ、ジョブ識別子と初期状態を含むレスポンスを即座に返します。この時点ではまだピクセルはレンダリングされていないため、この処理は高速で、通常は一瞬で完了します。ここでのあなたの役割は、その識別子を取得して適切に保存することです。
レンダリングフェーズ
生成はバックグラウンドで行われます。クリップの長さや設定によっては、かなりの実時間がかかる場合があります。この待機期間中に最終的な動画 URL がすでに利用可能であることを期待してはいけません。代わりに、ジョブの状態を問い合わせる必要があります。
結果フェーズ
最終的にジョブは終端状態に達します。成功の場合はダウンロード可能な動画成果物が付随し、失敗の場合は調査可能なエラーが付随します。終端状態に達したら、ポーリングを停止してください。
これがコードにとって重要な理由
モデルが非同期であるため、最もよくある統合上の誤りは構文上のものではなく、アーキテクチャ上のものです。最初のレスポンスに動画が含まれていると仮定すること、状態フィールドをポーリングする代わりに固定間隔でスリープすること、そして一時的な processing 状態と恒久的な失敗を区別できないことです。このチュートリアルの内容はすべて、クリーンな「送信 → ポーリング → 終了」ループを中心に展開しているので、読み進める際にはこれら 3 つのフェーズを念頭に置いてください。
前提条件とリクエスト構造
初回呼び出しの前に用意するもの
- API 認証情報。 すべてのリクエストに付随する HiAPI API キーです。ソース管理ではなく環境変数(
HIAPI_API_KEY)に保存してください。以下の例はそのように読み取ります。 - モデル識別子。 このチュートリアルでは文字列は固定です:
seedance-2.5-flash/image-to-video。不透明な定数として扱い、各部分を連結して組み立てないでください。 - ソース画像。 公開 URL またはサポートされているインライン画像参照です。モデルには少なくとも 1 枚の最初のフレーム画像が必要です。
- HTTP クライアント。 スモークテスト用の
curlと、今後維持する予定のものにはrequestsを使用します。
リクエストボディの論理フィールド
言語にかかわらず、画像から動画生成のリクエストボディはいくつかの概念グループで構成されます。それぞれを個別に理解することで、JSON が読みやすくなります。
モデルと入力
- モデル識別子。
- 最初のフレーム画像と、オプションの最後のフレーム画像を含む入力オブジェクト。第 4 章でそれらがどのように相互作用するかを説明します。
出力設定
- 解像度と長さに関連するスイッチ。
- 生成されたクリップに付随する音声トラックを含めるかどうかを決めるネイティブ音声スイッチ。第 5 章でいつ有効にするかを説明します。
何が返されるか
送信が成功すると、ジョブオブジェクトが返されます。実際に必要なフィールドはジョブ識別子と現在の状態です。それ以外はすべて、記録または無視できるメタデータです。初日からレスポンス全体を型付きモデルにパースしないでください。まず記録して確認し、それから絞り込んでください。
進む前に簡単な現実確認をしましょう。リクエストボディに、その名前を一文で説明できないフィールドが含まれている場合は、それを削除して最小構成から始めてください。seedance-2.5-flash/image-to-video のモデルページは、正確に受け入れられるフィールド名のリファレンスです。
curl でジョブを送信する
動作する可能性のある最小リクエストから始め、その後フィールドを 1 つずつ追加します。以下は curl による最小送信です。
curl -X POST "$HIAPI_BASE_URL/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/image-to-video",
"input": {
"first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
}
}'
フィールドごとの注釈
Authorization—— ベアラートークンとしての API キーです。ここで誤ると、検証が実行される前に認証エラーが返るため、デバッグ時にはまずこれを確認してください。Content-Type: application/json—— 必須です。省略すると、紛らわしい下流のエラーが発生します。model—— 固定のモデル識別子です。ここで誤字があると、サイレントなフォールバックではなく 4xx が返ります。input.first_frame_image—— クリップの冒頭画像です。ネットワークから実際にアクセス可能な URL を使用してください。プライベートまたは期限切れの URL は、送信時ではなく取得時に失敗します。
レスポンスの読み取り
レスポンスはジョブ識別子と状態を含む JSON です。識別子をすぐに保存してください。これが第 7 章でポーリングする对象です。シェルで抽出する簡単な方法は次のとおりです。
# 上記の curl の後に、jq を介してパイプ処理する
# {"job_id": "...", "status": "queued"}
最後のフレームを追加する
終了フレームも制御するには、同じ input オブジェクト内に 2 枚目の画像を追加します。フィールド名と受け入れられる形式についてはモデルドキュメントに従ってください。代替の綴りを推測しないでください。API は未知のキーを無視するのではなく拒否します。
最小リクエストが動作したら、問題が発生したときに再実行できるスモークテストが手に入ります。それをファイルに保存してください。午前 2 時にサービスで問題が発生したとき、それはどんな長い説明よりも価値があります。
最初のフレームと最後のフレームの入力
入力画像は、ジョブが成功するかどうかを最も大きく左右する要因です。入力画像はクリップの内容を形作ると同時に、リクエストが拒否される最も一般的な原因でもあります。
最初のフレームが制御するもの
最初のフレーム画像は、生成されるクリップの冒頭状態を設定します。構図、被写体、ライティング、色彩です。モデルはその開始点から動きと継続を生成するため、画像はタイムゼロに実際に現れてほしい 1 フレームのように見えるべきです。ぼやけた、トリミングされた、または高度に圧縮されたソース画像は、後の工程で魔法のように良くなることはありません。
最後のフレームが制御するもの
最後のフレーム画像を提供すると、終了状態を固定できます。クリップが特定のショットで終わる必要がある場合に役立ちます。製品の美しいカット、ロゴの出現、編集でのマッチカットなどです。省略した場合、モデルが独自に結末を選びます。これは探索的な作業には問題ありませんが、本番では予測できません。
両方が相互作用する仕組み
両方が提供されると、モデルはそれらの間を補間します。これには実際的な影響があります。
- コントラストよりも連続性。 同じシーンで適度な動きのある 2 つのフレームは、無関係な 2 つの画像よりも一貫したクリップを生成します。フレームの差が極端な場合、合理的な遷移ではなく、目に見える変形が発生すると予想してください。
- アスペクト比は一致させるべきです。 最初のフレームと最後のフレームのアスペクト比が一致しないと、モデルは不自然なリフレーミングを強いられます。送信前に両方を同じ比率にトリミングしてください。
- 解像度は同程度にすべきです。 鮮明な最初のフレームと低解像度の最後のフレームを送信すると、モデルに矛盾した信号を与えます。
送信前のチェックリスト
送信する前に、以下を確認してください。両方の画像 URL が公開アクセス可能で、ジョブの途中で期限切れにならないこと、両方がサポートされている形式であること、両方のアスペクト比が同じであること、どちらもレンダリングしたくない UI 要素を含むスクリーンショットでないことです。各 URL に対する簡単な HEAD リクエストは、失敗した生成ジョブよりも低コストでほとんどの問題を捕捉します。
拒否が発生した場合、エラーメッセージは通常、入力オブジェクトを指し示します。API を疑う前に、まず画像をローカルで検証してください。サイズ、形式、アクセス可能性です。
解像度とネイティブ音声の設定
出力設定は、開発者が過剰に設定しがちな部分です。良いニュースはデフォルト値が合理的であることです。リスクは、別のモデルのドキュメントから値をそのまま流用することです。
解像度
解像度は配信される動画のサイズを決定し、それが生成時間と出力ボリュームに影響します。2 つの経験則があります。
- 数字ではなく目的地に合わせて選ぶ。 モバイルのフィード向けのクリップは、大きなサイズでレンダリングしてから縮小する必要はありません。ターゲットプラットフォームを満たす最小の解像度を選んでください。
- ドキュメントのプリセットのいずれかを優先する。 任意の、またはサポートされていない値を渡すことは、リクエストが拒否される一般的な原因です。特定のフレームが必要な場合は、リクエストバリデーターと戦うのではなく、生成後にトリミングまたはスケーリングしてください。
ネイティブ音声
ネイティブ音声スイッチは、生成されたクリップに、動画と一緒に生成される付随音声トラックを含めるかどうかを決定します。必要かどうかを検討してください。
- 有効にする場合、クリップが音声付きで視聴される最終成果物であるときです。ソーシャルコンテンツ、短いプロモーション、環境音が動きの感覚を高めるキャラクターシーンなどです。
- 無効にする場合、エディタで独自の音楽やナレーションを追加するとき、またはクリップが中間アセットであるときです。捨てる予定の音声を生成することは無駄な作業であり、下流の処理をより重くします。
長さ
長さは他のすべてと結合しています。長いクリップは生成に時間がかかり、被写体の一貫性ドリフトも発生しやすくなります。初回の統合では、短く始めてください。短いクリップでパイプラインがエンドツーエンドで動作することを確認してから、パイプラインを信頼して長くしてください。
設定オブジェクトを小さく保つ
品質問題を修正するために設定を追加していることに気づいたら、立ち止まって、問題が実際に入力画像にあるかどうかを確認してください。期待外れの出力のほとんどは、あるノブの欠如ではなく第 4 章に起因します。意識的に設定し、正確な設定オブジェクトを各ジョブ識別子と一緒に記録すれば、品質の変化を特定の調整に帰属させることができます。
Python で同じリクエストを行う
curl リクエストは Python に直接変換できます。ここでの目標はフレームワークではなく、ジョブを送信して識別子を返す、小さく読みやすいクライアントです。これによりポーリング層を分離したままにできます。
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"
def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
payload = {
"model": MODEL,
"input": {"first_frame_image": first_frame_url},
}
if last_frame_url:
payload["input"]["last_frame_image"] = last_frame_url
response = requests.post(
f"{BASE_URL}/image-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
このように構造化する理由
- 環境変数で設定する。 ベース URL とキーはコードの外に置かれるため、同じクライアントを異なる環境に対して実行できます。
- 送信時に
timeout=30を使用する。 送信は高速です。送信がハングすることはネットワークまたは認証の問題を示しており、ワーカープロセスを無期限にブロックするのではなく、早期に発見したいところです。 - パース前に
raise_for_status()を呼ぶ。 4xx レスポンスボディは通常、ジョブではなく JSON エラーオブジェクトです。先に例外を発生させることで正常パスをクリーンに保ち、呼び出し元が失敗を明示的に処理できるようにします。 - 送信とポーリングを分離する。
submit_jobは 1 つのことだけを行います。次の章のポーリングループは、返された辞書を受け取り、待機を担当します。
サービスへの移植
実際のサービスでは、失敗がステータスコードとレスポンスボディを伴う型付き例外として現れるように呼び出しをラップしてください。本番のデバッグでは生のレスポンスボディが必要になります。リクエストボディを返されたジョブ識別子と一緒に記録してください。同僚がなぜあるクリップがおかしく見えるのかと尋ねたとき、そのログ行が調査のすべてになります。
フィールド名は curl の例とまったく同じです。一方を読めれば他方も読めます。まさにそれが、curl から始める価値が 5 分ある理由です。
API を叩き続けずに結果をポーリングする
これでジョブが存在し、識別子があります。素朴な方法、つまり 60 秒スリープして祈る方法には 2 つの失敗パターンがあります。ジョブが早く完了した場合に時間を無駄にし、ジョブに時間がかかる場合に完全に失敗します。
時計ではなく状態フィールドをポーリングする
ジョブの現在の状態を問い合わせ、それに基づいて分岐するループを書きます。
import time
import requests
def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
deadline = time.monotonic() + timeout_s
delay = 2.0
while time.monotonic() < deadline:
r = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
r.raise_for_status()
job = r.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"job failed: {job.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15.0) # 有界指数バックオフ
raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")
重要な特性
- 明示的な終端状態。
succeededとfailedだけがループを終了させます。それ以外の状態は一時的です。未知の状態を失敗として扱わないでください。新しい中間状態は時間とともに現れるため、ループはそれらを許容すべきです。 - 有界バックオフ。 小さく始め(数秒)、適度な係数で増やし、上限を約 10〜15 秒にします。これにより、短いジョブには機敏に対応しつつ、長いレンダリング中にエンドポイントを叩き続けることを避けられます。
- ハード期限。 常に合計待機時間を制限してください。それがないと、スタックしたジョブがワーカープロセスを永久に占有します。上限は、現実的な最長レンダリング時間に余裕を加えて選んでください。
- 失敗とタイムアウトを分ける。
failedジョブはユーザーに報告する価値のある生成エラーです。タイムアウトは再試行または個別調査に値するインフラの状態です。両者を混同すると、インシデントの振り返りが苦痛になります。
Web サービス内で
このループを、ユーザーが待機しているリクエストハンドラー内で実行しないでください。送信し、ジョブ識別子を保存し、すぐに返し、バックグラウンドワーカーにポーリングと結果の配信を行わせてください。webhook、キュー、またはフロントエンドが監視する行更新を通じて行います。上記のループはワーカーの関心事であり、HTTP の関心事ではありません。
よくある失敗のトラブルシューティング
ほとんどの失敗は 3 つのカテゴリに分類されます。まずカテゴリを特定し、次に具体的な原因を特定してください。
カテゴリ 1:入力検証の失敗
症状:送信時、レンダリング前に即座に 4xx が発生します。
次の順序で診断してください。
- 画像 URL はアクセス可能ですか? 同じネットワークから自分で取得してください。期限切れの署名付き URL とプライベートバケットが主な原因です。
- 形式はサポートされていますか? 議論するのではなく、標準形式に再エンコードしてください。
- 最初のフレームと最後のフレームは一致していますか? アスペクト比の不一致や極端に異なるシーンは、しばしば検証または品質の問題として現れます。
- 名前が間違ったフィールドを追加していませんか? 未知のキーは通常、無視されるのではなく拒否されます。モデルリファレンスと比較してください。
カテゴリ 2:パラメータの不一致
症状:ある設定のためリクエストが拒否される、または出力が設定を無視します。
- サポートされていない解像度または長さ。 ドキュメントの値のみを使用してください。任意の数字は拒否の一般的な原因です。
- モデル識別子の綴り間違い。 固定文字列です。コピーして、再入力しないでください。
- ネストの誤り。 トップレベルに属する設定を
input内に置いたり、その逆を行うと、紛らわしいエラーが発生します。第 3 章のリクエスト構造を参考にしてください。
カテゴリ 3:ポーリングのタイムアウトとジョブの失敗
症状:ジョブは受け入れられたが、終端の成功状態に到達しません。
- 正しい識別子をポーリングしていることを確認してください。 バッチスクリプトでのジョブ間のコピー&ペーストの誤りは驚くほど一般的です。
- 状態が実際に進んでいるか確認してください。 各ポーリングの状態をログに記録し、ジョブが進んでいるのか停滞しているのかを確認してください。
- API の失敗と生成の失敗を区別してください。 ポーリングリクエスト自体がエラーになる場合は、転送の問題です。ジョブが
failedを報告する場合は、エラーボディを読んでください。通常、問題を引き起こした入力が示されています。 - 最小の
curlスモークテストを再実行してください。 スモークテストも失敗する場合は、認証情報またはサービスの問題です。成功する場合は、リクエストボディの問題です。
汎用的なデバッグ姿勢
各ジョブについて 3 つのことを記録してください。正確なリクエストボディ、返されたジョブ識別子、エラーボディ付きの最終状態です。これら 3 つがあれば、ほとんどすべてのインシデントは半日ではなく 5 分の診断になります。疑問がある場合は、リクエストを第 3 章の最小形式に縮小し、エラーが発生するまでフィールドを 1 つずつ追加してください。最後に追加したフィールドが犯人です。