要するに
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位を獲得しました。大規模かつ実績あるインフラを前提に使えます。
このガイドでは、リクエストの作成、結果のポーリング、パラメータ調整、プロンプト設計、参照画像の使い方、ビデオの延長・編集手順、適切なAPI選択まで具体的に解説します。
💡 APIは非同期です。 フロントエンドはビデオの生成完了まで何も表示できません。UIを開発・テストするには、APIのポーリングフローを模倣できる環境が必須です。ApidogのSmart Mockなら生成・ポーリング両エンドポイントを簡単にモック可能。バックエンド開発中でもUIやポーリングロジックを実装できます。詳細は後述のテストセクション参照。
Grokテキスト-to-ビデオAPIとは？
Grokテキスト-to-ビデオAPIは、https://api.x.aiで提供されるxAIのメディア生成APIの一つです。テキストプロンプトのみでgrok-imagine-videoモデルが短い動画を生成します（ソース画像不要）。
同期型の画像生成エンドポイント（POST /v1/images/generations、モデルgrok-imagine-image、1画像0.02ドル）も併設されています。さらに、既存ビデオの延長や編集用エンドポイントも利用可能です。
テキスト-to-ビデオは「言葉だけで」構図・動き・スタイルをゼロから生成します。画像-to-ビデオのようにソース画像を渡したい場合は、Grok画像-to-ビデオAPIガイドを参照してください。
テキスト-to-ビデオ生成の仕組み（非同期パターン解説）
ビデオ生成APIは非同期パターンです。フローは以下の通り：
- プロンプトを含めてPOSTリクエスト送信
- 即座に
request_idが返却 - サーバー側でビデオ生成開始
-
request_idを使いGETエンドポイントをポーリング - ステータスが
"done"になればビデオURLを取得
この設計により、HTTP接続を短時間で済ませ、進捗確認やUIの切り替えが柔軟に行えます。ローディングインジケーターや中間状態の実装が必要です。
前提条件
実装前に以下を準備します。
xAIアカウント
console.x.aiで作成。API利用には課金情報登録が必要です。APIキー
コンソールでAPIキーを生成し、安全な場所に保管。全リクエストでBearer認証として使います。
APIキーは環境変数に設定しましょう。
export XAI_API_KEY="your_api_key_here"
オプションでxAI Python SDKをインストール可能です。
pip install xai-sdk
初めてのテキスト-to-ビデオ リクエスト
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"
}
Python (requests) での実装例
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を受け取ったら、GET /v1/videos/{request_id}を一定間隔で呼び出してステータスが"done"になるまで待ちます。
-
"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:
"""ビデオ生成が完了するまでポーリング"""
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")
# ワークフロー例
def generate_video(prompt: str) -> str:
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")
カスタムポーリングや進捗制御が必要な場合はrequests版を利用してください。
ビデオ生成のための効果的なプロンプト設計
シーン記述
被写体と設定を明確に記述。「雨に濡れた窓の横の木製テーブルに置かれた白いセラミックのコーヒーマグ」など。動きの指示
「湯気が立ち上るマグカップの周りをカメラがゆっくり旋回する」など、動きの明示が重要。カメラスタイル
「クローズアップ」「ドローンビュー」など映画的な表現を加える。ライティング・ムード
「ゴールデンアワー」「ネオンライト」「憂鬱な雰囲気」などで見た目・雰囲気を指定。スタイル参照
「シネマティック」「アニメ」「ハイパーラプス」など、スタイル名も積極的に活用。
効果的なプロンプト例
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秒）。長いほどコスト増。
解像度
"resolution": "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"}
]
}
一貫したスタイルの画像セットが最も効果的。プロンプトが主で、画像は色・構図・テクスチャに影響。
生成ビデオの延長と編集
xAIには生成済みビデオの操作用エンドポイントが2種類あります。
ビデオの延長
POST /v1/videos/extensions
既存ビデオのrequest_idと新しいプロンプトをセットで送信し、映像を追加できます。複数回呼び出すことで15秒以上の動画も実現可能。
ビデオの編集
POST /v1/videos/edits
既存ビデオをプロンプトで編集できます（スタイル変更・シーン修正など）。
いずれもrequest_idが返る非同期パターンです。GET /v1/videos/{request_id}で結果を取得。
APIレスポンスからコスト取得
完了時レスポンスのusage.cost_in_usd_ticksを10,000,000で割るとUSD換算できます。
cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Cost: ${cost_in_usd:.4f}")
# 出力例: Cost: $0.0500
料金表
| 解像度 | 1秒あたり | 10秒クリップ |
|---|---|---|
| 480p | $0.05 | $0.50 |
| 720p | $0.07 | $0.70 |
500000000ティック＝$0.50、480pの10秒クリップに相当します。全リクエストのコストを自前で集計し、ダッシュボードへ反映可能です。
ApidogでGrokビデオAPIをテストする方法
非同期ポーリングはテストが難しいですが、ApidogのSmart Mockで効率化できます。
ユースケース1：フロントエンド開発用Smart Mock
ApidogのSmart Mockでエンドポイントのスキーマを定義すれば、即座にリアルなモックレスポンスが得られます。
生成エンドポイントのモック例：
-
POST /v1/videos/generationsレスポンススキーマにrequest_id（文字列）を設定。自動でUUID風の値が返る。
{
"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
ポーリングエンドポイントのモック例：
-
GET /v1/videos/{request_id}status、video.url、video.duration、progress、usage.cost_in_usd_ticksなどを含むスキーマ・カスタムレスポンス例。
{
"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
}
}
開発のポイント：
-
"status": "processing"/"done"/"failed"のバリエーションでUI状態をテスト - 開発中はAPIクレジット消費ゼロ
ユースケース2：ポーリングループのテストシナリオ
統合テストもApidog内で自動化できます。
生成リクエスト追加
POST /v1/videos/generations→JSONPathでrequest_idを抽出し変数保存ポーリング追加
GET /v1/videos/{{videoRequestId}}をForループで繰り返し、status == "done"でブレーク。各ループで5秒待機。アサーション
最後のレスポンスで$.video.urlが空でないか検証。
このシナリオをCIに組み込めば、回帰テストも高速化できます。
テキスト-to-ビデオ vs 画像-to-ビデオ：使い分け
どちらもgrok-imagine-videoモデル利用ですが、用途が異なります。
-
テキスト-to-ビデオが適するケース：
- スクリプトやコンセプトから新規動画を生成
- モデルに構図や演出の自由度を持たせたい
- 入力がプロンプトのみ
-
画像-to-ビデオが適するケース：
- 既存の画像（写真・イラスト）をアニメーション化
- 細かなビジュアル要件がある
- 一連の画像から連続アニメーションを作成
重要：
テキスト-to-ビデオはゼロから生成、画像-to-ビデオは既存画像に動きを付与。詳細はこちらのガイド参照。
両対応UIの場合、入力内容に応じてAPIルーティングを自動化しましょう。
よくあるエラーと対処法
401 Unauthorized
APIキーの指定ミス・期限切れ。Bearer YOUR_XAI_API_KEY形式・有効性を再確認。429 Too Many Requests
レートリミット超過。1分60リクエスト・1秒1リクエスト。ポーリング間隔（5秒以上）を調整。status: "failed"
モデレーション違反の可能性。respect_moderationがtrueの場合はプロンプトを修正。ビデオURL 404
生成ビデオURLは短期間有効。取得後すぐに自ストレージへ保存。空白/静止ビデオ
曖昧なプロンプトや動きの記述がない場合。動きやシーンを明確に指定する。生成遅延
720pや長尺は時間がかかる。開発・テストでは短尺＆480p推奨。
まとめ
Grokテキスト-to-ビデオAPIは、テキストだけで動画生成を実現します。非同期パターンの理解が重要です。
request_idでポーリングし、完了したらビデオURLを取得・保存。
持続時間・解像度・アスペクト比・参照画像などパラメータも柔軟に指定可能です。
コスト追跡はcost_in_usd_ticksから計算。
開発時はApidogでAPIモックサーバー・テストシナリオを構築し、実際のビデオ生成待ちやクレジット消費なしでフロントエンド開発・CIテストが可能です。
よくある質問
Q: テキスト-to-ビデオ生成にはどのモデル名を使う？
A: grok-imagine-videoを指定。/v1/videos/generationsで必須。
Q: ビデオ生成にかかる時間は？
A: 持続時間・解像度による。480pの短尺は30秒未満、720p長尺は数分。5〜10秒おきのポーリング推奨。
Q: 15秒超のビデオ生成は可能？
A: 単一リクエスト不可。最大durationは15秒。/v1/videos/extensionsで延長。
Q: 生成ビデオのダウンロード方法は？
A: ポーリング完了時のresult.video.urlから即時ダウンロード。URLは一時的。
Q: プロンプトがモデレーション違反の場合？
A: status: "failed"で完了。respect_moderationがtrueならプロンプト修正で再試行。
Q: ビデオAPIの無料枠は？
A: ビデオは1秒ごとに課金。無料枠はなし。新規クレジットはconsole.x.aiで確認。
Q: reference_imagesとソース画像の違いは？
A: 参照画像はスタイルガイド用。画像-to-ビデオは画像そのものが最初のフレーム。
Q: クレジット消費なしでポーリングテストするには？
A: ApidogのSmart Mockで生成・ポーリング両エンドポイントをモック。"processing"/"done"状態のレスポンスを切り替えれば、実API不要でテスト可能です。
Top comments (0)