Grok-Video-3 API 実践ガイド:xAI ビデオエンジンで先に確認すべき現在の契約
対象モデル:
grok-video-1.5、grok-video-1.0
推論エンドポイント:https://api.toapis.com/v1/videos/generations
関連記事: OpenAI 互換アクセス · Grok Imagine 公式チャネル API · Hailuo 2.3 動画ガイド · Grok Video 1.5 リファレンス
1. クイックスタートと性能概要 (TL;DR)
- まずカタログを見る: Grok Video 3 の実践記事であっても、呼び出しは ToAPIs が実際に公開している ID から始めます。2026-11-10 付けの公開プロダクションカタログスナップショットは、
openai-videoエンドポイントにgrok-video-1.0とgrok-video-1.5を掲載しています。2026-11-17 にgrok-video-3のドキュメントとモデルガイド URL を確認したところ、結果は HTTP 404 でした。 - 契約:
POST /v1/videos/generationsに非同期で投入し、GET /v1/videos/generations/{id}をcompletedまたはfailedまでポーリングします。公式例はhttps://toapis.com(中国本土はhttps://toapis.cn)です。本シリーズの他ガイドはhttps://api.toapis.comを使います。オリジンは 1 つにそろえてください。 - モード:
grok-video-1.5はtext_to_video、first_frame_image_to_video、reference_images_to_videoを文書化しています。video_generation_modeを明示し、参照画像 1 枚がレガシーなファーストフレーム扱いにならないようにします。 - メディア: 公開の
http://またはhttps://URL だけを送ってください。ローカルファイルはPOST /v1/uploads/imagesでアップロードし、返却されたdata.urlを使います。base64 は送らないでください。 - 捨てるべき未検証の主張: 企画ドラフトにある
grok-video-3という ID、99.95% の SLA、固定の$0.030–$0.038/秒、あるいは将来の音声リリース日は、現行の ToAPIs ドキュメントではありません。ライブの料金とチャネル可否はアカウントで確認してください。
2. 現行の Grok Video ID と生成モード
model フィールドには公開モデル名を使います。サプライヤ固有名、URL スラッグ、未公開の grok-video-3 に置き換えないでください。
| カタログ ID | 文書化されたジョブ | 尺(ドキュメント) | 解像度 | 画像入力 |
|---|---|---|---|---|
grok-video-1.5 | テキスト、ファーストフレーム、または 1–7 枚の参照画像。video_generation_mode で指定 | 整数 1–15 秒 | 参照モードは 480p または 720p。テキストとファーストフレームはチャネル対応時に 1080p | ファーストフレーム: image または input_reference でちょうど 1 枚。参照モード: 1–7 枚の reference_images |
grok-video-1.0 | テキストから動画、画像から動画 | 生成リファレンス: 1–15 秒(デフォルト 8)。モデルガイド / Playground: 利用中のバリアントは 6 秒 上限 | 480p、720p | 任意の image と reference_images。合計最大 8 枚 |
grok-video-1.5 の新規連携ではモードを明示してください。
video_generation_mode | 必須入力 | 省略すべきもの |
|---|---|---|
text_to_video | 空でない prompt | あらゆる画像フィールド |
first_frame_image_to_video | image または input_reference にちょうど 1 枚のファーストフレーム | 両方の別名に矛盾する値を入れない。アカウントのリファレンスが別途述べない限り、参照リストを同時に送らない |
reference_images_to_video | prompt と 1–7 枚の reference_images(文字列または {"url":"..."} オブジェクト) | このモードなしで reference_images を 1 枚だけ送ること。レガシーな単一画像入力はファーストフレーム動作のままです |
見積もりの成功は、生成チャネルが開いている保証にはなりません。モードは互換チャネルで有効化されたときだけ使え、非対応の組み合わせはタスク作成前に拒否されることがあります。
Grok Video リファレンスでよく出るアスペクト比は 16:9、9:16、3:2、2:3、1:1 です。利用可否はチャネル依存なので、その ID で確認済みの値を送ってください。

