Grokテキストから動画APIの使い方【完全ガイド】

要するに

Grokのテキスト-to-ビデオAPIは、テキストプロンプトからビデオを生成します。`POST /v1/videos/generations`を呼び出すと、すぐに`request_id`が返され、ステータスが`"done"`になるまで`GET /v1/videos/{request_id}`をポーリングします。モデルは`grok-imagine-video`で、料金は480pで1秒あたり0.05ドルから始まります。xAI Python SDKはポーリングを自動的に処理します。

はじめに

xAIは2026年1月だけで12億本のビデオを生成しました。これは、2026年1月28日にGrokのテキスト-to-ビデオAPIをリリースして最初の1ヶ月でした。このモデルは同月、Artificial Analysisのテキスト-to-ビデオリーダーボードでも1位を獲得しました。これらの数字は、インフラストラクチャが大規模で実績があることを示しているため重要です。

このガイドでは、最初のリクエストの作成、結果のポーリング、パラメータの調整、より良いプロンプトの記述まで、すべての手順を説明します。また、参照画像の使用方法、既存ビデオの延長または編集方法、そしてテキスト-to-ビデオが適切な選択である時期についても学びます。

💡

APIは非同期です。つまり、フロントエンドはビデオの準備ができるまで何もレンダリングできません。ビデオ生成UIを構築している場合、テスト実行ごとにクレジットを消費することなく、ポーリングフローに対して開発する方法が必要です。ApidogのSmart Mockを使用すると、生成エンドポイントとポーリングエンドポイントの両方をモックできます。バックエンドがまだ開発中の間でも、チームはビデオプレーヤーUIを構築できます。このガイドの後半にあるテストセクションに沿って進めるために、Apidogを無料でダウンロードしてください。

button

Grokテキスト-to-ビデオAPIとは？

Grokテキスト-to-ビデオAPIは、`https://api.x.ai`にあるxAIのメディア生成スイートの一部です。テキストプロンプトを送信すると、`grok-imagine-video`モデルがゼロから短いビデオクリップを生成します。ソース画像は必要ありません。

このAPIは、同期画像生成エンドポイント（`POST /v1/images/generations`、モデル`grok-imagine-image`、画像あたり0.02ドル）と並んで存在します。また、ビデオの延長または編集用のエンドポイントも含まれています。

テキスト-to-ビデオエンドポイントは、画像-to-ビデオエンドポイントとは根本的に異なります。テキスト-to-ビデオでは言葉のみを提供します。モデルはあなたの説明からシーン、動き、視覚スタイルを完全に作成します。ソース画像があり、モデルにそれをアニメーション化させたい場合は、Grok画像-to-ビデオAPIガイドを参照してください。

テキスト-to-ビデオ生成の仕組み（非同期パターンを簡単に解説）

ほとんどのAPI呼び出しは同期型です。リクエストを送信し、少し待つとレスポンスが返されます。ビデオ生成には数秒から数分かかるため、このAPIでは非同期パターンを使用します。

これがそのフローです。

プロンプトとともにPOSTリクエストを送信します。
APIはすぐに（1秒以内に）`request_id`を返します。
ビデオはxAIのサーバーで生成されています。
その`request_id`を使用してGETエンドポイントを繰り返しポーリングします。
ステータスが`"processing"`から`"done"`に変わると、レスポンスにビデオURLが含まれます。

このパターンはAIメディアAPIでは一般的です。これによりHTTP接続が短く保たれ、自分のペースで進捗状況を確認できます。難しいのは、フロントエンドが中間状態を処理し、ビデオURLが届くまでローディングインジケーターを表示する必要があることです。

前提条件

コードを記述する前に、2つのものが必要です。

xAIアカウント。console.x.aiで作成してください。APIキーが生成アクセス権を持つ前に、そこで課金設定も追加する必要があります。

APIキー。xAIコンソールでAPIキーに移動し、新しいキーを作成します。安全な場所にコピーしてください。すべてのリクエストヘッダーでBearerトークンとして渡します。

