チュートリアル

grok-imagine-1.5-lite テキストto動画 API の使い方（curl + Python）

Oct 21, 2026

一文のプロンプトから音声付きの短い動画を生成したいなら、grok-imagine-1.5-lite/text-to-video は hiapi 上で 1080P に到達できる最も安価な選択肢です。プロンプトを1つ受け取り、音声が既にミックスされた 1～15 秒の MP4 を返します。しかもプラットフォーム上の他のすべてのモデルと同じ統一タスク API 上で動作します。本ページでは、そのまま貼り付けて実行できるリクエスト、正確なスキーマ（仕様書から引いたものではなく、ライブエンドポイントで検証済み）、実際のレスポンスの見え方、そして私がテスト中に踏んだ落とし穴を示します。

以下の内容はすべて 2026-10-21 にライブ API に対して検証済みです。価格は私の実測値です。価格が変更されている場合は料金ページを優先してください。

1. 何を構築し、何を準備するか

目標：テキストプロンプトを送信し、ダウンロード可能で音声付きの MP4 クリップを受け取ること。

必要なものは1つだけです：hiapi API キー。コンソールで作成してサーバー側に保存してください。形式は sk-... で、Authorization: Bearer ヘッダーに入れます。キー不要の経路はありません。以下のすべてのリクエストは認証が必要です。

このモデルは非同期です。POST レスポンスで直接動画を取得することはできません。まずタスクを作成して taskId を取得し、その後ポーリング（またはコールバックを使用）してタスクが完了し出力 URL を返すまで待ちます。

2. 最小の動作例

2ステップ：タスクを作成し、結果をポーリングします。

タスクの作成（curl）

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5-lite/text-to-video",
    "input": {
      "prompt": "夜明け、新雪の上を歩くアカギツネ、吐く息が白く漂う、柔らかな朝の光、穏やかな環境音。シネマティック、自然な色彩。テキストなし。",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

構造に注意してください：model はトップレベルにあり、その他すべては input の下にネストされます。フィールドをフラットに送信すると（input のラッパーなし）、API はリクエストボディ全体を invalid input: must be a JSON object で拒否します。これが最もよくある間違いです。

作成に成功すると、すぐにタスク id が返されます：

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

結果のポーリング（Python）

import time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEAD = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def generate(prompt, duration=5, resolution="720p", aspect_ratio="16:9"):
    r = requests.post(BASE, headers=HEAD, json={
        "model": "grok-imagine-1.5-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # integer, 1–15
            "resolution": resolution,      # "480p" | "720p" | "1080p"
            "aspect_ratio": aspect_ratio,  # see schema below
        },
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    # Poll the SAVED task_id. A single transient network error is not a failure —
    # keep polling the same id rather than re-creating (re-creating bills again).
    deadline = time.time() + 300
    while time.time() < deadline:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEAD, timeout=30).json()
        except requests.RequestException:
            time.sleep(5); continue
        task = d.get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

print(generate("夜明け、新雪の上を歩くアカギツネ、穏やかな環境音。シネマティック。"))

スキーマ（ライブ検証済み）

フィールドは input 内に置きます。このスキーマはクローズドです——認識しない key はすべて 400 を返すため、seed、negative_prompt、motion_mode を送信しないでください（ここには存在しません。すべてのショットと動きの方向はプロンプトの表現で伝えます）。

フィールド	型	必須か	許容値
`prompt`	string	はい	自由テキスト
`duration`	integer	はい	1–15（整数秒。`5.5` は拒否されます）
`resolution`	string	—	`480p`、`720p`、`1080p`
`aspect_ratio`	string	—	`16:9`、`4:3`、`3:2`、`1:1`、`2:3`、`3:4`、`9:16`

このモデルにはauto アスペクト比はありません（画像to動画の同級モデルにはありますが、このテキストto動画エンドポイントにはありません）。比率を明示的に指定しない場合、モデルのデフォルト比率になります。

以下は完了したタスクの実際のレスポンスです：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB",
    "model": "grok-imagine-1.5-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      { "type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1793153637 }
    ]
  },
  "message": "success"
}

これはこのモデルが生成したクリップです（hiapi が grok-imagine-1.5-lite/text-to-video 向けに提供する参考出力で、ドキュメントのサンプルプロンプト「日の出、棚田の上を漂うガラスの熱気球」から生成）：

3. 本番運用に投入する

ポーリングの代わりにコールバックを使います。ポーリングはスクリプトには問題ありませんが、サーバーでは callback を追加してリクエストを開いたままにしなくて済むようにします。タスクが終端状態になると、プラットフォームがタスク詳細をあなたの URL に POST します：

