hiapi API で veo-3.1-lite/image-to-video を使用する方法

Veo 3.1 Lite は、1枚の参照画像とテキストプロンプトから短い動画を生成します。hiapi では、プラットフォーム上のすべてのモデルが共有する同一の非同期タスク API を通じて提供されます。本ガイドでは、実際に動作するリクエストの流れを一通り説明します。API キーの取得、POST /v1/tasks の呼び出し、結果の取得、そしてこの流れを使い捨てのスクリプトから本番環境へと進める際に注意すべき点（コールバック、冪等性、エラー処理）です。

何を構築するか、そして事前に準備するもの

画像 URL とプロンプトを veo-3.1-lite/image-to-video モデルに送信し、外部でホストされた .mp4 の URL を受け取ります。すべては hiapi の統合タスクエンドポイントを通じて実行されるため、同じリクエスト構造がプラットフォーム上のすべての動画・画像モデルに適用できます。変わるのは model id と input フィールドだけです。

始める前に：

1. hiapi アカウントを作成し、コンソールから API キーを取得します。キーは sk-... の形式です。
2. 公的にアクセス可能な画像 URL を用意します。API はサーバー側でこれを取得するため、localhost のパスやプライベートバケットは使用できません。
3. 実際（テスト以外）のリクエストを実行する前に、料金ページで veo-3.1-lite/image-to-video の現在の価格を確認してください。料金は長さと解像度によって変動します。

無料枠やキーなしモードはありません。すべての呼び出しに Authorization: Bearer sk-<your-key> が必要です。

最小限の動作例

hiapi のタスク API は 2 回の呼び出しで構成されます。タスクを作成し、その後ポーリングするか、コールバックで完了通知を受け取ります。以下はポーリング方式の Python コードで、requests と time のみを使用します：

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until it's done
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        video_url = task["output"][0]["url"]
        print("done:", video_url)
        break
    if status == "fail":
        raise RuntimeError(task.get("error"))
    time.sleep(5)

オンラインでの転送形式だけを確認したい場合は、同じ内容を生の curl で記述すると以下のようになります：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/image-to-video",
    "input": {
      "prompt": "the camera slowly pushes in as steam rises from the cup",
      "image_url": "https://example.com/your-reference-image.jpg",
      "duration": 6,
      "aspect_ratio": "16:9"
    }
  }'

# then poll:
curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-your-key-here"

input スキーマについて特に知っておくべき点があります。これは「何でも送れる」汎用エンドポイントよりも厳格で、余分なフィールドは黙って無視されるのではなく、直接拒否されます：

• prompt と image_url が必須の 2 つのフィールドです。image_url は単数形です。このモデルは参照画像を正確に 1 枚だけ受け付け、配列は受け付けません。
• duration は 4、6、8（秒）のみを受け付けます。他の整数は受け付けません。
• aspect_ratio は auto、16:9、9:16 を受け付けます。
• resolution は 720p または 1080p を受け付けます。
• オプションの追加項目：seed（整数、再現用）、generate_audio（ブール値）、negative_prompt（文字列）。

モデル id は裸の id、つまり veo-3.1-lite/image-to-video であることに注意してください。プレフィックスや名前空間を追加しないでください。

status が "success" になると、出力動画は data.output[0].url にあります。この URL は一時的（expireAt 付き）なので、ホットリンクを保存するのではなく、すぐにダウンロードするか再ホストしてください。

本番環境での注意点：コールバック、冪等性、エラー

5 秒ごとのポーリングはスクリプトなら問題ありませんが、多数のタスクを同時に処理するサーバーでは無駄が大きくなります。本番トラフィックではコールバックが推奨されます。タスク作成リクエストに callback オブジェクトを渡すと、hiapi は結果を問い合わせるのではなく、最終結果をあなたのエンドポイントに POST します。

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
    },
    "callback": {
        "url": "https://yourapp.example.com/hooks/hiapi",
        "when": "final",
    },
}