図 1: プロンプト(と任意の公開画像 URL)を POST /v1/videos/generations に送り、同じタスク id をポーリングし、status が completed になってから result.data[0].url を読みます。
公式チャネルの Grok Imagine で動画延長などが必要なら、別の ID ファミリーです。Imagine 公式チャネルガイド を参照してください。尺の体系が異なる別契約としては Hailuo 2.3 ガイド があります。
3. 本番実装: cURL と Python
本シリーズの国際向け例は https://api.toapis.com を使います。公式ドキュメントは中国本土ユーザーに https://toapis.cn を指示しています。環境ごとにオリジンは 1 つにそろえます。パス、モデル ID、Bearer ヘッダーは同じです。
ステップ 1: cURL で grok-video-1.5 を投入する
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-video-1.5",
"prompt": "A cinematic product shot with a slow camera push-in",
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
ファーストフレームジョブは同じパスで "video_generation_mode": "first_frame_image_to_video" と image URL を使います。参照画像ジョブは "video_generation_mode": "reference_images_to_video" と reference_images を設定し、resolution は 480p または 720p のままにします。
ステップ 2: Python の投入とポーリング
次の例は、文書化されたタスク状態パスと queued / in_progress / completed / failed に従います。本番前に、アカウントの API リファレンスで id、result.data[0].url、エンベロープを確認してください。
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_grok_video(
prompt: str,
*,
model: str = "grok-video-1.5",
mode: str = "text_to_video",
duration: int = 8,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-video-3":
raise ValueError("grok-video-3 is not a current public catalog ID")
if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
raise ValueError("reference mode is documented as 480p or 720p")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if model == "grok-video-1.5":
payload["video_generation_mode"] = mode
if mode == "text_to_video" and (image_url or reference_images):
raise ValueError("text_to_video rejects image fields")
if mode == "first_frame_image_to_video":
if not image_url:
raise ValueError("first-frame mode requires exactly one image URL")
payload["image"] = image_url
if mode == "reference_images_to_video":
refs = reference_images or []
if not (1 <= len(refs) <= 7):
raise ValueError("reference mode requires 1-7 image URLs")
payload["reference_images"] = refs
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_grok_video(
"A cinematic product shot with a slow camera push-in",
mode="text_to_video",
duration=8,
resolution="720p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
プロンプトテンプレートのバージョンをタスク記録と一緒に保存し、モデルやモードの変更と文言の変更を区別できるようにしてください。expires_at の前にファイルをダウンロードします。ステータスリファレンスは 30 日の保持期間を記載しています。
4. エラー処理とステータスマトリクス
下表は切り分けの起点であり、ToAPIs のエラーコードと完全一致することを保証しません。HTTP の照会が成功しても、タスクの status を読む必要があります。リクエストエラーと status: failed の理由(content_policy_rejected、insufficient_user_balance、generation_timeout など)は エラーリファレンス を見てください。
| HTTP またはタスク状態 | よくある分類 | 推奨アクション |
|---|---|---|
400 | 無効なフィールド、モードとメディアの不一致、非対応の組み合わせ | 正確なカタログ ID、video_generation_mode が画像フィールドと一致していること、参照モードが 480p または 720p であること、画像が公開 URL であることを確認する |
401 | API キーの欠落または無効 | ToAPIs ダッシュボードでキーをローテーションし、Authorization: Bearer ヘッダーを確認する |
429 | レートまたは同時実行の制限 | Retry-After があれば従い、ジッター付きでバックオフし、安全なときだけ再試行する |
5xx またはクライアントタイムアウト | ゲートウェイまたは上流の一時障害 | 再投入の前に既存のタスク id を照会する |
status: queued または in_progress | エラーではない | 待って再ポーリングする。2 つ目のジョブを作らない |
status: failed | 生成が成功しなかった | error.code と error.message(あれば error.reason)を読む。ポリシーで拒否されたペイロードをそのまま再送しない |
5. 料金と FinOps ROI
- 企画ドラフトの単価を再利用しないでください。
grok-video-1.5の API リファレンスは、料金は現行アカウントと SKU 設定に従い、ページは固定の秒単価を保証しないと述べています。ToAPIs 料金ページの公式ベンダー参考行は表示用であり、口座の請求と一致するとは限りません。 - 見積もりはチャネル保証ではありません。 1.5 のリファレンスは、見積もり成功が生成チャネルの利用可能性を意味しないと注記しています。
- プロンプト層で支出を制御する: まず
720pと 8 秒前後の中尺で試し、バージョン管理したテンプレートを使い、一度に 1 変数だけ変え、クライアントタイムアウト後は状態を確認してから再投入します。 - 公式ベンダー契約には年間コミット、席数、前払い下限が付くことがあります。ToAPIs の課金は通常従量課金です。アカウント上の現行条件を確認してください。
6. よくある質問
frontmatter の FAQ を参照してください。要約: grok-video-3 は現行の公開カタログ ID ではありません。grok-video-1.5 または grok-video-1.0 から始め、1.0 の尺上限はチャネル固有の確認事項として扱い、同期音声は文書化されておらず、必ず generations のステータスパスをポーリングし、タスク id を保存してください。
7. アクションチェックリスト
- ToAPIs 開発者ポータル でキーを作成する。
-
GET /v1/models?type=videoで、キーからgrok-video-1.5またはgrok-video-1.0が見えることを確認する。一覧と API リファレンスの両方に後から現れない限り、grok-video-3は送らない。 -
video_generation_mode: "text_to_video"、duration: 8、resolution: "720p"で上記の cURL をスモークテストする。 - 期限を設けて
GET /v1/videos/generations/{id}をポーリングし、expires_atの前に結果をダウンロードする。 - 次のステップ: 既存クライアントを ToAPIs に向ける場合は OpenAI 互換アクセスガイド、現行カタログは Grok Video 1.5 モデルガイド。1.0 で 6 秒を超える尺に依存する前に Grok Video 1.0 モデルガイド を確認する。







