チュートリアル
HiAPI API で veo-3.1/image-to-video を呼び出す:curl と Python のチュートリアル
このページの内容
veo-3.1 画像から動画へのエンドポイントが何を期待するか
最初の1行のコードを書く前に、これがどのような種類の呼び出しなのかを理解しておくと役立ちます。veo-3.1/image-to-video は、プロンプトを送信した HTTP レスポンスの中で直接動画を返すことはありません。これは非同期タスクエンドポイントです。あなたが望む動画を記述すると、プラットフォームがタスクを受け付け、その後で結果を問い合わせに戻ってくる仕組みです。
概念的には、1つのリクエストは大きく分けて2つの部分から構成されます:
- 最初のフレーム画像。 これは生成される動画の開始時の静止フレームです。冒頭の瞬間の構図、被写体、見た目を固定します。その後のすべての内容はこの起点からモデルが生成します。
- 生成オプション。 これらは動画の生成方法を制御するパラメータです。たとえば音声を生成するかどうか、出力解像度、クリップの長さなどです。
この分割が重要なのは2つの理由からです。第一に、故障の推論が容易になります。画像の問題はパラメータの問題とは見え方が異なるため、両者を区別できると望ましいです。第二に、コードも同じように構成すべきだということを意味します。一方のロジックが画像の準備を担当し、もう一方がオプションの集合の構築を担当します。
呼び出し側は少なくとも、有効な最初のフレーム画像、および音声・解像度・長さに関する決定を提供する必要があります。それ以外のすべて(タスクの送信、状態の追跡、最終動画の返却)はプラットフォームのタスクライフサイクルが処理します。あなたの統合が行うべきことは3つだけです。正しい形式のリクエストを送信し、返されたタスク識別子を記憶し、タスクが終態に達するまでポーリングすることです。
続ける前に1つ実用的なヒントがあります。呼び出しは非同期であるため、コードは送信後に動画がすぐ利用可能になることを前提にできません。最初からこの点を中心にフローを設計すれば、以降のチュートリアルは自然に理解できるでしょう。
2つの部分のメンタルモデル
以下の章を読むときは、この枠組みを保ってください:
- 入力 → 準備・検証済みの最初のフレーム画像。
- オプション → 音声、解像度、長さ。
- タスク → 送信、識別子の取得、ポーリング、取得。
以下の各節は、このうちの1つのボックスに対応します。
最初のフレーム画像を準備する
最初のフレーム画像は、画像から動画への呼び出しにおいて最も重要な単一の入力です。そのため、パイプライン内で専用のステップを設け、リクエストビルダーの中に埋め込まないようにしましょう。API 呼び出しはその画像を参照できなければならず、これは画像がプラットフォームにとって受け入れ可能で読み取り可能な形式である必要があることを意味します。
送信前に確認すべきこと
- 画像が実際に開けること。 ダウンロードが途中で切れたりファイルが破損したりすることは、下流で不可解な失敗が起きる最も一般的な原因です。何かを送信する前に、正常にデコードできることを検証してください。
- 形式がプラットフォームで受け入れられること。 ソースがスクリーンショット、スマートフォンの写真、デザインツールの書き出しファイルである場合は、アップロード前に広くサポートされる形式に正規化してください。事前に一度変換しておく方が、後からデバッグするより楽です。
- サイズが妥当であること。 極端に小さい、または極端に引き伸ばされた画像は、モデルに与える材料がほとんどありません。ソースが小さすぎる場合は、拡大するか、より良いフレームを選ぶことを検討してください。
- 構図が良い起点であること。 これは最初のフレームであるため、生成される動きはそこから続きます。被写体がはっきり見えており、クリップの冒頭でその構図を見ても構わないフレームを選んでください。
オプションと分離する
コードを整理する際は、画像の準備がリクエストビルダーに渡せる参照を返すようにし、画像処理とパラメータの組み立てを混在させないようにしてください。具体的には:
# 疑似コード構造であり、完全なクライアントではない
def prepare_first_frame(path):
image = load_and_validate(path) # デコード、形式チェック、サイズチェック
ref = upload_or_encode(image) # API 呼び出しが参照できるもの生成
return ref
def build_request(first_frame_ref, options):
return {
"first_frame": first_frame_ref,
# 音声 / 解像度 / 長さをここに配置
}
この分離はデバッグ時に報われます。タスクが失敗した場合、prepare_first_frame を単独で再実行し、生成パラメータに触れる前に画像側が健全であることを確認できます。
早めに検証し、大きな声で失敗する
自分の側で検証を完了し、失敗時には明確なエラーをスローしてください。形式が誤っていたり読み取れない画像は決してネットワークに到達してはなりません。ローカルで捕捉すれば、曖昧な非同期タスクの失敗を、自分で書いた正確かつ即時の例外に変えられます。
生成オプションを設定する:音声、解像度、長さ
画像の処理が終わったら、残る決定は生成オプションです。これらは出力の性質を変えるため、リクエストボディに埋め込まれた魔法の値ではなく、明示的な名前付きパラメータとして扱うべきです。
音声
音声オプションは、生成される動画に音声トラックを含めるかどうかを制御します。これは技術的な決定であると同時に製品上の決定でもあります:
- 動画が無音で埋め込まれる場合(背景ループ、自動再生のメインビジュアルなど)は通常音声は不要で、省くことで下流の処理が簡単になります。
- クリップが音声付きで単独で提示される場合(短いソーシャルコンテンツ、デモなど)は音声を有効にし、1回の呼び出しで完全な素材を得られるようにします。
デフォルト値を盲目的に採用するのではなく、ユースケースに応じて意図的に決定してください。出力にも、下流のパイプラインがそのファイルをどう処理するかにも影響します。
解像度
解像度は最終的な動画のピクセル寸法を決定します。単に「利用可能な最大値」を選ぶのではなく、動画がどこで表示され、コンテンツがどれだけの詳細を必要とするかに基づいて選択してください。小型の埋め込みプレーヤー向けにレンダリングされるクリップを、表示パネルの能力をはるかに超えるサイズで生成しても利益はありません。プラットフォームがサポートする値の集合を公開している場合は、そこから明示的に選択し、クライアント側でそれに基づいて検証し、サポートされない値が早く失敗するようにしてください。
長さ
長さは生成されるクリップの尺を設定します。これはコンテンツ計画と相互作用します。シーンを確立してから動きを見せるショットは、単一のジェスチャーよりも多くの時間を必要とします。これは最も課金されやすいパラメータの1つである可能性に注意してください。プラットフォームの課金は生成出力を基準に記述されるため、バッチリクエストの際はクリップの長さに気を配ってください。
オプションを1つのオブジェクトに組み立てる
3つを同じオプション構造にまとめ、確認する場所も変更する場所も1か所だけにしてください:
options = {
"audio": True, # 音声トラックを生成
"resolution": "...", # サポートされる値の1つ
"duration": 8, # 生成動画の秒数
}
あなたのアカウントと現在のエンドポイントドキュメントがサポートすると記載している値を使用してください。ドキュメントから読み取り、ハードコードした推測ではなく、リクエスト構築時に検証して、不正な値が失敗したタスクにならないようにしてください。
curl でタスクを送信する
ここで2つの部分を組み合わせて送信します。コマンドラインから始めましょう。curl はリクエストの形を可視化し、コードを書く前に変更を素早くテストする方法を提供します。
リクエスト
送信リクエストは構造的には次のようになります。プレースホルダーの値を自分の認証情報、画像参照、オプション値に置き換えてください:
curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_frame": "<アップロード手順からの画像参照>",
"audio": true,
"resolution": "<サポートされる値>",
"duration": 8
}'
身につける価値のある慣習がいくつかあります:
- キーはコマンドに貼り付けるのではなく、環境変数(
$HIAPI_API_KEY)に置いてください。この習慣はそのまま Python コードに引き継がれ、キーをシェル履歴から遠ざけます。 - 明示的な
Content-Typeヘッダーで JSON を送信してください。 - リクエストボディ内で画像参照と数値・ブール値のオプションを分離し、第1節の2つの部分モデルを反映してください。
レスポンスを読む
これは非同期エンドポイントであるため、成功レスポンスは動画ではありません。それはタスクが受け付けられたことの確認にすぎず、追跡に必要な情報、最も重要なのはタスク識別子、そして通常はタスクがキューに入ったか実行中であるかを示すステータスフィールドを伴います。
2つのステップで読み取ります。まず、HTTP ステータスがクライアントエラーではなく受け付けを示していることを確認します。次に、レスポンスボディを解析してタスク識別子を抽出します:
curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | tee submit.json
レスポンスを submit.json に書き出せば、確認でき、ポーリングステップに渡せるものになります。送信が失敗した場合、エラーレスポンスボディが最初で最良の手がかりです。それが画像参照を指しているのか、あるいはあるオプションを指しているのかを確認し、その半分だけを修正して再送信してください。
動画が準備できるまで非同期タスクをポーリングする
タスク識別子を取得したら、ワークフローはループになります。プラットフォームにタスク状態を問い合わせ、タスクが終態に達したら停止します。
ライフサイクル
画像から動画へのタスクは少数の状態を経ます。受け付けられてキューに入り、処理され、最終的に成功して動画を生成するか、失敗してエラーを返します。ポーリングコードは3つのことだけを区別できれば十分です:
- まだ処理中 — 待機を続ける。
- 成功 — 出力位置を読み取り、動画をダウンロードまたは保存する。
- 失敗 — 停止してエラーをスローする。
責任あるポーリング
2つの習慣がポーリングをより堅牢にします:
- チェックの間に待機する。 タイトなループでステータスエンドポイントを連打するのはリクエストの無駄であり、何の利益もありません。生成には実際の時間がかかります。固定間隔または穏やかなバックオフを使用してください。
- 期限を設定する。 決して無限にポーリングしないでください。最大試行回数または最大経過時間を選び、それを超えたら明確に報告可能な失敗として扱ってください。
# ポーリングループのスケッチ
for i in $(seq 1 60); do
status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
-H "Authorization: Bearer $HIAPI_API_KEY")
echo "$status"
# ステータスフィールドが成功または失敗を報告したら抜ける
sleep 5
done
正確なステータス文字列とエンドポイントパスは、スクリプトに固定された仮定ではなく、現在の API ドキュメントと照らし合わせて確認すべき事項として扱ってください。
成功した場合
タスクが成功を報告すると、レスポンスは最終動画の位置を伴います。速やかにダウンロードし、永続的な場所に保存してください。非同期プラットフォーム上のタスク結果は、ずっと後で遅延取得するものではなく、今すぐ取得すべきものとして扱うべきです。タスク識別子を保存ファイルとともに記録し、あらゆる出力がそれを生成したリクエストまで追跡できるようにしてください。
Python での同じリクエスト
Python 版は2つ目の実装であってはなりません。同じリクエストを一度表現し、再利用するべきです。目標は、以前に検証した同じ画像参照と同じオプションオブジェクトから構築される、単一の送信・ポーリング関数です。
1つのリクエストボディ、1つのクライアント
import os
import time
import requests
BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
})
def build_body(first_frame_ref, options):
return {"first_frame": first_frame_ref, **options}
def submit(body):
r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
r.raise_for_status()
data = r.json()
return data["job_id"]
def poll(job_id, interval=5, max_attempts=60):
for _ in range(max_attempts):
r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
r.raise_for_status()
data = r.json()
state = data.get("status")
if state in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"タスク {job_id} が時間内に完了しませんでした")
def image_to_video(first_frame_ref, options):
job_id = submit(build_body(first_frame_ref, options))
result = poll(job_id)
if result["status"] == "failed":
raise RuntimeError(result.get("error", "タスクが失敗しました"))
return result # 最終動画の位置を含む
なぜこの形なのか
- 1つの
Session。 セッションを再利用することで認証ヘッダーを1か所に置き、送信と各ポーリングの間で接続を再利用します。 - 1つの
build_body。 curl リクエストと Python リクエストは同じリクエストボディです。同じキー、同じ値です。あるオプションを変更するときは1か所だけ変更します。 - 明示的なタイムアウトと期限。 両方の呼び出しにタイムアウトを設定し、
pollには試行回数の制限があるため、停滞したタスクがプロセスをハングさせることは決してありません。 - 失敗は大きな声で露見する。 送信時の
raise_for_statusはリクエストレベルのエラーを即座に捕捉し、image_to_video内の明示的な失敗分岐はタスクレベルの失敗を捕捉します。
将来、同じプラットフォームを通じて他のモデルを呼び出す必要が生じた場合、この構造は一般化できます。セッション、送信ヘルパー、ポーリングヘルパーはそのままで、エンドポイントとリクエストボディビルダーだけが変わります。
失敗した画像から動画への呼び出しをトラブルシューティングする
呼び出しが動画を生成しない場合、どの段階で失敗したかを問うことで範囲を絞り込みます。2つの部分からなるリクエストモデルは明確なチェックリストを提供します。
段階1:送信が拒否された
送信呼び出し自体がエラーを返した場合、何も生成されていません。これは良い知らせです。問題はリクエスト内にあるからです。
- 画像参照の問題。 最も一般的な単一の原因です。画像準備ステップを単独で再実行し、有効で読み取り可能、正しい形式の画像と API が受け入れる参照を生成することを確認してください。まずアップロードの切断とサポートされない形式を確認してください。
- 無効なオプション値。 サポートされない解像度や範囲外の長さは送信時に拒否されます。送信前にドキュメントのサポート値と照らし合わせてオプションを検証してください。
- 認証とリクエストヘッダー。 キーが実際に送信されていること(
Authorization: Bearer ...)、およびリクエストボディが JSON として送信されていることを確認してください。curl で手作業でリクエストを構築するとき、空または不正な形式のボディは見落とされがちです。
段階2:タスクは送信されたが失敗した
送信が受け付けられたのにポーリングが失敗で終わった場合、リクエストの形式は正しく、問題は内容またはタスク自体にあります。
- タスクのエラーを読む。 失敗レスポンスは推測よりも、何が問題だったかをよく説明します。そのまま記録してください。
- 最初のフレームを確認する。 明確な被写体がない、極端にトリミングされた、またはひどく歪んだソース画像は、モデルに与える材料がほとんどありません。よりきれいなフレームに差し替えて再試行してください。
- オプションを再検討する。 非常に長い長さや珍しい設定の組み合わせは、より単純な構成で再テストしてどのパラメータに問題があるかを切り分ける価値があります。
段階3:ポーリングが永遠に終わらない
ループが失敗ではなくタイムアウトした場合、それを内容の問題ではなくインフラの問題として扱ってください。正しいタスク識別子をポーリングしていること、間隔が過度に攻撃的でないこと、期限が要求された長さに対して十分に長いことを確認してください。送信時にタスク識別子を記録してください。それがなければ、停滞したタスクを調査すること自体できません。
効果的なデバッグの流れ
問題が発生した場合は、この順序で進めてください:画像をローカルで検証し、再度送信して生のレスポンスを捕捉し、タスクエラーが現れた場合はそれを確認し、その後オプションを簡素化して再試行します。各ステップはリクエストのちょうど半分をテストするため、コード内で画像と生成パラメータを分離しておくことが、まさにエラー時に報われるのです。
これで完全なサイクルを手に入れました。最初のフレームを準備し、音声・解像度・長さを設定し、非同期で送信し、完了までポーリングします。curl で実行しても Python で実行しても、同じリクエストです。