ここでの重要な設定は when: "final" です。これはタスクが終了状態（success または fail）に達したときに一度だけ通知することを意味し、中間状態が変わるたびに通知するわけではありません。webhook ハンドラーはタスク id を検証し、最初に POST /v1/tasks を呼び出したときに作成したローカルタスクレコードを照会する必要があります。

冪等性。 サービスがタスク作成呼び出しを再試行する可能性がある場合（タイムアウト、少なくとも 1 回の配信など）、最大 255 バイトの Idempotency-Key ヘッダーを付加してください：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Idempotency-Key: order-42-veo-submit" \
  -H "Content-Type: application/json" \
  -d '{...}'

同じアカウントで同じキーを使って再試行すると、2 つ目の（課金対象の）タスクを作成するのではなく、元の taskId が返されます。再試行ループから安全に発行でき、顧客に二重課金することはありません。

ポーリング vs. コールバック、簡潔に： スクリプト、notebook、低トラフィックの内部ツールの場合、結果をブロックして待つのが前提ならポーリングを使います。サーバー側で並行処理するあらゆるシナリオではコールバックを使います。接続を開いたままにせず、タスクごとにポーリングループを実行する必要なく、多数の進行中タスクにスケールできます。

エラー処理。 無効または取り消されたキーは HTTP 401 と error.code: "permission_denied" を返します。2xx 以外はすべて動画生成自体の失敗だと決めつけず、これを特別にチェックしてください。不正な input（prompt の欠落、duration の列挙範囲外、認識できないフィールド）は HTTP 400 と error_code: "INVALID_REQUEST" を返し、具体的な問題フィールドを示すメッセージが付きます。メッセージは何を修正すべきかを正確に示すので、握りつぶさず自分のログにそのまま表示する価値があります。タスクが受け入れられた後の生成側の失敗は、ポーリング/コールバックのペイロード上の status: "fail" と error オブジェクトとして現れます。メッセージが上流の一時的な問題を示している場合にのみ再試行可能とみなし、スキーマの問題とはみなさないでください。

関連リソース

• veo-3.1-lite/image-to-video モデルドキュメント——この特定モデルの完全なパラメータリファレンス
• タスクの作成 と タスク詳細の取得——本ガイドが構築される 2 つのエンドポイント
• 認証ドキュメント——キー形式とヘッダー要件
• Veo 3.1 Image-to-Video：ショート動画ガイド——非 lite モデルのより高忠実度な出力が必要な場合のユースケース解説
• 料金——持続時間と解像度ごとの現在の秒単価

よくある質問

image_url を data URI や base64 で渡す必要はありますか？ いいえ。image_url は hiapi サーバーが取得できる公的な HTTP(S) URL でなければなりません。このモデルは base64 エンコードされた画像を受け付けません。

参照画像なしで動画を生成できますか？ veo-3.1-lite/image-to-video ではできません。これは画像から動画を生成するモデルであり、image_url は必須です。テキストのみの生成が必要な場合は、テキストから動画を生成するモデルを使用してください。非 lite の Veo 3.1 モデルページに利用可能なモードが記載されています。

必須フィールドをすべて送信したのに、なぜまだ 400 が返るのですか？ 余分なフィールドがないか確認してください。このモデルの入力スキーマは、許可リスト（prompt、image_url、duration、aspect_ratio、resolution、seed、generate_audio、negative_prompt）にないものを拒否します。エラーメッセージは、認識できない正確なフィールドを示します。

生成には実際どのくらいかかりますか？ 持続時間と現在のキューの深さによって変わります。だからこそ、固定の待機時間を仮定するのではなく、短い間隔でのポーリングまたはコールバックが正しい方法です。

出力に音声を含めることはできますか？ はい、generate_audio ブール値で可能です。現在のデフォルト値と料金への影響についてはモデルドキュメントを参照してください。

タスク完了時にコールバックエンドポイントがダウンしていたらどうなりますか？ コールバックの到着だけに依存しないでください。作成呼び出しが返した taskId を保持し、妥当な時間枠内にコールバックを受信しなかった場合は、GET /v1/tasks/<id> のポーリングにフォールバックしてください。