HiAPI
Ja
ブログ

チュートリアル

hiapi API で veo-3.1-lite/text-to-video を使う方法：curl、Python、そして実行可能なリクエスト

Aug 27, 2026
hiapi API で veo-3.1-lite/text-to-video を使う方法：curl、Python、そして実行可能なリクエスト

veo-3.1-lite/text-to-video はテキストプロンプトだけで短い動画クリップを生成します——開始画像は不要です。このガイドでは、実際の hiapi タスク API に対するコピー＆ペースト可能な curl と Python の例、正確な入力スキーマ（オンラインのエンドポイントで確認済み）、そして本番環境で実際に遭遇するエラーの形を提供します。

1. 前提条件

  • hiapi アカウントと、API Keys ダッシュボード から取得した API key（sk-...）。
  • curl、または requests がインストールされた Python 3（pip install requests）。
  • それ以外は何も不要——text-to-video にはプロンプト文字列が 1 つあれば十分です。

hiapi 上のすべての生成モデルは同じ 統一された非同期タスク API を通じて動作します：POST /v1/tasks でタスクを作成し、その後ポーリングするかコールバックを待って結果を取得します。veo-3.1-lite/text-to-video の呼び出し方は他のどの動画モデルともまったく同じです——同じ認証ヘッダー、同じタスクライフサイクル——異なるのは model と input だけです。モデル id は /text-to-video サフィックスが付いた veo-3.1-lite/text-to-video です。同じシリーズには veo-3.1-lite/image-to-video もあり、これはソース画像をアニメーション化するための独立したモデル id です。

2. 最小限の実行可能な例

2.1 タスクの作成（curl）

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "input": {
      "prompt": "a paper boat drifting down a rain-slicked city street at night, neon signs reflecting on wet asphalt",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'

呼び出しが成功するとすぐにタスク id が返されます——生成は非同期で行われます：

{"code":200,"data":{"taskId":"tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX"},"message":"success"}

2.2 結果のポーリング

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX \
  -H "Authorization: Bearer sk-<your-api-key>"

クリップのレンダリング中は、status が "handling" です。完了すると：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX",
    "model": "veo-3.1-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      {"artifactId": "...", "type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786932195}
    ]
  },
  "message": "success"
}

output[0].url は一時的な、期限切れになるリンクです——expireAt が切れる前にファイルをダウンロードしてください（または出力を永続ストレージに移してください）。

2.3 完全な Python の例

import time
import requests

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


def create_task(prompt: str) -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "veo-3.1-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": 6,
            "resolution": "720p",
            "aspect_ratio": "16:9",
        },
    }, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, poll_seconds: int = 5, timeout_seconds: int = 600) -> str:
    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(poll_seconds)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_seconds}s")


if __name__ == "__main__":
    tid = create_task("a paper boat drifting down a rain-slicked city street at night")
    video_url = wait_for_result(tid)
    print(video_url)

3. 入力スキーマ

以下のすべてのフィールドは input の下に置きます。このスキーマは厳格です——存在しないフィールドを送ると 400 が返されます（additional properties '<field>' not allowed）。これはレンダリング前にリクエストを素早く検証する良い方法です。

フィールド 型 必須 説明
prompt string はい シーンの説明。被写体、動き、カメラの挙動を具体的に指定してください。
duration integer いいえ 4、6、8 のいずれか（秒）。
resolution string いいえ "720p" または "1080p"。
aspect_ratio string いいえ "16:9" または "9:16"。
generate_audio boolean いいえ 同期した環境音/効果音をレンダリングに含めます。
negative_prompt string いいえ レンダリングで避けたい内容要素。
seed integer いいえ 固定値。リトライ間で同じ構図/動きを再現するために使用します。

長い時間と高い解像度はどちらもレンダリングコストを増やします——大量タスクにスケールする前に、料金ページ で現在のモデル別課金価格を確認してください。

4. 本番環境のパターン

大規模な場面ではポーリングよりコールバックを優先する

使い捨てスクリプト以外のあらゆる場面では、ループでポーリングするのではなくコールバックを登録してください：

{
  "model": "veo-3.1-lite/text-to-video",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-app.example.com/webhooks/hiapi", "when": "final"}
}

callback.url はアクセス可能な http(s) URL である必要があり、when は "final" のみを受け付けます——hiapi はタスクが終状態（success または failed）に達したときに 1 回 POST します。これによりポーリングループにリクエスト枠を浪費せず、結果の準備ができた瞬間に受け取れます。これは動画ではより重要です（レンダリング時間が画像生成より長いため）。

冪等性とリトライ

タスクランナーが送信をリトライする可能性がある場合（クラッシュ、タイムアウト、再デプロイ）、リクエストを送る前に独自の冪等キーを返された taskId と一緒に記録しておき、リトライ時に「これをすでに送信したか？」を確認できるようにしてください。そうすれば重複レンダリングを作成して二重に支払うことを避けられます。

エラーハンドリング

実際には 2 種類の異なるエラーの形が現れます：

  • 入力の誤り（400）——リクエストボディの検証エラー：
    {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}
  • 認証/権限の失敗（401）——キーの欠落、無効、または権限不足：
    {"error":{"code":"permission_denied","message":"This API key cannot use the selected model...","request_id":"...","type":"hiapi_error"}}

まず HTTP ステータスコードで分岐し、次にレスポンスボディを確認してください——400 はほぼ常にフィールド名または値の誤りを意味し（リクエストを修正）、401 はキー自体に対処が必要（ダッシュボードの権限または新しいキー）であることを意味します。

5. 関連ページ

よくある質問

veo-3.1-lite/text-to-video には開始画像が必要ですか？ いいえ。完全に prompt 文字列から生成します。アニメーション化したいソース画像がある場合は、独立した veo-3.1-lite/image-to-video モデル id を使用してください。

どの解像度と時間がサポートされていますか？ resolution は "720p" または "1080p"、duration は 4、6、8 秒です。それ以外の値を送ると 400 が返され、許可される値の集合が示されます。

生成されたクリップに音声を付けられますか？ はい——input に "generate_audio": true を設定すると、同期した環境音/効果音を含められます。

ループ内のポーリングを避けるにはどうすればよいですか？ webhook の url と "when": "final" を含む callback オブジェクトを渡してください。タスク完了時に hiapi がその URL に POST するため、GET /v1/tasks/<id> を定期的に再確認する必要はありません。

なぜリクエストが 400 ではなく 401 を返すのですか？ 401 かつ error_code/code が "permission_denied" の場合、API key 自体が無効か、そのモデルへのアクセス権限がないことを意味します——API Keys ダッシュボード を確認してください。400 は、有効な key に対してリクエストボディの形式が誤っていることを意味します。

返された動画 URL は永続的ですか？ いいえ——output[0].url は expireAt タイムスタンプ付きの一時リンクです。期限切れ前にダウンロードするか、永続ストレージに移してください。

タグveoテキストから動画APIチュートリアル動画生成hiapi

関連記事

すべての記事を見る →

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む