OpenAI 互換エンドポイントで Grok Video 3 API にアクセスする
対象モデル:
grok-video-1.5、grok-video-1.0
推論エンドポイント:https://api.toapis.com/v1/videos/generations
関連記事: Grok Video 実践ガイド · Grok Imagine 公式チャネル API · Chatbox の OpenAI 互換設定 · モデル一覧
1. クイックスタートと性能概要 (TL;DR)
- ここでいう「OpenAI 互換」: ToAPIs は単一の
/v1オリジン、Bearer 認証、OpenAI 風のモデル一覧とチャット補完 API を文書化しています。公開の Grok Video ID はカタログのopenai-videoエンドポイントファミリーに登録されています。これは未公開のgrok-video-3が使えることでも、OpenAI Videos SDK メソッドが文書化されていることでもありません。 - ID:
GET /v1/models?type=videoであなたのキーに見えてからgrok-video-1.5またはgrok-video-1.0を使います。2026-11-10 付けの公開カタログスナップショットにgrok-video-3はありません。 - 動画パス: 作成は
POST /v1/videos/generations、ポーリングはGET /v1/videos/generations/{id}です。公式例はhttps://toapis.com(中国本土はhttps://toapis.cn)です。本シリーズはhttps://api.toapis.comも使います。 - 共有認証:
Authorization: Bearerに 1 つの API キーを使います。これらの動画呼び出し向けの公開 OAuth スコープ文書はありません。 - クライアントの選び方: チャットや使い慣れたキー/オリジン設定には、OpenAI SDK の
base_url="https://api.toapis.com/v1"を使えます。Grok Video では、video_generation_modeと画像 URL を明示するため、文書化された REST JSON 本体を使います。
2. 互換オリジン、モデル一覧、動画パス
オリジン、/v1 プレフィックス、キーはセットで使います。ToAPIs のキーを https://api.openai.com/v1 に混ぜたり、ToAPIs のオリジンをベンダー固有の Grok パスと組み合わせたりする構成は、別の(しかも未文書化の)セットアップです。
| 手順 | 文書化されたパス | 注記 |
|---|---|---|
| モデル一覧 | GET /v1/models?type=video | デフォルトの GET /v1/models はテキストモデルのみです。type=video または type=all を使います |
| ローカル画像のアップロード | POST /v1/uploads/images(multipart file) | data.url を読みます。生成リクエストに base64 を送らないでください |
| Grok Video ジョブの作成 | POST /v1/videos/generations | 本体に model、prompt、1.5 のモード/メディアフィールドを含めます |
| ステータスのポーリング | GET /v1/videos/generations/{id} | 終端状態は completed と failed です |
| チャット(動画ではない) | POST /v1/chat/completions | オリジンとキーだけを共有します |
grok-video-1.5 では、送るメディアに合わせて video_generation_mode を text_to_video、first_frame_image_to_video、または reference_images_to_video にします。フィールド契約の詳細は Grok Video 実践ガイド と Grok Video 1.5 API リファレンス を見てください。

