チュートリアル
HiAPI API で pixverse-v6-max/text-to-video を使う方法:curl、Python、実行可能なリクエスト例
このページの内容
このエンドポイントが行うこと、そして使うべき場面
pixverse-v6-max/text-to-video は HiAPI 上のテキストtoビデオエンドポイントです。希望するシーンを記述したテキストプロンプトを送信すると、レンダリング済みの動画が返ります。動画生成には時間がかかるため、このエンドポイントは非同期です。最初のリクエストは動画を直接返すのではなく、タスク識別子を返し、それを使って進捗を問い合わせ最終結果を取得します。
この「リクエスト→確認→ポーリング」という形が、本チュートリアル全体の中心となるメンタルモデルです。内部の流れは常に同じです:
- プロンプトとパラメータを指定して生成タスクを送信する。
- 直ちにタスク識別子を受け取る。
- タスクが完了(または失敗)を報告するまでそのタスクをポーリングする。
- 結果動画の URL をダウンロードまたは埋め込む。
このエンドポイントが適する場面
手元に説明文しかなく、素材がない場合は pixverse-v6-max/text-to-video を選びます。たとえば、テキストのブリーフから製品ティーザーを作る、アプリ用の背景クリップを生成する、絵コンテのプレビューを作る、といった用途です。既に画像があり、それを動かしたい場合は画像toビデオのワークフローであり、このエンドポイントではありません。モデルと対話しながらプロンプトを繰り返し改善したい場合は別のインタラクション方式になります。このエンドポイントは、テキストから動画への直接的な単発生成の経路です。
生成が非同期であるため、キュー基盤のアーキテクチャにも適しています。Web バックエンドがユーザーリクエストを受け取りタスクを送信し、その後ワーカープロセスがポーリングして後で結果を届けます。呼び出しのどの段階でも、レンダリング完了までブロックされることはありません。
開始前の準備:認証とリクエストの基本
コードを書く前に、3 点を確認します。
1. API キー
HiAPI のすべてのリクエストは API キーで認証します。パスワードと同様に扱ってください。ソースリポジトリにコミットせず、環境変数から読み込み、漏洩したら直ちにローテーションします。以下の例は HIAPI_API_KEY から読み込むため、まずシェルでエクスポートします:
export HIAPI_API_KEY="your_key_here"
2. 正しいベース URL
すべてのリクエストは HiAPI API のベース URL にエンドポイントパスを付けて送信します。ブログ記事からホスト名をハードコードするのではなく、HiAPI アカウントに記載されたベース URL を使用してください。不明な場合はダッシュボードの API リファレンスを確認します。以下の例では $HIAPI_BASE_URL をその値のプレースホルダーとして使います。
3. JSON の約束事
送信もステータス問い合わせも HTTPS 上の JSON です:
- ボディ付きの各リクエストには
Content-Type: application/jsonを送信します。 - 各リクエスト(ステータス問い合わせを含む)には
Authorization: Bearer $HIAPI_API_KEYを送信します。 - エラー時も含めて JSON が返ると想定します。HTTP ステータスコードだけでなく、エラーレスポンスボディも読み取ってください。
簡単な健全性チェック
軽量なエンドポイント(models や account のルートなど)が利用できる場合は、動画エンドポイントに触れる前に一度呼び出してください。そこで 200 が返れば、キー、ベース URL、ヘッダー形式がすべて正しいことが証明され、以降のデバッグで 3 つの変数を排除できます。
実行可能な curl リクエスト
以下は完全な送信呼び出しです。エンドポイントパスは pixverse-v6-max/text-to-video で、ボディにプロンプトと生成パラメータを含めます。
curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "夜、雨に濡れたネオン路地をゆっくりとドリーインする映画的なショット",
"duration": 5,
"aspect_ratio": "16:9"
}'
フィールドごとの説明
prompt—— テキストによる説明。被写体、動き、カメラワーク、雰囲気を明確にします。出力品質に最も影響する要素です。duration—— リクエストするクリップの長さ。後述の「duration とアスペクト比パラメータ」を参照してください。aspect_ratio—— 出力の画面比率。たとえば16:9、9:16、1:1など。
何が返るか
送信が成功すると、タスク識別子を含む JSON オブジェクトが返ります。これはポーリングに使うハンドルです。具体的なフィールド名は API リファレンスに従ってください。本チュートリアルでは task_id と呼びます。これを保存しておきます:
TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"夜、雨に濡れたネオン路地をゆっくりとドリーインする映画的なショット","duration":5,"aspect_ratio":"16:9"}' \
| python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"
レスポンスに何が含まれないかに注目してください。動画です。生成はバックグラウンドで実行されます。送信レスポンスは結果ではなく受領書とみなしてください。
同じリクエストの Python 版
Python 版は curl 呼び出しに完全に対応しています。簡潔さのため requests を使いますが、httpx や urllib でも同様に動作します。要件は同じヘッダーと JSON ボディだけです。
import os
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 = {
"prompt": "夜、雨に濡れたネオン路地をゆっくりとドリーインする映画的なショット",
"duration": 5,
"aspect_ratio": "16:9",
}
resp = requests.post(
f"{BASE_URL}/pixverse-v6-max/text-to-video",
headers=headers,
json=payload,
timeout=30,
)
if resp.status_code >= 400:
# サーバー側のエラーレスポンスボディを出力する——通常は問題のあるフィールドを示す
raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")
data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)
そのまま参考にすべきポイント
json=payloadはボディを自動的にシリアライズし、コンテンツタイプを設定します。data=json.dumps(payload)を使う場合は、明示的なContent-Typeヘッダーを保持する必要があります。- 送信時にクライアント側タイムアウトを設定すると、接続のハングを防げます。これは生成時間を制限するものではありません。生成はサーバー側で行われるため、ポーリングが必要になるのです。
- パース前にまずステータスコードを確認する。 4xx のレスポンスボディはステータスコード自体よりも情報が多いことがよくあります。出力してください。
- API キーは絶対にログに記録しない。 代わりに
task_idを記録します。安全に保存でき、デバッグのハンドルになります。
duration とアスペクト比パラメータ
この 2 つのフィールドはリクエストが拒否される最も一般的な原因であるため、真剣に扱う価値があります。
duration
duration はリクエストするクリップの長さを秒単位で設定します。リクエスト可能な値はエンドポイントの対応範囲に制限されます。範囲外の値を送信すると、通常はサイレントにクリップが切り詰められるのではなく、パラメータ検証エラーになります。API リファレンスに記載された対応値を選び、整数として保ってください。クリップが長いほどレンダリングに時間がかかるため、開発段階では対応する最短の長さを優先してください。検証すべきはフローの連結であり、映像芸術ではありません。
aspect_ratio
aspect_ratio は W:H 形式の文字列です。動画が最終的に表示される場所に合わせてください:
16:9—— 横長:Web サイトのヒーローセクション、YouTube 風プレーヤー、デスクトップ背景。9:16—— 縦長:モバイルのショート動画フィードやストーリーズ。1:1—— 正方形:グリッドレイアウトやサムネイル。
ここで形を間違えると修正コストは低く済みますが、気づくのが遅いと割高になります。再レンダリングには完全な生成サイクルがもう 1 回必要です。そのため、送信前に表示先のシーンを決めておくべきです。
拒否されたときに確認すべきこと
- 型の不一致 ——
durationを数値ではなく文字列("5")で書く、あるいはaspect_ratioを 2 つの数値で書く。duration は数値のまま、アスペクト比は文字列のままにしてください。 - サポートされていない値 —— 長さや比率がドキュメント記載の範囲外。リファレンス一覧と 1 つずつ照合してください。
- フィールド名 ——
aspectRatioやdurationSecondsのような綴り間違いは、最良の場合でも未知のフィールドとしてサイレントに処理されます。フィールド名はリファレンスドキュメントからコピーしてください。
問題のフィールドを素早く特定する方法:まず prompt だけで再送信し、その後パラメータを 1 つずつ戻します。最初に拒否された時点で、問題のフィールドが分かります。
動画が準備できるまで非同期タスクをポーリングする
ポーリングは、状態を確認し、スリープし、終端状態で停止するという 3 つのルールに従うループです。さらに上限を設けて、スタックしたタスクが無限に空回りしないようにします。
import time
import requests
def wait_for_video(task_id, base_url, api_key, timeout=600):
headers = {"Authorization": f"Bearer {api_key}"}
url = f"{base_url}/tasks/{task_id}" # ステータスルートは API リファレンスを参照
deadline = time.time() + timeout
delay = 2
while time.time() < deadline:
r = requests.get(url, headers=headers, timeout=30)
r.raise_for_status()
task = r.json()
status = task["status"]
if status == "succeeded":
return task["result"]["video_url"]
if status == "failed":
raise RuntimeError(f"generation failed: {task.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15) # 控えめなバックオフ、上限あり
raise TimeoutError(f"task {task_id} not finished in {timeout}s")
バックオフが重要な理由
1 分かかる生成タスクを毎秒一定間隔でポーリングすると、何十回ものリクエストを無駄にします。小さな間隔から始めて徐々に増やします。上記の上限倍率は、API を頻繁に叩かずに快適な間隔に落ち着きます。多数のタスクを実行する場合は、リクエストごとに 1 つのループを回すよりも、キューと単一のポーリングワーカープロセスの組み合わせが優しい方法です。
結果の処理
タスクが成功すると、レスポンスに動画 URL が含まれます。速やかに取得し、結果を保持する必要がある場合は自分のストレージにコピーしてください。署名付き URL は永久に有効ではありません。ファイルをユーザーに渡す前に、ダウンロード時のコンテンツタイプとサイズを確認し、task_id を保存したアセットと一緒に記録してください。そうすれば将来の問題を正確な生成記録まで追跡できます。
よくあるエラーの切り分け
呼び出しが失敗したら、このチェックリストを順に確認してください。ほとんどの失敗は以下の 4 つのカテゴリのいずれかに当てはまります。
認証とアクセス
- 401 / unauthorized —— キーが欠落、形式が誤っている、または送信されていない。ヘッダーが正確に
Authorization: Bearer <key>であること、そして呼び出しを行うシェルまたはプロセスでその環境変数が実際に設定されていることを確認します。 - 403 / forbidden —— キーは有効だが、このエンドポイントへのアクセスが許可されていない。ダッシュボードでそのキーの権限範囲を確認します。
リクエスト検証
- 400 / 422 —— JSON の形式エラー、またはフィールド値の誤り。完全なエラーレスポンスボディを出力してください。通常はフィールドを示します。
durationの型とaspect_ratioの文字列形式を再確認します。 - 送信時の 404 —— エンドポイントパスが誤っている。パスが正確に
pixverse-v6-max/text-to-videoであること、およびベース URL に重複や欠落したパスセグメントがないことを確認します。
タスクレベルの失敗
- ステータスが
failed—— タスクは受け付けられたが生成に失敗。タスク上のエラーメッセージを読みます。コンテンツ拒否と内部障害を区別できます。プロンプト拒否は API の問題ではなくプロンプトの問題です。修正して再送信します。 - 実行状態でスタック —— ポーリングに期限を設定し、タイムアウトをサービスをクラッシュさせる例外ではなく、対処すべき失敗として扱います。
運用上の問題
- 429 / レート制限 —— 送信中またはポーリング中のリクエストが多すぎる。並列度を下げ、レスポンスに含まれる再試行の指示に従います。
- 送信時の接続タイムアウト —— ネットワークまたはプロキシの問題であり、生成の問題ではない。バックオフ付きで送信を再試行しますが、重複タスクが発生する可能性を許容できる場合に限ります。
- ダウンロード時の動画 URL 404 —— URL の有効期限が切れている。古い URL を再利用せず、タスク結果を再取得します。
繰り返せる習慣
失敗のたびに 3 つの値を記録します。HTTP ステータスコード、レスポンスボディ、そして(あれば)task_id です。この 3 つがあれば「壊れた」を「ここで壊れた」に変えられ、それがデバッグを速くする唯一の鍵です。
次にやること
これで完全な閉ループを押さえました。認証、送信、タスク識別子の取得、バックオフ付きポーリング、そして結果の取得です。本番投入するには、送信とポーリングを小さなクライアントクラスにまとめ、task_id とプロンプトを各アセットと一緒に保存して追跡可能にし、ポーリングをバックグラウンドワーカープロセスに移して、ユーザー向けリクエストがレンダリングでブロックされないようにします。
次に、HiAPI リファレンスドキュメントにある隣接エンドポイントを探索してください。既存の静止画にアニメーションを加える画像toビデオや、完全な生成に入る前に映像スタイルを磨くためのプロンプト反復インタラクション方式などです。ここで学んだリクエストの形はほぼそのまま移行できます。