HiAPI
Ja
ブログ

チュートリアル

Grok Imagine API でテキストから動画を生成する方法：curl、Python、そして実行可能なリクエスト

Jul 3, 2026
Grok Imagine API でテキストから動画を生成する方法：curl、Python、そして実行可能なリクエスト
モデル
grok-imagine

Grok Imagine は xAI の動画生成モデルです。HiAPI は他のすべての生成モデルと同じ統一非同期エンドポイントを通じて、そのテキストから動画へのバリアントを公開しています：POST /v1/tasks。プロンプト（およびオプションの duration、mode、アスペクト比、解像度）を送信すると、すぐに taskId が返され、タスク完了後に .mp4 URL を取得できます。

本ガイドは実行可能なリクエストへの最短経路です：正確な入力スキーマ（フィールド名を間違えたときに遭遇する 400 エラーを含め、本番 API に対して検証済み）、そのままコピー＆ペーストできる curl フロー、ポーリング付きの小さな Python クライアント、そして本番環境で使用するコールバックパターンです。

何を構築するか、そして何が必要か

目標：grok-imagine/text-to-video を通じて、HTTP のみでテキストプロンプトを 6〜30 秒の動画クリップに変換すること。

必要なものは 1 つだけ：HiAPI API キーです。HiAPI ダッシュボードで作成してください。1 つのキーがすべてのモデルで共通に使えるため、すでに HiAPI で画像モデルを呼び出している場合、同じキーがここでもそのまま使えます。リクエストは標準の bearer ヘッダーで認証します：

Authorization: Bearer sk-<your-key>

入力スキーマ（コードを書く前に）

タスク API はモデルごとに input を厳格に検証します。未知のフィールドは黙って無視されるのではなく、400 で拒否されます。以下が grok-imagine/text-to-video の完全なスキーマです：

フィールド 型 必須 値 デフォルト
prompt string はい 最大 5000 文字、英語が最適 —
duration integer いいえ 6–30（秒） 6
mode enum いいえ fun、normal normal
aspect_ratio enum いいえ 2:3、3:2、1:1、16:9、9:16 2:3
resolution enum いいえ 480p、720p 480p

事前に知っておくべき点が 3 つあります：

  • mode は「モーションモード」の切り替えです。 normal はバランス型、fun はよりクリエイティブで誇張された動きを生成します。Grok Imagine のモードが他の場所で別の名前で説明されていても、API パラメータは mode です。motion_mode のようなものを送ると 400 additional properties 'motion_mode' not allowed が返ります。
  • duration はコストに線形に影響します。 Grok Imagine は出力秒数で課金されるため、30 秒クリップのコストは 6 秒クリップの 5 倍です。現在の秒単価は HiAPI 料金ページを参照してください。
  • デフォルトのアスペクト比は 2:3（縦向き）です。 ワイドスクリーンが必要な場合は 16:9 を明示的に渡してください。これはデフォルトが横向きのモデルから移行してきたユーザーがつまずくポイントです。

範囲外の値は説明的なメッセージとともに即座に失敗します。例えば duration: 31 は次を返します：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

最小の実行可能な例：curl

2 回の呼び出し：タスクを作成し、それをポーリングします。

1. タスクを作成：

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

モデル id は裸の文字列 grok-imagine/text-to-video であることに注意してください。プロバイダーのプレフィックスもバージョンサフィックスもありません。

2. 終了状態までポーリング：

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

.mp4 URL は一時的です。expireAt は約 1 週間後の Unix タイムスタンプです。タスク成功後すぐにバイトをダウンロードして自分で永続化してください。ユーザー向けのあらゆる場所から temp.hiapi.ai URL をホットリンクしないでください。（出力リンクの失効に遭遇したことがあるなら、原因はこれです。hiapi 出力 URL の有効期限切れ：期限前にダウンロードしてくださいを参照。）

Python：小さなポーリングクライアント

同じフローの再利用可能なスクリプト：作成、期限付きポーリング、ダウンロード：

# pip install requests
import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