ハードコーディングしないように、環境変数として設定してください。

export XAI_API_KEY="your_api_key_here"

オプションで、最も簡単な統合のためにxAI Python SDKをインストールしてください。

pip install xai-sdk

初めてのテキスト-to-ビデオリクエスト

エンドポイントは`POST https://api.x.ai/v1/videos/generations`です。必須フィールドは`model`と`prompt`のみです。

curlを使用する

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
  }'

レスポンスはすぐに返されます。

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

そのUUIDは、ビデオの準備ができ次第取得するためのチケットです。

requestsライブラリを使ったPythonの使用

import requests
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "grok-imagine-video",
    "prompt": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
}

response = requests.post(
    f"{BASE_URL}/v1/videos/generations",
    headers=headers,
    json=payload
)

data = response.json()
request_id = data["request_id"]
print(f"Generation started. Request ID: {request_id}")

ビデオ結果のポーリング

`request_id`を取得したら、ステータスフィールドが`"done"`になるまで`GET /v1/videos/{request_id}`をポーリングします。

ステータスフィールドには3つの可能な値があります。- `"processing"`: 生成中 - `"done"`: 完了、ビデオURLが利用可能 - `"failed"`: 何らかのエラーが発生

完全なPythonポーリングループは次のとおりです。

import requests
import time
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

def poll_video(request_id: str, interval: int = 5, max_attempts: int = 60) -> dict:
    """Poll until video generation is complete."""
    url = f"{BASE_URL}/v1/videos/{request_id}"

    for attempt in range(max_attempts):
        response = requests.get(url, headers=headers)
        data = response.json()

        status = data.get("status")
        progress = data.get("progress", 0)
        print(f"Attempt {attempt + 1}: status={status}, progress={progress}%")

        if status == "done":
            return data
        elif status == "failed":
            raise RuntimeError(f"Video generation failed: {data}")

        time.sleep(interval)

    raise TimeoutError(f"Video not ready after {max_attempts} attempts")


# Full workflow: generate then poll
def generate_video(prompt: str) -> str:
    """Generate a video and return its URL."""
    response = requests.post(
        f"{BASE_URL}/v1/videos/generations",
        headers={**headers, "Content-Type": "application/json"},
        json={"model": "grok-imagine-video", "prompt": prompt}
    )
    request_id = response.json()["request_id"]
    print(f"Request ID: {request_id}")

    result = poll_video(request_id)
    video_url = result["video"]["url"]
    print(f"Video ready: {video_url}")
    return video_url


video_url = generate_video(
    "A timelapse of a city skyline at sunset transitioning to night, aerial view"
)

完了すると、完全なポーリングレスポンスは次のようになります。

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 500000000
  }
}

xAI Python SDKの使用

手動でのポーリングをスキップしたい場合は、xAI SDKがそれを処理します。`client.video.generate()`メソッドは、ビデオの準備が整うまでブロックします。

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