図 1: クライアントを ToAPIs の /v1 オリジンに向け、モデル一覧で grok-video-1.5 または grok-video-1.0 を確認し、/v1/videos/generations で投入とポーリングを行います。chat/completions は使いません。
アプリケーションコードではなくデスクトップクライアントを設定する場合は、Chatbox 設定ガイド がチャット用のホスト欄のパターンを扱います。同じチャットパスから動画ファイルが返ることは期待しないでください。
3. 本番実装: cURL と Python
本シリーズの国際向け例は https://api.toapis.com を使います。公式ドキュメントは中国本土ユーザーに https://toapis.cn を指示しています。環境ごとにオリジンは 1 つにそろえます。
ステップ 1: ID を確認してから cURL で投入する
curl -sS "https://api.toapis.com/v1/models?type=video" \
-H "Authorization: Bearer $TOAPIS_API_KEY"
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"
}'
ハードコードする前に、モデル一覧の正確な id 文字列を確認してください。grok-video-3 が無ければ送らないでください。
ステップ 2: Python — オリジンは共有し、動画は REST で呼ぶ
ここでの OpenAI SDK は、共有の base_url と API キーのためだけに示します。動画の作成とポーリングは、非公式なクライアントマッピングで 1.5 の本体フィールドが落ちないよう、文書化された generations パスのままにします。
import os
import time
import requests
from openai import OpenAI
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
# Shared origin and key. Use this client for chat completions; do not assume
# a videos.create mapping unless your account docs define one.
client = OpenAI(base_url=f"{BASE}/v1", api_key=API_KEY)
def list_video_model_ids() -> list[str]:
res = requests.get(
f"{BASE}/v1/models",
headers=HEADERS,
params={"type": "video"},
timeout=30,
)
res.raise_for_status()
data = res.json()
items = data.get("data") or data.get("models") or []
return [item.get("id") or item.get("name") for item in items if item]
def dispatch_grok_video(prompt: str, model: str = "grok-video-1.5") -> str:
available = set(list_video_model_ids())
if available and model not in available:
raise ValueError(f"{model} is not in this key's video model list")
res = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json={
"model": model,
"prompt": prompt,
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
},
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__":
print("Video models (excerpt):", list_video_model_ids()[:20])
task_id = dispatch_grok_video("A cinematic product shot with a slow camera push-in")
print("Task:", task_id)
print("Video:", poll_task(task_id))
一覧のエンベロープが想定と違う場合は、生の JSON を記録し、アカウントの モデル一覧 に合わせてパーサを直してください。ID が無いときに grok-video-3 を送るフォールバックを発明しないでください。
4. エラー処理とステータスマトリクス
下表は切り分けの起点であり、ToAPIs のエラーコードと完全一致することを保証しません。HTTP の照会が成功しても、タスクの status を読む必要があります。エラーリファレンス を参照してください。
| HTTP またはタスク状態 | よくある分類 | 推奨アクション |
|---|---|---|
400 | 未知のモデル ID、モードとメディアの不一致、または動画本体をチャットパスへ送った | GET /v1/models?type=video で ID を確認し、/v1/videos/generations に POST していること、1.5 ジョブに一致する video_generation_mode があることを確認する |
401 | API キーの欠落または無効 | OpenAI プラットフォームのキーではなく ToAPIs のキーを使い、Bearer ヘッダーを確認する |
404 | 誤ったオリジン、/v1 の欠落、または /videos/tasks/{id} のような独自パス | 投入に使った同じオリジンで GET /v1/videos/generations/{id} に切り替える |
429 | レートまたは同時実行の制限 | Retry-After があれば従い、ジッター付きでバックオフする |
5xx またはクライアントタイムアウト | ゲートウェイまたは上流の一時障害 | 再投入の前に既存のタスク id を照会する |
status: failed | 生成が成功しなかった | error.code と error.message を読む。ポリシーで拒否されたペイロードをそのまま再送しない |
5. 料金と FinOps ROI
- 互換性は課金 SKU を変えません。 請求対象は送信したカタログ ID(
grok-video-1.5またはgrok-video-1.0)であり、「OpenAI SDK を使ったこと」ではありません。 - 企画ドラフトの単価を再利用しないでください。 Grok Video 1.5 のリファレンスは固定の秒単価を保証しません。ToAPIs 料金ページの公式ベンダー参考行は表示用であり、口座の請求と一致するとは限りません。
- 発見は安く、重複生成は高くつきます。 モデル一覧は短時間キャッシュして構いませんが、クライアントタイムアウト後は、新しいジョブを作る前に必ず状態を確認してください。
- ToAPIs の課金は通常従量課金です。アカウント上の現行条件を確認してください。
6. よくある質問
frontmatter の FAQ を参照してください。要約: 互換オリジンは grok-video-3 を解放しません。/v1 は一度だけ付け、/v1/videos/generations/{id} をポーリングし、SDK の videos.create ヘルパーを仮定せず、チャット補完は MP4 を返しません。
7. アクションチェックリスト
- ToAPIs 開発者ポータル でキーを作成する。
- クライアントを
https://api.toapis.com/v1(中国本土はhttps://toapis.cn/v1)に向け、Authorization: Bearerを付ける。 -
GET /v1/models?type=videoを呼び、キーから見える正確な Grok Video ID を記録する。 -
grok-video-1.5とvideo_generation_mode: "text_to_video"でPOST /v1/videos/generationsをスモークテストし、同じ id をポーリングする。 - 次のステップ: モードと画像フィールドの詳細は Grok Video 実践ガイド、現行カタログは Grok Video 1.5 モデルガイド。