def wait_task(task_id: str, timeout_s: int = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

6 秒クリップは通常、上記の 15 分の期限よりはるかに早く完了します。より長い duration は比例して時間がかかるため、30 秒タスクではこの余裕のあるタイムアウトを維持してください。

本番環境での注意点

ポーリングの代わりにコールバックを使う。 スクリプト以外のあらゆる用途では、作成時にトップレベルの callback オブジェクトを渡すと、HiAPI が終了状態のタスク状態をあなたのエンドポイントに POST します。ポーリングループを監視する必要はありません：

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when は "final" のみを受け付けます（タスクが success または fail に達したときに 1 回 POST を受け取ります。増分の進捗ではありません）。経験則：ポーリングは CLI、バッチジョブ、その他短命なシナリオに適しています。コールバックは Web バックエンドに適しています。そうでなければ、数分間のレンダリングでワーカープロセスの容量が占有されてしまいます。コールバックエンドポイントに何も届かないように見える場合は、hiapi タスクコールバックが発火しない理由を調査してください。

冪等性。 タスク作成は冪等ではありません。タイムアウトした作成リクエストを再試行すると、2 つの課金タスクが生成される可能性があります。taskId を取得した瞬間に記録し、曖昧な失敗（作成時のネットワークタイムアウト）が発生した場合は、再送信する前にタスク履歴を確認してください。duration は秒単位で課金されるため、30 秒タスクの重複は高コストな種類の重複です。

エラー処理。 実際に遭遇する 2 種類のエラー：

  • スキーマ 400 エラー（error_code: "INVALID_REQUEST"）——フィールド名の誤り、duration の範囲外、無効な enum 値。これらは決定的です。リクエストを修正し、再試行しないでください。
  • 認証失敗——無効なキー、またはこのモデルへのアクセス権がないキーは 401 を返し、"code": "permission_denied" とメッセージ "This API key cannot use the selected model." が付きます。ダッシュボードでキーを確認し、そのモデルが有効化されていることを確認してください。
  • タスクレベルの失敗——作成は成功したものの、タスクがその後 status: "fail" で終了状態になり、error オブジェクト（コンテンツポリシー、上流の容量）が付く場合。これらはバックオフ付きで 1 回再試行する価値があります。タスクが handling でスタックしているように見える場合は、ハングまたはタイムアウトした /v1/tasks ジョブの診断を参照してください。

次のステップ

よくある質問

Grok Imagine API とは何ですか、どうやってアクセスしますか？ Grok Imagine は xAI の動画生成モデルです。HiAPI を通じて、単一の HiAPI キーを使って統一された POST /v1/tasks エンドポイントで grok-imagine/text-to-video として呼び出します。別途 xAI アカウントや SDK は不要です。

Grok Imagine の動画はどれくらいの長さにできますか？ duration は 6〜30 秒の整数を受け付けます（デフォルト 6）。この範囲外の値は作成時に 400 で拒否され、課金は出力秒数に基づきます。

fun モードと normal モードの違いは何ですか？ normal（デフォルト）はバランスの取れたリアルな動きを提供します。fun はよりクリエイティブで誇張された動きを好みます。これは API が公開する唯一のモーションスタイル切り替えであり、リクエストごとに選択します（アカウント単位ではありません）。

grok-imagine/text-to-video は 1080p に対応していますか？ 現在は対応していません。resolution は 480p（デフォルト）または 720p を受け付けます。より高い出力解像度が必要な場合は、ダウンストリームでアップスケールするか、モデルページで他の動画モデルを比較してください。

Grok Imagine を使って既存の画像をアニメーション化できますか？ このモデルではできません。テキストのみをサポートしています。同じタスクエンドポイント上に画像入力を受け付ける別の grok-imagine/image-to-video モデルがあり、非同期ライフサイクル（作成 → ポーリング/コールバック → ダウンロード）はまったく同じです。

Grok Imagine API に無料枠はありますか？ 生成は動画秒数に応じて HiAPI 残高から課金されます。キー不要の無料エンドポイントはありません。現在の料金は料金ページを参照してください。この分野での「無料」が現実的にどのようなものかについては、この無料テキストから動画 API 比較がさまざまな選択肢をカバーしています。

タグチュートリアル動画レシピ

関連記事

すべての記事を見る →

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

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

APIドキュメントを読む