result = client.video.generate(
    model="grok-imagine-video",
    prompt="A golden retriever running through autumn leaves in slow motion",
    duration=8,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {result.video.url}")
print(f"Duration: {result.video.duration}s")

SDKは、動作するコードへの最短経路です。リトライロジック、進捗更新、またはカスタムポーリング間隔をより細かく制御する必要がある場合は、生のrequestsアプローチを使用してください。

ビデオ生成のための効果的なプロンプトの記述

プロンプトは最も重要な入力です。詳細で構造化されたプロンプトは、曖昧なものよりもはるかに良い結果を生み出します。

シーンの記述

被写体と設定を一緒に記述してください。何が見えるのかを具体的にしてください。「雨に濡れた窓の横の木製テーブルに置かれた白いセラミックのコーヒーマグ」は、「コーヒーマグ」よりも現実的なシーンを生成します。

動き

モデルに何がどのように動くかを伝えます。「湯気が立ち上るマグカップの周りをカメラがゆっくりと旋回する」という記述は、明確な方向性を持った動きを加えます。明示的な動きの指示がない場合、モデルは最小限またはぎこちない動きを生成する可能性があります。

カメラのスタイル

撮影監督に指示するようなカメラ用語を使用してください：「クローズアップ」、「トラッキングショット」、「オーバーヘッドドローンビュー」、「手持ち」、「ドリーズーム」など。これらの指示は、生成される映像に確実に反映されます。

ライティングとムード

「ゴールデンアワー」、「曇り」、「ネオンライト」、「スタジオ3点照明」はすべて異なる外観を生み出します。ライティングとムードを組み合わせることで、「霧深い朝、憂鬱な雰囲気」は、色温度を超えたトーンのガイダンスをモデルに与えます。

スタイル参照

心に描いているビジュアルスタイルがあれば、その名前を挙げてください。「シネマティック」、「ドキュメンタリー」、「アニメ」、「ストップモーション」、「ハイパーラプス」など。2つのスタイルを組み合わせると、しばしば興味深い結果が生まれます。

効果的なプロンプトの構造

被写体から始め、動きを加え、カメラを記述し、スタイルとムードで締めくくります。次のようにです。

A lone astronaut floats past the International Space Station,
tether drifting behind them. The camera tracks slowly
alongside, showing Earth below. Cinematic, IMAX quality,
warm sunrise light reflecting off the visor.

解像度、持続時間、アスペクト比の制御

生成エンドポイントは、出力の寸法、長さ、品質を制御できるいくつかのオプションパラメータを受け入れます。

持続時間

"duration": 10

範囲：1～15秒。デフォルトは6秒です。ビデオが長くなると料金が高くなります。480pの10秒クリップは0.50ドルかかります。

解像度

"resolution": "720p"

2つのオプション：「`480p`」（デフォルト）と「`720p`」があります。プロトタイピングとテストには480pを使用してください。品質が重要な本番出力には720pを使用してください。

アスペクト比

"aspect_ratio": "9:16"

利用可能な比率：

比率	最適用途
`16:9`	デスクトップ、YouTube、プレゼンテーション（デフォルト）
`9:16`	TikTok、Instagramリール、モバイル
`1:1`	Instagramフィード、ソーシャルカード
`4:3`	クラシックビデオ、プレゼンテーション
`3:4`	ポートレートモバイルコンテンツ
`3:2`	標準写真比率
`2:3`	ポートレート写真

すべてのパラメータを使用した完全な例

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A coastal town at dawn, waves breaking gently on a rocky shore",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

ビデオスタイルをガイドするための参照画像の使用

`reference_images`パラメータは、最大7つの画像URLの配列を受け入れます。これらの画像は、生成されるビデオのビジュアルスタイルとコンテンツをガイドしますが、その主題となるわけではありません。

{
  "model": "grok-imagine-video",
  "prompt": "A coastal town at dawn, waves breaking gently on a rocky shore",
  "reference_images": [
    {"url": "https://example.com/my-style-reference.jpg"},
    {"url": "https://example.com/color-palette-reference.jpg"}
  ]
}

参照画像は、一貫した美的感覚を共有している場合に最も効果的です。異なるビジュアルスタイルの3つの画像を提供すると、モデルはそれらを調整しようとし、出力に一貫性がなくなる可能性があります。最も強力なガイダンスを得るには、統一された外観を持つ緊密な画像セットを使用してください。

参照画像は画像-to-ビデオエンドポイントとは異なります。参照画像の場合、プロンプトが依然としてシーンを駆動します。画像はカラーグレーディング、構図スタイル、視覚的なテクスチャに影響を与えます。画像-to-ビデオの場合、ソース画像がビデオの最初のフレームになります。

生成されたビデオの延長と編集

xAIは、すでに生成したビデオを操作するための2つの追加エンドポイントを提供します。

ビデオを延長する

`POST /v1/videos/extensions`は、既存の生成済みビデオにさらに映像を追加します。元のビデオの`request_id`と、延長用の新しいプロンプトを渡します。これは、単一の呼び出しで15秒の制限に達することなく、より長いシーケンスを作成するのに役立ちます。

ビデオを編集する

`POST /v1/videos/edits`は、テキスト指示に基づいて既存のビデオを変更します。スタイルを変更したり、シーンを修正したり、すでに生成したクリップにエフェクトを適用したりできます。

どちらのエンドポイントも、メインの生成エンドポイントと同じ非同期パターンに従います。`request_id`を返し、結果を得るために`GET /v1/videos/{request_id}`をポーリングします。

APIレスポンスからのコストの読み取り

完了したポーリングレスポンスには`usage`オブジェクトが含まれます。

"usage": {
  "cost_in_usd_ticks": 500000000
}

単位はUSDティックです。10,000,000で割るとドルに変換されます。

cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Cost: ${cost_in_usd:.4f}")
# Output: Cost: $0.0500

料金表

解像度	1秒あたりの料金	10秒クリップ
480p	$0.05	$0.50
720p	$0.07	$0.70

`500000000`ティックの値は0.50ドルに相当します。これは480pでの10秒クリップです。

完了したすべてのレスポンスから`cost_in_usd_ticks`をログに記録することでコストを追跡できます。これにより、xAIの課金APIを別途呼び出すことなく、使用状況ダッシュボードを構築できます。

ApidogでGrokビデオAPIをテストする方法

非同期ポーリングパターンは、特定のテスト上の課題を生み出します。フロントエンドコードは、読み込み中（ポーリング中）、成功（ビデオURL受信済み）、エラーの3つの状態を処理する必要があります。実際のAPI呼び出しを行うことで3つの状態すべてをテストすることはできません。なぜなら、各呼び出しには時間とコストがかかるからです。ここでApidogのSmart Mock機能がこの問題を直接解決します。

ApidogのSmart Mock機能がビデオ生成のモックレスポンスを表示しているスクリーンショット

ユースケース1：フロントエンド開発のためのSmart Mock

ApidogのSmart Mockを使用すると、両方のエンドポイントのスキーマを定義でき、Apidogはリアルな偽のレスポンスを即座に返します。

生成エンドポイントのモック：

Apidogで、プロジェクト内に`POST /v1/videos/generations`エンドポイントを作成します。`request_id`という単一の文字列フィールドを持つレスポンススキーマを定義します。Smart Mockは、フィールド名のパターンに基づいて自動的に偽のUUIDを返します。

モックされたレスポンス：

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

ポーリングエンドポイントのモック：

Apidogで`GET /v1/videos/{request_id}`を作成します。`status`、`video.url`、`video.duration`、`progress`、`usage.cost_in_usd_ticks`を含む完全なレスポンススキーマを定義します。プレースホルダーのMP4 URLとともに`"status": "done"`を返すカスタムモックレスポンスを設定します。

モックされたポーリングレスポンス：

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/mock-video-12345.mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 400000000
  }
}

