チュートリアル
HiAPI API で wan2.7-video テキストtoビデオを呼び出す方法:curl と Python
このページの内容
このチュートリアルで構築するもの
本ガイドを読み終えると、動作する小さなパイプラインが手に入ります。HiAPI API を通じて wan2.7-video/text-to-video にテキストtoビデオのタスクを投入し、まず curl で一度、次に Python で一度実行し、その後ビデオの生成完了を待つ、というものです。
この 2 つの呼び出しは意図的に等価に保っています。curl 版はリファレンス実装であり、ターミナルに貼り付けて認証情報とリクエストボディが正しいかを確認できます。Python 版は同じリクエストを関数としてカプセル化し、スクリプトやサービスに組み込みやすい形にしたもので、ポーリング、エラーハンドリング、妥当なデフォルト値を含みます。
ビデオ生成はチャット補完よりはるかに遅いため、全体の流れは非同期です。まずタスクを投入して識別子を受け取り、タスクが終態を報告するまでポーリングします。以下はこのライフサイクルに沿って構成されているため、後でイメージtoビデオや同じエンドポイントファミリーの別のビデオモデルに切り替えても、全体の構造はそのまま適用できます。
最初のリクエストを送る前に
初回の呼び出しを成功させるには、まず 3 つの条件を満たす必要があります。
認証情報
HiAPI API キーが必要で、Authorization ヘッダーで bearer token として送信します。ソースコードに書き込まず、環境変数に置いてください:
export HIAPI_API_KEY="your-key-here"
既知のモデル識別子
モデル識別子は正確な文字列です。本チュートリアルでは wan2.7-video/text-to-video という値で、タスクのサフィックスを含みます。wan2.7-video や wan2.7/text-to-video のような近似表記は拒否されるため、モデルリストから識別子をコピーし、記憶に頼って手書きしないでください。
評価可能なプロンプト
ビデオ生成をやみくもに反復するのはコストが高くつきます。あらかじめ具体的なプロンプト(主体、動作、カメラの動き、ライティング、スタイル)を書いておけば、結果が返ってきたときに調整すべきが設定なのか文言なのかを判断できます。
さらに HTTP クライアントと JSON を読み取る手段が必要です。シェル側では curl と jq、スクリプト側では Python と requests を使います。
リクエストボディの構造を読み解く
テキストtoビデオのリクエストは 1 つの JSON オブジェクトで、フィールドは 3 つのグループに分けられます。
識別
model——正確なモデル識別子、すなわちwan2.7-video/text-to-video。
内容
prompt——欲しいビデオを説明するテキスト。これが主要な役割を果たすフィールドです。形容詞を並べるのではなく、動き、構図、スタイルを具体的に述べましょう。negative_prompt——任意。表示されるべきでない内容を記述します。よくある瑕疵の抑制に役立ちますが、良いプロンプトの代わりにはなりません。
生成設定
duration——出力クリップの尺。resolution——出力のサイズ/解像度の档位。seed——任意。安定した起点のもとで 2 つのプロンプトや 2 回の設定変更を比較したいときに固定します。
最小のリクエストボディには model と prompt だけで十分で、残りのフィールドにはプラットフォームがデフォルト値を適用します。ただしデフォルト値はあなたが選択したものではありません。本番環境ではなぜ明示的に設定すべきかについては、後述の尺と解像度のセクションを参照してください。
リクエストボディはフラットで浅い構造に保ってください。本当に子オブジェクトに属するフィールドだけをネストすれば、リクエストが読みやすくなり、スキーマエラーも見つけやすくなります。
curl でタスクを投入する
以下は完全な投入例です。このエンドポイントは JSON を受け取り、ビデオそのものではなくタスクハンドルを返します。
curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/text-to-video",
"prompt": "夜の雨に濡れたネオンの路地をゆっくりと進むトラッキングショット、地面には光を反射する水たまり、浅い被写界深度、シネマティックなカラーグレーディング",
"duration": 5,
"resolution": "720p"
}'
投入に成功すると、タスクまたはジョブの識別子とステータスを含むオブジェクトが返ります。構造はおおよそ次のとおりです:
{
"id": "job_abc123",
"status": "queued",
"model": "wan2.7-video/text-to-video"
}
注意すべき点が 2 つあります。第一に、status は succeeded ではありません。この時点ではまだ何もレンダリングされていません。第二に、レスポンスにビデオ URL は含まれていません。この URL はタスクが終態に達した後にのみ現れます。
識別子をポーリング手順のためにシェルセッションに残しておきたい場合:
JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | jq -r '.id')
echo "$JOB_ID"
リクエストボディを payload.json に移すとコマンドが短く保て、実行間でプロンプトを調整しやすくなります。
Python でタスクを投入する
Python 版は同じリクエストをより扱いやすくしたものです。curl ではヘッダーや JSON キーだったものが、ここではキーワード引数になります。
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "wan2.7-video/text-to-video",
"prompt": (
"夜の雨に濡れたネオンの路地をゆっくりと進むトラッキングショット、"
"地面には光を反射する水たまり、浅い被写界深度、シネマティックなカラーグレーディング"
),
"duration": 5,
"resolution": "720p",
}
resp = requests.post(
f"{BASE_URL}/v1/video/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])
シェル版との対応関係は一対一です:
-H "Authorization: ..."→HEADERS辞書。-d '<json>'→json=payload。文字列ではなく辞書を渡すことでシリアライズはrequestsが担うため、不正な形式の JSON を誤って送信することはありません。jqで抽出した.id→job["id"]。
Python 特有の習慣として、今のうちに身につけておくべきものが 2 つあります。投入呼び出しには必ず timeout を設定してください。このリクエストは小さく、すぐ返るはずなので、長時間ハングするのはレンダリングではなく接続の問題です。また、レスポンスボディを読む前に raise_for_status() を呼んでください。そうすれば HTTP 層の失敗は明確な traceback を出し、job["id"] で不可解な KeyError を投げることはありません。
非同期タスクとポーリングの処理
ポーリングは、多くの統合が堅牢にも不安定にもなる箇所です。タスクにはライフサイクルがあり、通常はキュー待ち、処理中、そして成功または失敗の終態へと進みます。あなたのループはこの 3 つのケースを扱わなければなりません。
def wait_for_job(job_id, interval=5, max_attempts=120):
url = f"{BASE_URL}/v1/video/generations/{job_id}"
for attempt in range(max_attempts):
r = requests.get(url, headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status in ("failed", "cancelled"):
raise RuntimeError(f"Job {job_id} ended as {status}: {data.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} still not finished after {max_attempts} polls")
このループには、見た目以上に重要な設計上のポイントがいくつかあります:
終態を明示的にチェックする。succeeded 以外のすべての状態を「待機継続」と扱うと、失敗したタスクがポーリング予算を静かに使い果たしてしまいます。失敗状態を照合して例外を投げるべきです。
ポーリング間隔を意識的に選ぶ。ビデオのレンダリングには数十秒から数分かかります。200 ミリ秒ごとのポーリングは負荷を増やすだけで、新しい情報は何も得られません。5 秒程度から始め、タスクが長時間かかることが多いなら試行回数を増やすのではなく間隔を広げてください。
ループには必ず上限を設ける。max_attempts の上限は、無限ハングを診断可能な TimeoutError に変えてくれます。あわせてタスク ID も記録してください。調査時に必要になる値です。
レート制限を守る。バッチで投入する場合、すべてのポーリングリクエストを同時に発行しないでください。一定間隔で動く共有ポーラーや単純なクライアント側スロットリングを使えば、制限内に収まります。
成功時、レスポンスには完了したアセットの場所が含まれます。すぐにダウンロードし、タスクレコードを永続ストレージとして扱わないでください。
尺と解像度の選択
この 2 つの設定は他のどのパラメータよりも出力に影響し、どちらもタスクの実行時間とコストに影響します。課金は出力秒数で計算され、解像度は 1 秒あたりの作業量を決めるため、どちらもデフォルトのままにしておくフィールドではなく、ユースケースに応じた意図的な選択として扱ってください。
尺
長いクリップは動作が展開する余地を与えますが、追加の 1 秒ごとにレンダリングとコストが増え、長時間の生成は一貫性の問題も起きやすくなります。実用的な指針:
- 短い(数秒)——ソーシャル用ループ、製品のキービジュアル、B-roll。反復コストが最も低く、判断も最も容易です。
- 中程度——物語のビート、確立ショット。
- 長い——物語が本当に必要とするときだけ使います。長いビデオが必要なら、短いクリップを複数生成して編集でつなげることを検討してください。多くの場合、一度の長いレンダリングより安価で、より多くの制御が得られます。
プロンプトを反復するときは、生成モデルが許可する最短のクリップを生成してください。この長さで構図と動きを判断し、満足してから尺を延ばしましょう。
解像度
高い解像度はフレームあたりのピクセル数が増え、レンダリング時間が長くなり、コストも高くなります。しかし小さい画面では、思ったより重要ではありません。1080p のマスターはクライアントへの納品に適し、720p(あるいはそれ以下)のドラフトはプロンプトが有効かを判断するのに適しています。
効率的なパターンは 2 段階のワークフローです。低解像度でプロンプトと尺を確定し、その後、納品解像度で最終タスクを再実行します。最高設定で反復しないでください。予算の大部分を捨てる素材に費やすことになります。
よくあるエラーのトラブルシューティング
失敗のほとんどはモデル自体ではなく、リクエストの組み立て方に起因します。モデルの能力について結論を出す前に、次のカテゴリを順に確認してください。
401 / 403——認証情報の問題
キーがプロセスから実際に見える環境に設定されているか(あるシェルで export したキーは systemd サービスからは見えません)、ヘッダーが Authorization: Bearer <key> になっているか、変数に末尾の空白がないかを確認してください。デバッグ時はキーの先頭数文字だけを出力し、完全なキーは決して出力しないでください。
404——パスまたはモデルの誤り
エンドポイントパスとモデル識別子は別物で、どちらも正確でなければなりません。POST する URL を確認し、wan2.7-video/text-to-video がモデルリストから文字単位でコピーされているか確認してください。有効なキーでも誤ったモデル文字列では not-found 系のエラーが返ります。
400——リクエストボディの形式エラー
これが最も多いカテゴリです。よくある原因は、duration のような数値フィールドが文字列 "5" として送信されている、プロンプトが文字列ではなくリストとして送信されている、あるいはリクエストボディが誤って二重エンコードされている、などです。最も速い切り分けは、まったく同じ curl コマンドを再送することです。シェル呼び出しが成功して Python 呼び出しが失敗するなら、問題はリクエスト自体ではなくスクリプトの辞書構築方法にあります。
422 / バリデーションエラー
構文は有効だが意味に問題があります。尺がサポート範囲を超えている、未知の解像度档位、必須フィールドの欠落などです。エラーメッセージを読んでください。通常は問題のあるフィールドを指し示しています。
投入後のタスク失敗
投入呼び出しは成功したものの、レンダリングが成功しなかったケースです。コンテンツポリシーによる拒否や一時的なレンダリング失敗が考えられます。タスク ID とエラーペイロードを記録し、一時的な問題なら同じペイロードでの再投入が妥当な最初の一手です。同じプロンプトで繰り返し起きるなら、同じリクエストを再試行し続けるのではなく、プロンプトの文言や生成設定を変えてください。
ポーリングが終わらない
タスクが同種のタスクよりはるかに長く処理中のままなら、ポーリングを停止し、タスク ID を記録して、失敗タスクとして扱ってください。ロングテールは十分まれなので、明示的なエラーメッセージを伴う上限付きタイムアウトの方が、オープンなループより優れています。
新しい問題に遭遇するたびに、まず curl のリファレンス実装から始めてください。自分のコードを問題から切り離し、問題がリクエスト側にあるのかクライアント側にあるのかを切り分けられます。