チュートリアル
HiAPI API で seedance-2.5-flash の参照動画生成を呼び出す方法(curl + Python)
動作するリクエスト、実行可能な Python スクリプト、そして非同期タスクのポーリング処理方法
このページの内容
参照動画生成が実際に意味するもの
参照動画生成は、モデルに2つのものを同時に与える生成モードです。運動とシーンを記述するテキストプロンプト、そして画面内容を固定する1つ以上の参照素材です。プロンプトが意図(「ゆっくりと寄り、キャラクターが振り向いて微笑む」)を担い、参照素材がアイデンティティと外観(キャラクター、製品、ビジュアルスタイル)を担います。
このワークフローのモデルエンドポイントは seedance-2.5-flash/reference-to-video で、HiAPI の統合 API を通じて提供されます。model、prompt、参照素材を1つのリクエストボディにまとめて送信します。あなたが編成する必要のある個別のアップロード手順も、維持すべき素材ごとのレジストリもありません。
実用上の帰結はこうです。これは長時間実行の操作です。短い動画のレンダリング時間はテキスト補完よりはるかに長いため、API はこの呼び出しを非同期タスクとして扱います。あなたのリクエストがタスクを作成し、2回目の呼び出しがその結果を取得します。この「まず送信、その後ポーリング」という形が設計上最も重要な点であり、本チュートリアルの残りの部分が構築していく方向性です。
以下のすべては HiAPI インターフェース内に収まります。1つのベース URL、1つの認証ヘッダー、1つのエンドポイントファミリーです。
最初のリクエストを送信する前に
最初の呼び出しの前に3つのものを用意する必要があります。
1. API キー
HiAPI コンソールでキーを作成し、ソースコード管理から遠ざけてください。以下の例では環境変数から読み取ります。
export HIAPI_API_KEY="your_key_here"
現在のキー形式やリクエストヘッダーの規約が不明な場合は、コンソールのプラットフォーム API ドキュメントを確認してください。推測したり、共有する可能性のあるスクリプトにキーをハードコードしたりしないでください。
2. ベース URL と認証ヘッダー
すべての呼び出しは HiAPI のベース URL に送信され、Authorization ヘッダーにあなたのキーを乗せます。これを一度変数に設定すれば、すべてのリクエストが一貫します。
export HIAPI_BASE_URL="https://api.hiapi.ai"
アカウントのドキュメントに記載されたとおりにベース URL を使用してください。末尾スラッシュの不一致は、紛らわしい 404 のよくある原因です。
3. モデルエンドポイント
ターゲットは seedance-2.5-flash/reference-to-video です。これをパスに埋め込むのではなく、リクエストボディ内でこの識別子を使って参照してください。そうすれば、後でモデルを切り替えるのは1行の変更で済みます。
また、参照素材を URL 経由でアクセス可能にする必要があります(またはエンドポイントのドキュメントで指定された任意の素材形式を使用してください)。開始する前にそれらをホストし、公開アクセス可能にしてください。壊れた参照 URL は、タスクの送信には成功するものの生成中に失敗する最も一般的な原因です。
これら3つが設定できたら、リクエストボディを構築できます。
参照素材を使ったリクエストボディの構築
リクエストボディには概念的には3つの部分があります。どのモデルを使うか、何を望むか、何を参照するかです。
モデル
model を seedance-2.5-flash/reference-to-video に設定します。通常の文字列フィールドとして扱ってください。URL エンコードもパスセグメントも不要です。
プロンプト
プロンプトは願望リストではなく、ショットの説明として書いてください。被写体、動作、カメラの挙動、テンポを記述します。「赤いジャケットを着た人物がカメラに向かって歩いてくる、ミディアムショット、ゆっくりと寄る、柔らかな日光」は「人物のいい感じの動画」よりもはるかに多くの情報をモデルに与えます。プロンプトは提供する参照素材と一致させてください。2つの参照素材が異なるキャラクターを示している場合は、どちらが主導的かを明示してください。
参照素材
参照素材こそが、このエンドポイントと通常のテキストからの動画生成呼び出しとの違いです。フレーム間で一貫させるべき内容を定義する1つ以上の素材を渡します。反復を節約できる実用的なルールは次のとおりです。
- アイデンティティを確定できる最小数の参照素材を使う。強力な参照1つは、平凡な参照4つにたいてい勝ります。
- 参照素材同士を一致させる。矛盾するアングルやスタイルは出力のドリフトを引き起こします。
- クリーンで照明の良いソース素材を優先する。切り抜かれたり、ぼやけたり、強いフィルターがかかった参照素材は、その欠陥を伝播させます。
- 送信前に各 URL が解決可能か検証する——まず自分で一度取得してみてください。
参照素材がリクエストボディ内で具体的にどのようにキー付けされるか(配列フィールド名、オブジェクト構造、対応素材タイプ)は、HiAPI ドキュメントのエンドポイントのリクエストスキーマから取得すべきです。記憶に頼らず、そのスキーマに従ってリクエストボディを構築してください。スキーマはフィールド名の権威ある情報源であり、キーの不一致はサイレントな失敗を引き起こします。
リクエストがネットワークに到達する前に、ローカルで JSON を検証してください(python -m json.tool body.json)。不正な形式のリクエストボディは最も捕捉しやすいエラーであり、スタックトレースからデバッグするのが最も厄介なエラーでもあります。
動作する curl リクエスト
次のコマンドは「まず送信、その後ポーリング」パターンに従います。タスクを作成し、ポーリングに使用するタスク識別子を含む JSON レスポンスを出力します。
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/reference-to-video",
"prompt": "赤いジャケットを着た人物がカメラに向かって歩いてくる、ミディアムショット、ゆっくりと寄る、柔らかな日光",
"references": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png"
]
}'
参照 URL を自分でホストする素材に置き換え、本番環境でこのコードに依存する前に、HiAPI ドキュメントのモデルページと照らし合わせてエンドポイントパスとフィールド名を確認してください。スキーマの詳細が権威であり、このスニペットは説明用です。
レスポンスで注目すべき内容:
- id(または task/job 識別子)——これを捕捉してください。各ポーリングで必要になります。
- タスクが受け付けられたことを示す status フィールド。
- 無視または拒否された素材に関する警告があれば、その内容。
読みやすくするために整形して出力します。
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json | python -m json.tool
リクエストボディを body.json に保存することは、この小さな追加手間だけの価値があります。クリーンにバージョン管理でき、読みやすく差分を確認でき、シェルのクォートミスをデバッグ対象から除外できます。
Python での同じ呼び出し
以下は Python での同等の呼び出しで、環境変数を設定すればそのまま実行できるように書かれています。標準ライブラリのみを使用するため、何もインストールする必要はありません。
import json
import os
import urllib.request
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_reference_video(prompt, references):
body = {
"model": "seedance-2.5-flash/reference-to-video",
"prompt": prompt,
"references": references,
}
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
payload = json.loads(resp.read().decode("utf-8"))
return payload
if __name__ == "__main__":
result = submit_reference_video(
prompt="赤いジャケットを着た人物がカメラに向かって歩いてくる、ミディアムショット、ゆっくりと寄る、柔らかな日光",
references=[
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png",
],
)
print(json.dumps(result, indent=2))
job_id = result.get("id")
print("job id:", job_id)
2つの細部は見た目以上に重要です。第一に、timeout=60——送信呼び出しは素早く返るべきですが、接続のハングは素早い失敗よりも悪いです。第二に、result.get("id") はレスポンス構造が予想外の場合を処理し、正常なパスで KeyError を発生させません。
requests や httpx を好む場合、変換は簡単です。同じ URL、同じヘッダー、同じ JSON ボディです。リクエストボディの構築こそがコピーする価値のある部分であり、HTTP クライアントは差し替え可能です。
完了まで非同期タスクをポーリングする
動画生成は待つことができるリクエストではありません。送信して識別子を受け取り、タスクが終端状態に達するまで定期的にステータスをチェックします。これを安全にする2つの特性があります。ポーリングのオーバーヘッドは低く、送信呼び出しがすでに高コストな処理を完了していることです。
ループ
import time
def wait_for_video(job_id, timeout_s=600, interval_s=5):
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
job = json.loads(resp.read().decode("utf-8"))
status = job.get("status")
if status in ("succeeded", "completed"):
return job
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")
よりタイトなループは速くなりません。レート制限を消費するだけです。動画タスクでは、5秒間隔が妥当なデフォルトです。
設計上の注意
- 常に締め切りを設定する。終了しないタスクがリクエストスレッドを永遠にハングさせてはいけません。
- 不明なステータスは成功ではなく「待機継続」として扱う。明示的な成功だけが成功です。
- Web リクエストハンドラー内でポーリングしない。ハンドラーで送信し、タスク id をクライアントに返し、バックグラウンドワーカーにポーリングと結果の永続化を任せます。
- タスク id とステータス遷移を永続化することで、中断されたプロセスが再送信してレンダリング費用を二重に支払うのではなく、復旧できます。
この「まず送信、その後ポーリング」の分割こそが、遅い動画パイプラインを高速な API の背後に置ける理由です。
よくあるエラーとその修正方法
最初の1時間のほぼすべての失敗は4つのカテゴリのいずれかに分類されます。この順序で確認してください。
1. 認証
症状:タスクが作成される前の未認証または禁止のレスポンス。
確認事項:スクリプトを実行するシェルまたはプロセスで HIAPI_API_KEY が実際に設定されているか?ヘッダーは正確に Authorization: Bearer <key> か?インポート時にキーを読み込んでいるが、スクリプトは後で使うことを想定していないか?解析されたキーの先頭数文字を出力し(キー全体は決して出力しない)、空文字列でないことを確認してください。
2. エンドポイントパス
症状:見つからない(通常は即座に発生)。
確認事項:ベース URL とパスの間にスラッシュがちょうど1つ——これが Python の例で .rstrip("/") を呼び出している理由です。ドキュメントのモデルページと照らし合わせて生成パスとポーリングパスを確認してください。タスク id セグメントが欠けたポーリング URL は毎回 404 になります。サーバーが想定しない末尾スラッシュも同じ症状を引き起こします。
3. 不正な形式のリクエストボディ
症状:検証エラー、またはタスクが受け付けられた直後の失敗。
確認事項:json.dumps(body) を実行して確認してください。model は seedance-2.5-flash/reference-to-video と完全に一致しているか?参照フィールドは配列で、各エントリはブラウザで解決可能な文字列 URL か?Content-Type: application/json を送信しているか?ネットワークに到達する前に構文エラーを排除するため、リクエストボディを python -m json.tool に通してください。
4. タスクステータス
症状:送信呼び出しは成功するが、タスクが失敗するか完了しない。
確認事項:ステータスレスポンスのエラーフィールドを読んでください。通常は原因を示しており、最も多いのは到達不可能または非対応の参照素材です。タスクが単に停止している場合は、正しい id をポーリングしているか、ループのステータス比較が API が実際に返す終端状態をカバーしているかを確認してください。すべてのステータス遷移を記録してください。失敗前の最後のステータスが診断の根拠になります。
4カテゴリすべてのトラブルシューティングを短縮するルールが1つあります。呼び出しごとにリクエスト id とタスク id を記録してください。障害が発生したとき、id があれば曖昧なエラー報告を具体的な調査に変えられます。
次のステップ
これで完全な形を把握しました。プロンプトと参照素材でリクエストボディを構築し、送信し、終端までポーリングし、4つの一般的な失敗を処理します。ここから先、自然な次のステップは API レベルではなくエンジニアリングレベルです。
- 一時的なネットワークエラーに対応するため、バックオフ付きリトライで送信をラップする。ただし、すでに id を持つタスクを決して再試行しないでください。それは重複レンダリングです。
- ポーリングをワーカープロセスまたはキューに移動することで、HTTP レイヤーを応答性に保ち、タスクがプロセスの再起動を生き延びられるようにします。
- タスク id を自身のリクエストメタデータ(プロンプト、参照素材、リクエスト元ユーザー)と一緒に保存することで、数か月後も結果を追跡可能にします。
- 検証後にのみ参照素材を通過させる——ユーザーが各 URL を提供したときに取得し、その後でタスクを消費します。
権威あるリクエストスキーマ、対応素材形式、現在のエンドポイント詳細については、HiAPI の seedance-2.5-flash 参照動画生成モデルページを参照してください。そのスキーマに基づいて構築し、「まず送信、その後ポーリング」の分割を維持すれば、統合は平凡なまま保たれます。それこそが動画パイプラインに望むものです。