フロントエンド開発者は、このモックサーバーに対してビデオプレーヤーUI全体を構築およびテストできます。読み込み状態、完了状態を確認し、モックを`"status": "failed"`を返すように変更することでエラー状態をトリガーできます。開発中に実際のAPIクレジットが消費されることはありません。

ユースケース2：ポーリングループのテストシナリオ

統合が構築されたら、Apidogのテストシナリオを使用して、完全な生成-ポーリングフローを自動的に検証します。

ステップ1：生成リクエストを追加します。 `POST /v1/videos/generations`をテストシナリオの最初のステップとして追加します。ポストプロセッサで、JSONPath式`$.request_id`を使用してレスポンスボディから`request_id`をキャプチャする抽出変数を追加します。それを`videoRequestId`という名前の変数に保存します。

ステップ2：ポーリングループを追加します。 `GET /v1/videos/{{videoRequestId}}`を2番目のステップとして追加します。`response.body.status == "done"`というブレーク条件を持つForループでそれをラップします。レート制限の打ち込みを避けるために、繰り返しごとに5秒の待機プロセッサを追加します。

ステップ3：結果をアサートします。ループ終了後、最終的なGETリクエストにアサーションプロセッサを追加します。`$.video.url`が空でないことをアサートします。これにより、完全なサイクルが正常に完了したことを確認します。