{
  "model": "grok-imagine-1.5-lite/text-to-video",
  "input": { "prompt": "...", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your.app/hooks/hiapi", "when": "final" }
}

このタスクタイプでは、when は "final" のみを受け付けます。ハンドラー内で taskId により重複排除してください——コールバックは再試行される可能性があるため、ハンドラーを冪等に扱う必要があります。

出力 URL は期限切れになります。storage: "temp" と expireAt の unix タイムスタンプに注意してください——一時出力は temp.hiapi.ai 上に約 7 日間保存され、その後 404 を返します。ホットリンクを保存しないでください。タスク成功の瞬間にバイトをダウンロードするか、ストレージ転送エンドポイントを呼び出して TTL が切れる前に成果物を永久ストレージに移してください。

コストは出力秒数で計算されます。課金は duration とリクエストした解像度のみで決まります。テスト時：480P $0.029/s、720P $0.043/s、1080P $0.20/s。したがって 5 秒の 720P クリップは約 $0.215、5 秒の 1080P クリップは約 $1.00、1 秒の 480P クリップは約 $0.029 です。1080P の料金は 720P の約 5 倍です——その解像度が本当に必要な場合にのみ使用してください。最新の数値は料金ページをご覧ください。

エラー処理。拒否されたリクエストは HTTP 400 で返され、記録して対応できる正確なメッセージが付きます。検証はタスク作成前に行われるため、ここの 400 には課金されません。私が実際に発生させた実際のレスポンス：

invalid input: duration: maximum: got 999, want 15
invalid input: duration: minimum: got 0, want 1
invalid input: duration: got number, want integer
invalid input: resolution: value must be one of '480p', '720p', '1080p'
invalid input: aspect_ratio: value must be one of '16:9', '4:3', '3:2', '1:1', '2:3', '3:4', '9:16'
invalid input: prompt: missing required field "prompt"
invalid input: <root>: additional properties 'bogus_field' not allowed

タスクが受理された後に失敗した場合は、HTTP エラーではなく data.status: "fail" と詳細エンドポイントに data.error オブジェクトが付いて現れます——そのため status を確認し、ポーリングの HTTP ステータスコードに依存しないでください。

4. 私が実際に観察したこと

エンドツーエンドの流れ（スキーマだけでなく）を確認するため、実際に生成を1回実行しました：duration: 1、resolution: "480p"、aspect_ratio: "16:9"。

確かに動作し、課金もされる——POST は taskId を返し、タスクは実際の出力 URL で完了しました。1 秒クリップのサーバー側レンダリングには実際に約 51 秒かかりました。小さなクリップでも即時ではないため、ポーリングの期限を余裕を持って設定してください（私は 300 秒に設定）。
タスクは中間状態を経ます。status フィールドは handling → archiving → success の順に進みます。success と fail のみが終端状態です。archiving を完了とみなさないでください。
480P は 16:9 で 848×480 H.264 としてレンダリングされます。ダウンロードしたファイルに ffprobe を実行：H.264 ビデオストリーム（848×480）に加え、埋め込みの MJPEG サムネイルストリームがあります。この 495 KB のファイルは有効な MP4 です。
音声は常に組み込まれています。私のプロンプトが「穏やかな環境音」にしか言及していなくても、出力には AAC 音声トラックが含まれていました——モデルは一致する音声を合成して同じ MP4 にミックスします。別個の音声 URL も、無効にするスイッチもありません。無音クリップが必要な場合は自分で音声トラックを除去してください（ffmpeg -an）。

範囲の注記：私は API 契約、上記の3種類のエラー、および1回の 480P レンダリングを検証しました。720P/1080P の出力品質や長い（15 秒）時間についてのベンチマークは行っていないため、品質についての主張はしません——スキーマがそれらを受け付け、秒単位で課金されることのみ述べます。

5. Lite と標準 Grok Imagine 動画 API の比較

構築前に正しいエンドポイントを選んでください：

grok-imagine-1.5-lite/text-to-video（本ページ）：480P/720P/1080P、1～15 秒（したがって 1 秒や 2 秒のクリップも生成可能）、価格 $0.029～$0.20/s。hiapi がホストする唯一の 1.5 世代テキストto動画エンドポイントであり、1080P に到達できる唯一の Grok t2v ティアです。
grok-imagine/text-to-video（古い標準ティア、本ガイドを参照）：秒単位では安価（$0.0114～$0.0214/s）で Motion Modes も提供しますが、最高 720p までで、6～30 秒の時間が必要です——6 秒未満のクリップは生成できません。

したがって、ここでの「lite」は秒単位で最も安い選択肢ではありません。1080P と極短クリップを可能にするティアです。入力に単一の静止画像をテキストの代わりに使う場合は、同ティアの grok-imagine-1.5-lite/image-to-video エンドポイントを使用してください（価格は同じ、入力は image_urls）。

6. 関連リンク

よくある質問

ポーリングは必須ですか、それともコールバックがありますか？どちらでも可能です。スクリプトは GET /v1/tasks/{taskId} でポーリングします。サーバーは callback.url を付加し、when を "final" に設定します。taskId で重複排除してください。

なぜリクエストが 400 で「must be a JSON object」と返されるのですか？フィールドが input で包まれていません。リクエストボディは {"model": "...", "input": { ... }} でなければなりません。

音声をオフにできますか？リクエスト時にはできません——すべての出力にミックスされた AAC 音声トラックが含まれます。無音が必要な場合は、下流で ffmpeg -an を使って除去してください。

出力 URL の有効期間はどのくらいですか？expireAt（約 7 日）付きの一時 URL です。すぐにダウンロードするか、永久ストレージに転送してください。ホットリンクしないでください。

最も安い有効なリクエストは何ですか？480P で 1 秒あたり約 $0.029 です。バッチ処理の前に、キーに残高があることを確認するカナリアリクエストとして使うのが良い方法です。

重要なポイント

フィールドは input の下にネストされます。フラットなリクエストボディは「invalid input: must be a JSON object」を返します。
スキーマはクローズドでライブ検証済み：prompt（必須）、duration（整数 1-15）、resolution 480p/720p/1080p、aspect_ratio は 7 値の列挙で「auto」はありません。
テスト時の課金は出力秒数単位：480P $0.029/s、720P $0.043/s、1080P $0.20/s。duration のみで課金されます。
すべての出力にミックスされた AAC 音声トラックが含まれます。無効にするスイッチはありません（無音が必要なら ffmpeg -an で除去）。
出力 URL は一時的です（storage:temp、expireAt は約 7 日）。すぐにダウンロードするか永久ストレージに転送してください。
「Lite」は最も安いティアではありません。秒単位では古い標準 grok-imagine t2v より高価ですが、1080P と 6 秒未満のクリップが追加されます。