チュートリアル
HiAPI API で seedance-2.5-flash のテキストから動画生成を呼び出す方法(curl と Python)
開発者向けの実用的なリクエスト演習:エンドポイント、パラメータ、非同期タスク処理、そして実行可能な curl と Python のサンプル
このページの内容
seedance-2.5-flash/text-to-video でできること
seedance-2.5-flash/text-to-video は HiAPI API 上のテキストから動画を生成するエンドポイントです。生成したいシーンを説明するテキストプロンプトを送信すると、モデルが生成した動画を返します。約束はこれだけです。テキストを入力し、動画を出力します。
動画生成は一般的なチャット補完よりも時間がかかるため、このエンドポイントは非同期です。1 回の呼び出しで動画の準備ができるまでブロックして待つのではなく、生成タスクを作成し、タスクが終了状態になった後に結果を取得します。長時間実行されるメディア API を統合したことがあれば、この形には馴染みがあるでしょう。送信し、タスク識別子を保存し、結果を取得します。
したがって、あなた側の統合作業は 3 つに分かれます。正当な送信リクエストを構築すること、タスク ID を永続化すること、完了した動画を確実に取得することです。本チュートリアルでは、実行可能な curl と Python のコードでこの 3 つの手順を順に説明し、その後、パラメータの検証、ポーリングとコールバックのトレードオフ、そして初回の統合でほとんどの人が遭遇する失敗パターンを解説します。
プログラミングによってプロンプトを短い動画クリップに変換するパイプライン——コンテンツツール、プロトタイプバックエンド、社内生成サービス——を構築しているなら、このガイドはあなた向けです。同期レスポンスが必要な場合や、動画生成ではなく画像生成を探している場合は、別のエンドポイントの方が適しています。これがあなたのユースケースに合うなら、前提条件を引き続きお読みください。
前提条件と API Key の取得
最初のリクエストを送信する前に、3 つの点を確認してください。
HiAPI アカウントと API Key
このエンドポイントへのすべてのリクエストは、あなたの HiAPI アカウントに紐づく API Key で認証されます。アカウントのコントロールパネルで Key を作成し、ソースコード管理にコミットしないようにしてください。以下の例では環境変数から読み取るため、キーをインラインで編集することなく、ターミナルやスクリプトに直接貼り付けることができます。
export HIAPI_API_KEY="your_api_key_here"
HTTPS リクエストを送信できるクライアント
curl のパートでは curl が必要です。macOS とほとんどの Linux ディストリビューションには標準で付属しています。Python のパートでは Python 3 と requests ライブラリが必要です(pip install requests)。ベンダー専用の SDK は不要です。このエンドポイントは JSON リクエストボディ付きの通常の HTTPS であるため、Node の fetch から Python の httpx まで、あらゆる HTTP クライアントが使用できます。
リクエスト間で状態を保存する手段
生成は非同期であるため、送信呼び出しが返すタスク識別子を保存する場所が必要です。データベースの行、ジョブキュー、テスト中の JSON ファイルなどです。ポーリングの代わりにコールバックを使う予定なら、HiAPI からアクセス可能な HTTPS エンドポイントも必要です。
Key と使用可能なクライアントが揃えば、リクエストを送信できます。
curl で最初に動作するリクエストを送信する
送信呼び出しは JSON リクエストボディ付きの POST です。正確なエンドポイントパスと認証ヘッダー名はモデルページに記載されています。これらの値はそのまま使用し、他の API から推測しないでください。呼び出しの構造は次のとおりです。
curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "日の出の霧のかかった松林の上をゆっくりと飛行する空撮、柔らかな光、シネマティック"
}'
各部分についての補足です。
- メソッドとパス。
POSTは新しい生成タスクを作成します。パスはモデルを識別します。自分の設定にコピーする前にモデルページで確認してください。 - リクエストヘッダー。
Authorizationヘッダーに Key を設定し、Content-Type: application/jsonでサーバーにリクエストボディの解析方法を伝えます。 - リクエストボディ。少なくとも
prompt文字列を送信する必要があります。プロンプトは創造的な入力であり、モデルが描画するすべてはそこから生まれます。そのため、被写体、動き、照明、カメラの挙動を明確に指定してください。
リクエストが受け入れられると、レスポンスにはタスクオブジェクトが含まれます。動画 URL はすぐには得られません。レスポンスからタスク識別子を抽出して保存してください。正確なフィールド名はモデルページに記載されたレスポンススキーマの一部です。それらを唯一の信頼できる情報源として扱い、実際のレスポンスを確認する前に推測をクライアントにハードコードしないでください。
まず curl で生のレスポンスを確認し、その形を理解してから同じ呼び出しをコードに移してください。
パラメータの選択:プロンプト、解像度、長さ
厳密に必須なのは prompt だけですが、出力結果とリクエストコストを左右するいくつかのオプションパラメータがあります。盲目的にデフォルト値を受け入れるのではなく、意図を持って設定してください。
プロンプト
プロンプトは最も影響の大きいパラメータです。カメラマンへの指示のように書いてください。被写体、動作、環境、照明、カメラのスタイルです。「夜のネオンに照らされた東京の通りを縫うように走る自転車、ハンドヘルドカメラ、浅い被写界深度」は「街」よりもはるかに多くの情報をモデルに与えます。プロンプトはモデルページに記載された長さ制限内に収めてください。
解像度
解像度が高いほどディテールが増え、出力ファイルも大きくなり、生成時間も長くなる可能性があります。動画生成は通常、出力の長さに応じて課金されますが、現在の課金基準や解像度の段階については、独自に仮定せず、価格パネルとモデルドキュメントで確認してください。納品目標を満たす最小の解像度を選択してください。後でアップスケールする方が、すべてを最高品質で生成するよりも一般的に安価です。
長さ
長さはモデルが何秒の動画を生成するかを制御し、通常はレイテンシとコストの両方に影響します。短いクリップは反復作業に適しています。短い長さで動きが正しく見えるまでプロンプトを磨き、その後、最終的な長さで再生成してください。
送信前の検証
値を本番コードに接続する前に、モデルページで各パラメータの許容範囲を確認してください。許容される長さ、サポートされる解像度、および任意の列挙値です。次に、クライアント側で検証してください。範囲外の長さや不明な解像度の値を、リクエストがプロセスを離れる前に拒否します。これにより、サーバー側の検証エラーの一種を、自分のログに即座に記録される低コストの失敗に変換できます。
同じルールがパラメータ名にも当てはまります。ドキュメントからコピーしてください。長さのフィールドに余分なアンダースコアが 1 つあるようなタイプミスは、多くの場合、拒否されるか、あるいは黙って無視されます。そして黙って無視される方が発見が難しいバグです。
Python で同じリクエストを送信する
以下は Python での同等の送信コードです。環境変数から Key を読み取り、JSON リクエストボディを送信し、ステータスコードをチェックし、ドキュメントに記載されたレスポンスフィールドからタスク識別子を返します。
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_video(prompt: str, **options) -> str:
payload = {
"prompt": prompt,
**options, # 例: resolution="720p", duration=5
}
response = requests.post(
f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
body = response.json()
task_id = body["id"] # フィールド名はモデルページで確認してください
return task_id
if __name__ == "__main__":
task_id = submit_video(
"日の出の霧のかかった松林の上をゆっくりと飛行する空撮、柔らかな光、シネマティック"
)
print("submitted task:", task_id)
このコードにはいくつか意図的な選択があります。
- タイムアウト。送信呼び出しは素早く返るべきですが、明示的な
timeoutはハングしたソケットがワーカープロセスをブロックするのを防ぎます。 raise_for_status()。エラーレスポンスボディを成功レスポンスとして解析するのではなく、HTTP エラーで直ちに失敗します。- キーワードオプション。
**optionsを渡すことで呼び出し側が読みやすく保たれ、モデルページで正確な名前を確認した後にresolutionやdurationを追加するのが非常に簡単になります。 - ID の返却。関数の責務は送信時に終わります。その ID は何らかの永続ストレージに保存してください。次のセクションで結果の取得に使用します。
実際のパイプラインでは、submit_video をキュー駆動ワークフローの 1 ステップとして扱ってください。キューに入れ、返されたタスク ID をジョブレコードと一緒に保存し、結果の取得は独立したワーカーに任せます。
非同期結果の処理:ポーリングとコールバック
送信後、タスク ID はありますが、動画はまだありません。このギャップを埋める方法は 2 つあります。
ポーリング
一定間隔でタスクステータスエンドポイントをポーリングし、タスクが終了状態になるまで待ち、完了したレスポンスから出力 URL を取得します。
import time
import requests
def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
response = requests.get(
f"{BASE_URL}/v1/tasks/{task_id}", # パスはモデルページで確認してください
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
task = response.json()
state = task["status"]
if state == "completed":
return task
if state == "failed":
raise RuntimeError(task.get("error", "generation failed"))
time.sleep(delay)
delay = min(delay * 1.5, 15) # 緩やかなバックオフ、上限あり
raise TimeoutError(f"task {task_id} did not finish in time")
ポーリングに関する実用的な 3 つのルール:
- バックオフ。短い遅延から始めて徐々に増やします。高頻度の継続的なポーリングはクォータを浪費し負荷を増やすだけで、何の利点もありません。
- 上限を設ける。すべてのポーリングループには締め切りが必要です。動画生成には時間がかかることがありますが、無制限のループは最終的に、スタックしたタスクによってワーカープロセスが永久にハングする原因になります。
- 状態を区別する。
failedを明示的に処理し、悪いプロンプトが黙ってタイムアウトとして扱われないようにします。
コールバック
HTTPS コールバック URL を登録すると、HiAPI がタスク完了時に通知できるため、ポーリングを完全に回避できます。コールバックを安全で信頼できるものにする 2 つのルール:
- 検証してから信頼する。プラットフォームのドキュメントに記載された仕組みで署名や送信元を検証するまで、コールバックを未認証の入力として扱います。
- 冪等性を保つ。コールバックは複数回配信される可能性があります。ハンドラーのキーをタスク ID にし、重複配信の処理を何もしない操作にします。結果は 1 回だけ保存し、重複配信には確認応答を返します。
どちらの方法を選んでも、結果の取得は冪等です。完了したタスクの結果 URL を取得すると同じ動画が返るはずなので、ネットワークエラー後の再試行は安全です。
よくあるエラーとその修正方法
ほとんどの失敗は少数のカテゴリに集約されます。記録されていない動作を仮定する前に、このチェックリストを順に確認してください。
認証の失敗
401 または 403 は、ほぼ常に Key の欠落、形式の誤り、または期限切れを意味します。Authorization ヘッダーが存在するか、認証スキームがドキュメントと完全に一致しているか、そして環境変数に実際に Key が含まれているかを確認してください。空文字列は、紛らわしいものの認証に関連する失敗を引き起こします。
検証の拒否
検証メッセージ付きの 4xx は、サーバーがパラメータを拒否したことを意味します。モデルページで許容範囲を読み直し、パラメータ名を 1 文字ずつ確認してください。長さや解像度が範囲外の場合、修正方法は前述のクライアント側検証です。サーバーへの往復ではなく、自分のコード内で素早く失敗させます。
タスクが終了状態にならない
ポーリングで completed も failed も確認できない場合、タスクがまだ実行中であるか、ポーリングループが誤ったタスク ID を照会している可能性があります。送信した ID とポーリングした ID を記録して比較してください。ループは締め切りを強制する必要もあります。締め切りが発動したら、盲目的に再試行するのではなく、タスク ID を明らかにしてください。
コールバック後に結果が届かない
コールバックに依存している場合、エンドポイントが HTTPS で公開アクセス可能か、重い処理をインラインで実行するのではなく素早く成功ステータスを返しているか、重複配信が冪等に処理されているかを確認してください。コールバックハンドラーが同じタスクの 2 回目の配信でエラーを出すと、結果が失われたように見えます。
同じジョブを重複送信する
ワーカーがタイムアウト後に送信呼び出しを再試行すると、重複タスクが作成される可能性があります。エンドポイントを呼び出す前にクライアント側のリクエストキーまたはジョブ ID を自分のデータベースに記録し、再試行前にそれを確認することで、送信を自分の側で冪等に保つことができます。
一般的な原則:失敗が発生したら、コードを変更する前にエラーレスポンスボディとモデルドキュメントを読んでください。値やフィールドがドキュメント化されていない場合は、それが存在すると仮定するのを避け、モデルページで確認し、それに応じてリクエストを調整してください。