このテストシナリオは、非同期フローの繰り返し可能で自動化されたカバレッジを提供します。ポーリングロジックが変更された際の退行を検出するために、CIで実行してください。

テキスト-to-ビデオ vs 画像-to-ビデオ：いつどちらを使うべきか

どちらのモードも同じ`grok-imagine-video`モデルを使用しますが、異なる目的を果たします。

テキスト-to-ビデオを選択する場合：- コンセプトやスクリプトからオリジナルコンテンツを生成している場合 - モデルに構図の完全なクリエイティブな制御を与えたい場合 - ユーザーがプロンプトを入力するコンテンツ生成ツールを構築している場合 - 開始するためのソース画像がない場合

画像-to-ビデオを選択する場合：- アニメーション化する製品写真、イラスト、またはブランドアセットがある場合 - 既存の画像からの特定の視覚的詳細を維持する必要がある場合 - 一連の関連画像から一貫したアニメーションを作成している場合 - あなた自身の作品や写真をアニメーション化したい場合

重要な区別：テキスト-to-ビデオはゼロからシーンを作成します。画像-to-ビデオは既存の画像を動かします。画像-to-ビデオのアプローチの詳細については、Grok画像-to-ビデオAPIガイドを参照してください。

両方のモードを提供する製品を構築しているチームの場合、実行時に入力タイプを検出できます。ユーザーが画像をアップロードした場合は、`POST /v1/images/generations`（画像-to-ビデオ）にルーティングします。プロンプトのみを入力した場合は、`POST /v1/videos/generations`にルーティングします。

一般的なエラーとその修正方法

401 UnauthorizedAPIキーが見つからないか、期限切れか、形式が正しくありません。Authorizationヘッダーが余分なスペースなしで正確に`Bearer YOUR_XAI_API_KEY`であることを確認してください。xAIコンソールでキーがアクティブであることを確認してください。

429 Too Many Requestsレート制限に達しました。APIは1分あたり60リクエスト、1秒あたり1リクエストを許可しています。リクエスト間に遅延を追加してください。ポーリングしている場合は、呼び出し間隔を少なくとも5秒空けてください。

ポーリングレスポンスで status: "failed"生成が失敗しました。これは通常、プロンプトがコンテンツモデレーションによって拒否されたことを意味します。モデレーションが適用された場合、レスポンス内の`respect_moderation`フィールドは`true`になります。プロンプトを曖昧さを減らすか、潜在的に不適切な言葉を削除して修正してください。

ビデオURLが404を返す生成されたビデオURLは一定期間後に期限切れになります。URLを取得したらすぐに、ビデオを独自のストレージにダウンロードしてください。URLを保存して、数日後も利用可能であると期待しないでください。

空白またはフリーズしたビデオ曖昧なプロンプトや動きの指示がないプロンプトは、最小限の動きしかしないビデオを生成することがあります。プロンプトに明確な動きの言語を追加してください：何がどの方向に、どの速度で動くかを記述します。

ポーリングに時間がかかる720pビデオは480pよりも生成に時間がかかります。持続時間が長いほど時間もかかります。開発やプロトタイピングには、`"resolution": "480p"`と短い持続時間を使用して、イテレーションサイクルを高速化してください。

まとめ

Grokテキスト-to-ビデオAPIは、テキストからビデオへの簡単なパスを提供します。プロンプトを送信し、`request_id`を取得し、完了するまでポーリングして、MP4をRetrieveします。非同期パターンが理解すべき重要な概念です。ポーリングループが機能し始めれば、残りのパラメータ（持続時間、解像度、アスペクト比、参照画像）は簡単に調整できます。

