チュートリアル
veo-3.1 テキストtoビデオ API の呼び出し方法:curl と Python の例
開発者向けの実践的な統合ガイド
このページの内容
veo-3.1/text-to-video でできること
veo-3.1/text-to-video は、HiAPI の統合 API を通じて提供されるテキストtoビデオ生成モデルです。テキストのプロンプトを送信し、いくつかの出力オプションを選択すると、生成された動画が返ってきます。他の生成エンドポイントと同様に HiAPI 上にあるため、すでにこのプラットフォームで画像やチャットの機能を使っているなら、この統合方法は馴染みのあるものに感じられるでしょう。認証付きの HTTP リクエストが 1 回ジョブを返し、完了するまでポーリングします。
このエンドポイントは、シーンのテキスト記述があり、インフラを自分で管理せずに短い動画を生成したい場合に適しています。GPU の割り当て、モデルの重み、キューイングを自分で処理する必要はありません。その代償は生成が非同期であることです。ジョブを送信し、後で結果を確認します。これは動画では一般的です。レンダリングには単一のリクエスト/レスポンスサイクルよりも長い時間がかかるためです。
中核となる入力がプロンプトの場合は、テキストtoビデオを使用します。後で画像条件や動画条件の生成が必要になった場合は、モデルカタログの対応するエンドポイントを確認してください。ここでのリクエスト構造(認証、ジョブ送信、ポーリング)は、HiAPI のメディアエンドポイントで再利用するパターンと同じなので、一度学べば長く役立ちます。完全なモデルの詳細はveo-3.1/text-to-video モデルページで確認できます。
エンドポイント、認証、リクエスト構造
すべての HiAPI リクエストは HTTPS と bearer トークンを使用します。API キーはハードコードせずに環境変数に保存し、Authorization ヘッダーに入れて送信します:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
テキストtoビデオのリクエストは、model フィールドと input オブジェクトを含む JSON オブジェクトです。input オブジェクトにはプロンプトと任意の出力制御項目が入ります。最小のリクエストボディは次のようになります:
{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "夜、雨に濡れたネオンの路地をゆっくりとドリーインするショット"
}
}
返ってくるのは最終的な動画ではなく、ジョブのエンベロープです。通常、ジョブ識別子、ステータスフィールド、タイムスタンプが含まれます。構造はおおよそ次のとおりです:
{
"id": "job_abc123",
"status": "queued",
"created_at": "2025-01-01T00:00:00Z"
}
フィールドの正確な名前は実際のレスポンスに従ってください。ただし構造は一貫しています。ポーリングには id が必要で、status はジョブがキュー待ちか、実行中か、完了したかを示します。送信呼び出しが 200 を返したからといってジョブが完了したと判断しないでください。それはジョブが受け付けられたという意味にすぎません。
パラメータの選択:ネイティブ音声と解像度ティア
プロンプト以外でテキストtoビデオに最も重要なパラメータは、ネイティブ音声を生成するかどうかと、目標とする解像度ティアです。どちらも生成時間と出力の性質に影響するため、盲目的にデフォルト値を使うのではなく、意識的に選択してください。
ネイティブ音声
一部の動画モデルは映像とともに音声トラックを生成できます。このエンドポイントがネイティブ音声の切り替えを提供する場合、有効にすると生成されたクリップに同期した音声が含まれます。環境音、音楽、動作に合った効果音など、音声自体が体験の一部となるシーンに役立ちます。後から独自の BGM やナレーションを追加する予定なら、無効にして出力を映像に集中させてください。音声生成は処理時間も増やすため、本当に必要な場合にのみ有効にしてください。
解像度ティア
解像度ティアにより、映像の忠実度とコスト・レイテンシの間でトレードオフできます。高いティアほど鮮明な出力になりますが、時間がかかりリソースも多く消費します。納品目標を満たす最低のティアを選択してください。反復やレビューにはドラフトティア、最終レンダリングには高いティアを使います。1 つのプロンプトで多くの候補を生成する場合は、低いティアで探索し、勝ち残ったものをフル品質で再生成します。課金は生成した出力に応じて行われるため、ティアを意識的に選ぶことがあなたが制御できる主なレバーです。
このエンドポイントが現在どの値を受け入れるか不明な場合は、まずプロンプトだけを含むリクエストを送信し、レスポンスまたはエラーメッセージを確認してください。HiAPI は受け入れ可能なフィールドを列挙した構造化された検証エラーを返すため、推測せずにそれに合わせて調整できます。
実行可能な curl リクエスト
この curl コマンドはテキストtoビデオのジョブを送信します。JSON コンテンツタイプを設定し、環境変数から bearer トークンを渡し、model と input を含むリクエストボディを送信します。
curl -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "夜、雨に濡れたネオンの路地をゆっくりとドリーインするショット",
"duration": 5,
"resolution": "720p"
}
}'
呼び出しに成功すると、ジョブの id と status を含む JSON オブジェクトが返ります。この id を控えてください。ポーリング時に必要になります。スクリプトを書く場合は、出力を JSON プロセッサに通して id を抽出できます:
JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"veo-3.1/text-to-video","input":{"prompt":"夜、雨に濡れたネオンの路地をゆっくりとドリーインするショット"}}' \
| jq -r '.id')
echo "$JOB_ID"
エンドポイントパス、パラメータ名、および任意のフィールドは、実際の API の期待に合わせて調整してください。JSON リクエストボディを POST し、レスポンスから id を読み取るというこのパターンが、以降のすべての例の基礎となります。
Python で同じリクエストを送信する
Python 版は標準の requests ライブラリを使って同じことを行います。環境からキーを読み取り、payload を構築して送信します。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "夜、雨に濡れたネオンの路地をゆっくりとドリーインするショット",
},
}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
job = response.json()
job_id = job["id"]
print(f"ジョブを送信しました:{job_id}(ステータス:{job.get('status')})")
強調すべき点が 2 つあります。第一に、response.raise_for_status() は HTTP エラーを例外に変換し、壊れた payload が静かに流れていくのではなく失敗が即座に可視化されます。第二に、timeout=60 は接続のハングアップがスクリプトをブロックするのを防ぎます。送信自体はすぐに終わります。実際の動画は非同期でレンダリングされるため、ここでファイルを待つことはありません。次に、job_id を使って完了状況をポーリングします。
動画が準備できるまで非同期ジョブをポーリングする
送信後、ステータスが完了または失敗を示すまでジョブのエンドポイントをポーリングします。短いスリープを入れたシンプルなループで、最初は十分です。
import time
while True:
res = requests.get(
f"{BASE_URL}/videos/generations/{job_id}",
headers=headers,
timeout=30,
)
res.raise_for_status()
state = res.json().get("status")
print(f"ステータス:{state}")
if state == "succeeded":
video_url = res.json().get("output", {}).get("url")
print(f"動画の準備ができました:{video_url}")
break
if state == "failed":
raise RuntimeError(f"ジョブが失敗しました:{res.json()}")
time.sleep(5)
実用的な改善点:短い間隔から始めて徐々にバックオフし、無駄なリクエストを減らす。最大試行回数や期限を設けて、スタックしたジョブが無限ループにならないようにする。予期しないステータスは「待ち続ける」と仮定せず慎重に扱う。一般的なステータス値には queued、running、succeeded、failed があります。ジョブが成功すると、通常レスポンスに出力 URL が含まれます。署名付き URL は期限切れになる可能性があるため、ファイルを早めにダウンロードして保存してください。
ポーリングを冪等にし、各ステータス時にジョブ id を記録してください。プロセスが再起動した場合、再送信せずに id で再開できます。本番環境では、プラットフォームが webhook を提供するならそれを使い、ポーリングをフォールバックとすることを検討してください。
よくあるエラーのトラブルシューティング
ほとんどの失敗はいくつかのカテゴリに分類されます。盲目的に再試行するのではなく、以下のチェックリストを順に確認してください。
認証失敗(401/403)
Authorization ヘッダーが存在し、Bearer <key> の形式で正しく設定されているか、またその環境変数がリクエストを発行するシェルまたはプロセスで実際に設定されているかを確認してください。よくある落とし穴は、あるシェルではキーが存在するが別のシェルでは存在しない環境でスクリプトを実行することです。
検証エラー(400/422)
この種のエラーは、どのフィールドが誤っているかの構造化された詳細を返します。よくある原因:prompt の欠落、サポートされていない resolution や duration の値、パラメータのネスト階層の誤りなど。エラーメッセージを文字どおりに解釈してください。通常は問題のあるフィールドを指摘しています。まず最小の payload を送信し、その後 1 つずつパラメータを追加してください。
レート制限(429)
リクエストを送信するのが速すぎます。指数バックオフと再試行上限を実装してください。多くのジョブを起動する場合は、送信時間をずらし、進行中のジョブを追跡してください。
タイムアウトとネットワークエラー
送信時のクライアントタイムアウトは、ジョブ自体の問題であることはまれです。ジョブはサーバー側で実行されています。送信とポーリングの両方のリクエストに妥当なタイムアウトを使用し、冪等な GET リクエストは再試行してください。元のジョブが作成されたかを確認せずに POST を盲目的に再試行しないでください。
ジョブが完了しない
ジョブが期待よりはるかに長く queued または running のままの場合、再送信するのではなく、ステータスコードとメッセージを確認してください。長いプロンプトや高い解像度ティアはより長い時間がかかります。これは正常です。ジョブが failed を報告した場合は、レスポンスボディ全体を記録してください。エラーメッセージには通常、原因が示されています。
不明な場合は、可能な限り最小のリクエストで再現し、すべてのレスポンスを確認してください。一度に複数のパラメータを変更してどれが重要かを推測するよりも、はるかに優れています。エンドポイント固有の詳細については、モデルページを参照してください。