チュートリアル
HiAPI APIでpixverse-v6-maxのimage-to-videoを使う方法:curl、Python、そして実際に動くリクエスト
このページの内容
pixverse-v6-maxのimage-to-videoエンドポイントが要求するもの
HiAPI上のpixverse-v6-max/image-to-videoエンドポイントは、非同期の、画像を条件とする動画生成タスクです。この一言が、統合時にあなたが下すほぼすべての決定を左右します。
このエンドポイントは、ソース画像(先頭フレーム)と生成パラメータのセットを受け取り、完成した動画ではなくタスク参照を返します。実際のレンダリングはサーバー側で行われ、選んだパラメータによって数秒から数分かかることがあります。クライアントはタスクを投入し、終端状態を報告するまでそのステータスを繰り返し問い合わせる責任を負います。
これを同期の画像編集と比較してみましょう。同期編集では、リクエストボディをPOSTして、同じHTTPレスポンス内で変換後の画像をそのまま受け取ります。ここでの流れはこうです:
- 画像とパラメータを生成エンドポイントへ
POSTする。 - タスク識別子(通常は初期状態も付随)を受け取る。
- 完了または失敗するまで、間隔を置いて
GETでタスクステータスを取得する。 - 完了したタスクのレスポンスボディから生成された動画URLを読み取る。
この分離により、エラーは2種類に分かれます:投入段階の問題(認証エラー、リクエストボディの形式誤り、画像の拒否)と、実行段階の問題(タスクが受け入れられた後に失敗または停滞する)です。適切な統合では両方を明示的に処理します。具体的なチェックリストは後述のトラブルシューティング部分にあります。
もう一つ覚えておくべきこと:ソース画像がアンカーです。モデルはこの先頭フレームからアニメーションを開始するため、画像の品質、アスペクト比、内容は、提供するどんなプロンプトテキストよりも出力に大きく影響します。アップロードの正確さを後回しの考慮事項ではなく、最優先の関心事として扱ってください。
APIキーとエンドポイントを準備する
最初のリクエストを送る前に必要なものは2つだけです:HiAPI APIキーと、このエンドポイントの正しいベースURLです。
キーを取得する
HiAPIアカウントのコンソールでAPIキーを作成します。パスワードと同様に扱い、ソースコードやシェル履歴ではなく環境変数に置いてください。
export HIAPI_API_KEY="your_key_here"
ローカルで.envファイルを使う場合は、何かをコミットする前に.gitignoreに追加してください。共有ログ、スクリーンショット、リポジトリに現れたキーは直ちにローテーションすべきです。
ベースURLとパスを理解する
エンドポイントはHiAPI APIホストの下にあり、モデルパスはpixverse-v6-max/image-to-videoです。以下の例ではベースURLをhttps://api.hiapi.aiとして示し、完全なパスはそれを連結して構成します。アカウントやリージョンでホストが異なる場合は、一貫して置き換えてください。ホストとキーの不一致は401の最も一般的な原因の一つであり、開発者はしばしばこれを「無効なキー」と誤解します。
ツールを選ぶ
- curlは最初の素早い検証用です。リクエスト自体以外のすべての変数を排除します。
- Python 3と
requests(またはhttpx)は実際の統合用です。
python3 -c "import requests; print(requests.__version__)"
バージョン番号が出力されれば準備完了です。本記事の例はSDKのインストールを必要としません。すべて純粋なHTTPなので、後から任意の言語に移植できるという意味でもあります。キーとホストを確認できたら、リクエストの構築を始められます。
curlでリクエストを構築する
実際に成功する最小のリクエストから始め、その後でパラメータを追加しましょう。以下のリクエストボディは、完全なimage-to-video投入の構造を示しています。
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://your-cdn.example.com/first-frame.jpg",
"duration": 5,
"aspect_ratio": "16:9"
}'
ここで起きていることは3つです:
- 認証は
Authorizationヘッダーでbearerトークンを運びます。 - リクエストボディはJSONなので、画像はURL文字列として提供します(ローカルファイルを渡す方法は次のセクションで説明します)。
- 2つの生成パラメータ——
durationとaspect_ratio——がトップレベルのフィールドです。
投入に成功すると、タスク識別子を含むJSONオブジェクトが返ります。それをキャプチャしましょう:
JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"
そしてポーリングします:
curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
失敗時は必ずステータスフィールドと生のエラーレスポンスボディを確認してください。curlは終了コードが0でもエラーJSONを出力する可能性があるため、スクリプトでは終了コードだけに頼らないでください。
先頭フレーム画像を正しく提供する
ソース画像が最も一般的な失敗ポイントであり、ほぼすべての拒否は次の4つの理由のいずれかに帰着します。
1. 画像にアクセスできない
URLを渡す場合、HiAPIのサーバーがそれをGETできなければなりません。しかも彼らのネットワークからであって、あなたのネットワークからではありません。localhostのURL、プライベートバケット、60秒で期限切れになる署名付きURL、VPNの背後にあるエンドポイントはすべて失敗します。公開読み取り可能なオブジェクトストレージのURLやCDNリンクを使い、Cookieなしの新しいブラウザセッションで読み込めることを確認してください。
2. 画像形式がサポートされていない
標準的なWeb形式——JPEG、PNG、WebP——に固執してください。珍しい拡張子のファイル、スマートフォンで撮影したHEIC、アニメーションGIFはリスクがあります。パイプラインが特殊な形式を生成する場合は、先にトランスコードしてください。
3. 先頭フレームが宣言したアスペクト比と一致しない
これはやや微妙です。ソース画像が正方形なのに16:9をリクエストすると、サービスは入力のクロップ、パディング、または拒否のいずれかを行う必要があります。挙動は異なる可能性があり、そのどれもが大多数の開発者が望むものではありません。アップロードする前に自分でクロップまたはレターボックス処理を行い、画像のジオメトリがリクエストするaspect_ratioと既に一致するようにしてください。これにより出力が予測可能になり、タスクの無駄を避けられます。
4. 画像が大きすぎる、または小さすぎる
極端に高解像度の静止画(例えば8Kカメラの出力)は帯域を消費し、拒否されたりダウンサンプリングされたりする可能性があります。極端に小さいサムネイルでは、モデルがアニメーション化する内容をほとんど持てません。アップロード前のステップの一環として、画像を妥当な長辺サイズに正規化してください。
ローカルファイルを渡す
エンドポイントが画像フィールドでmultipartアップロードを受け付ける場合、パターンは次のとおりです:
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-F "image=@./first-frame.jpg" \
-F "duration=5" \
-F "aspect_ratio=16:9"
multipartを使うと数値フィールドが文字列になることに注意してください。どのContent-Typeが受け入れられるかはエンドポイントリファレンスを確認し、本番パイプラインではURL形式を優先してください。大きなバイナリファイルをアプリケーションサーバーに一切通さずに済みます。
durationとアスペクト比を設定する
これら2つのフィールドは、リクエストボディ内の他のどの内容よりもコストと出力に大きく影響します。
duration
durationは秒単位で、生成されるクリップの長さを表します。また課金に最も直接関係するフィールドでもあります。リアルタイムの価格設定はリクエストした出力時間に基づいて計算されるため、デフォルトで最大値を取るのではなく、慎重に選んでください。実用的なアドバイス:
- ストーリーを伝えられる最短の長さから始めてください。5秒のクリップはループ再生、製品ティーザー、ソーシャルフックに最適です。
- ショットが本当に長い時間を必要とする場合にのみ、より長いdurationを使ってください。静的な先頭フレームを長い時間アニメーション化すると、ドリフトして一貫性を失う傾向があります。
- クライアント側で検証してください:リクエストがサービスを離れる前に、非整数、ゼロ、負の数、不合理に大きな値を拒否します。
if not isinstance(duration, int) or not 1 <= duration <= 8:
raise ValueError("duration out of supported range")
現在サポートされている範囲はエンドポイントリファレンスで確認し、検証ロジックにそれを反映させてください。本記事の仮定をハードコードしないでください。
aspect_ratio
aspect_ratioは"16:9"、"9:16"、"1:1"などの文字列です。出力フレームのジオメトリを制御します。
16:9は横長用:YouTube、Webのヒーロービデオ、デスクトップ再生。9:16は縦長用:Reels、Shorts、TikTokスタイルの配信。1:1はフィードやサムネイル用。
2つのルールでトラブルを避けられます。第一に、ソース画像をリクエストする比率に一致させること。横長リクエストで縦長の先頭フレームを使うと、おそらく望まないクロップが発生します。第二に、比率を自由テキストではなく列挙型として扱うこと。ホワイトリストで検証すれば、"16x9"のようなタイプミスは往復の後ではなく、あなたのコード内で速やかに失敗します。
その他すべて
エンドポイントが追加の生成制御を公開している場合でも、最初のリクエストからは外しておいてください。最小で検証済みのリクエストボディがベースラインです。パラメータを一度に1つだけ追加し、出力を比較してください。この規律により、どのフィールドがリグレッションを引き起こしたかが一目でわかります。
同じリクエストをPythonで実装する
以下はcurlのフローをPythonに翻訳したものです。依存関係は意図的に最小限に保っています:requestsと標準ライブラリだけです。
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
resp = requests.post(
f"{BASE}/v1/pixverse-v6-max/image-to-video",
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def fetch(job_id: str) -> dict:
resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job_id = submit("https://your-cdn.example.com/first-frame.jpg")
print("submitted", job_id)
参考にすべき意図的な選択:
- 投入時に
raise_for_status()を呼び出す。400や401は即座に例外として表面化すべきであり、エラーレスポンスボディから["id"]を読み取ろうとしたときにKeyErrorになるべきではありません。 - 明示的なタイムアウト。 タイムアウトがないと、停滞した接続がワーカーを無限にハングさせます。
- 設定は環境から読み取る。 ベースURLとキーはコードにハードコードしません。
- 小さく型付きのヘルパー関数。
submitはタスクID文字列を返し、fetchは辞書を返します。解析を一箇所に集約すれば、スキーマ変更は1行の修正で済みます。
httpxのほうが好みなら、httpx.post(...)とhttpx.get(...)に置き換えるだけです。呼び出しはそれ以外まったく同じです。Webリクエストハンドラ内で実行するものについては、ここで投入してタスクIDをバックグラウンドワーカーに渡し、ユーザーのHTTPリクエストを動画生成でブロックさせないでください。
非同期タスクを完了までポーリングする
ポーリングは、ほとんどのチュートリアルが軽く流し、ほとんどのインシデントの原因となる部分です。ループ自体は短く、それを取り巻く規律が鍵です。
def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
deadline = time.time() + timeout
while time.time() < deadline:
job = fetch(job_id)
status = job.get("status")
if status == "completed":
return job["output"]["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish within {timeout}s")
上記で実装されている要点:
- 常にデッドラインを設定する。 動画生成は遅いため、無制限のループは無制限の請求とスタックしたワーカーになります。短いクリップには10分が妥当な上限です。durationの設定に応じて調整してください。
- 終端状態を区別する。 URLを生成するのは
completedだけです。failedとcancelledも終端状態です。ポーリングを停止し、errorフィールドを表面化してください。 - 妥当な間隔を使う。 数秒ごとで十分です。ステータスエンドポイントを連打するとレート制限にかかり、新しい情報も得られません。
- 長いタスクには穏やかなバックオフを:最初の1分以降、間隔を3秒から10秒に増やします。これにより負荷を減らしつつ、遅延コストは増えません。
- タスクIDを永続化する。 自分のレコードと一緒に保存しておけば、プロセスが再起動しても、同じタスクを再投入して再課金することなくポーリングを再開できます。
- ブラウザからAPIキーで直接ポーリングしてはいけません。 バックエンド経由でステータスチェックをプロキシしてください。
タスクが完了したら、返されたURLに永遠にリンクするのではなく、速やかに動画を自分のストレージにダウンロードしてください。生成されたアセットのURLは永続的に有効であることは保証されません。
失敗したタスクと停滞したタスクをトラブルシューティングする
このチェックリストを順番に実行してください。各ステップが1つのレイヤーを切り分けます。
投入エラー(タスクが作成されない)
401 Unauthorized—— キーが欠落、形式誤り、取り消し済み、または誤ったホストと組み合わされています。ヘッダーが正確にAuthorization: Bearer <key>であり、スペースが1つだけで、環境変数に余分な改行がないことを確認してください。403 Forbidden—— キーは有効ですが、このモデルまたはエンドポイントには許可されていません。リソースパスを1文字ずつ確認してください:pixverse-v6-max/image-to-video。400 Bad Request—— JSONが壊れているか、いずれかのフィールドが無効です。エラーレスポンスボディをデコードしてください。通常、問題のフィールドが示されます。一般的な原因:durationが数値ではなく文字列、"16:9"ではなく"16x9"、imageの欠落。422系の検証エラー —— フィールドは存在しますが範囲外です。推測せず、エンドポイントリファレンスと照合してください。429 Too Many Requests—— 送信が速すぎます。投入をキューに入れ、ジッター付き指数バックオフで再試行してください。タイトなループで再試行してはいけません。
実行失敗(タスクは作成されたが成功しなかった)
- 画像関連のエラーを伴う
failedステータス —— 投入後にソースURLの取得が失敗しました。これは典型的な「私のブラウザでは動く」の罠です。URLがCookie、referrer、IPホワイトリストを必要としている可能性があります。画像を公開で再ホストしてください。 - コンテンツまたは検証エラーを伴う
failedステータス —— 技術的な理由(形式、ジオメトリ、サイズ)でソース画像が拒否されました。トランスコード、リサイズし、宣言したアスペクト比に再クロップしてください。 - デッドラインを過ぎてもキューまたは処理中で停滞しているタスク —— まず正しいタスクIDを読んでいることを確認してください(コピー&ペーストのミスは驚くほどよくあります)。次に、ステータスが本当に変わっていないのか、ポーリングが誤ったベースURLに当たっているのかを確認してください。実際に停滞している場合は、APIが許す限りキャンセルして一度再投入してください。静かに何度も再投入することが予算の消える方法そのものです。
時間を節約する習慣
呼び出しごとに完全なリクエストID、タスクID、HTTPステータス、レスポンスボディを記録してください。ただしキーはマスクします。午前2時に問題が起きたとき、リクエストID1つが5分の修正と1時間の推測の差を生みます。最小で検証済みのリクエストボディから始め、パラメータを一度に1つずつ追加すれば、このチェックリストはほとんど必要なくなります。