本番ビルドの場合、完了したすべてのレスポンスから`cost_in_usd_ticks`を読み取ってコスト追跡を追加してください。開発中にApidogで両方のエンドポイントをモックすることで、フロントエンドチームが実際の生成を待ってブロックされることがなくなります。テストシナリオを使用して、統合の進化に合わせてポーリングロジックの信頼性を維持してください。

GrokビデオAPIのモックサーバーとテストシナリオをセットアップするために、Apidogを無料でダウンロードしてください。

button

よくある質問

テキスト-to-ビデオ生成にはどのモデル名を使用しますか？ `grok-imagine-video`を使用してください。これは`/v1/videos/generations`へのPOSTリクエストで必須の`model`フィールドです。

ビデオ生成にはどれくらい時間がかかりますか？持続時間と解像度によって異なります。短い480pクリップは30秒未満で完了する場合があります。長い720pクリップは数分かかることがあります。エンドポイントを継続的に打ち込むのではなく、5〜10秒ごとにポーリングしてください。

15秒より長いビデオを生成できますか？単一のリクエストではできません。最大`duration`は15秒です。より長いビデオを作成するには、クリップを生成し、`POST /v1/videos/extensions`を使用してさらに映像を追加してください。

生成されたビデオはどのようにダウンロードしますか？完了したポーリングレスポンスの`result.video.url`からURLを使用します。MP4をすぐにストレージにダウンロードしてください。URLは一時的なものであり、期限切れになります。

プロンプトがコンテンツモデレーションに違反した場合どうなりますか？ジョブは完了しますが、`status`は`"failed"`になります。ポーリングレスポンスの`respect_moderation`フィールドは、モデレーションが適用されたことを示します。プロンプトを修正して再試行してください。

ビデオAPIに無料枠はありますか？xAIは生成された出力の1秒あたりで課金されます。ビデオ生成に特化した無料枠はありません。新規アカウント向けの現在のクレジットオファーについては、console.x.aiを確認してください。

`reference_images`はソース画像から開始するのとどう違いますか？参照画像はテキスト-to-ビデオ生成の視覚スタイルをガイドします。それらは主題となることなく外観に影響を与えます。画像-to-ビデオのソース画像は、ビデオの実際の最初のフレームになります。

クレジットを消費せずにポーリングループをテストする最良の方法は何ですか？ApidogのSmart Mockを使用して、生成エンドポイントとポーリングエンドポイントの両方をモックしてください。スキーマを定義し、`"processing"`状態と`"done"`状態のモックレスポンスを設定すると、実際のAPIに触れることなくポーリングコードが機能します。

要するに

はじめに

Grokテキスト-to-ビデオAPIとは？

テキスト-to-ビデオ生成の仕組み（非同期パターンを簡単に解説）

前提条件

初めてのテキスト-to-ビデオ リクエスト

curlを使用する

requestsライブラリを使ったPythonの使用

ビデオ結果のポーリング

xAI Python SDKの使用

ビデオ生成のための効果的なプロンプトの記述

シーンの記述

動き

カメラのスタイル

ライティングとムード

スタイル参照

効果的なプロンプトの構造

解像度、持続時間、アスペクト比の制御

持続時間

解像度

アスペクト比

すべてのパラメータを使用した完全な例

ビデオスタイルをガイドするための参照画像の使用

生成されたビデオの延長と編集

ビデオを延長する

ビデオを編集する

APIレスポンスからのコストの読み取り

料金表

ApidogでGrokビデオAPIをテストする方法

ユースケース1：フロントエンド開発のためのSmart Mock

ユースケース2：ポーリングループのテストシナリオ

テキスト-to-ビデオ vs 画像-to-ビデオ：いつどちらを使うべきか

一般的なエラーとその修正方法

まとめ

よくある質問

初めてのテキスト-to-ビデオリクエスト