How to Access Grok Video 3 API via OpenAI-Compatible Endpoints
Target Models:
grok-video-1.5,grok-video-1.0
Inference Endpoint:https://api.toapis.com/v1/videos/generations
Related: Grok Video hands-on guide · Grok Imagine official-channel API · Chatbox OpenAI-compatible setup · List models
1. TL;DR & Performance Overview
- What “OpenAI-compatible” means here: ToAPIs documents a single
/v1origin, Bearer authentication, and an OpenAI-style models list and chat completions API. Public Grok Video IDs are registered on the catalog’sopenai-videoendpoint family. That does not mean an unpublishedgrok-video-3ID will work, and it does not by itself document an OpenAI Videos SDK method. - IDs: Use
grok-video-1.5orgrok-video-1.0after they appear for your key inGET /v1/models?type=video. The public catalog snapshot dated 2026-11-10 does not listgrok-video-3. - Video path: Create with
POST /v1/videos/generations. Poll withGET /v1/videos/generations/{id}. Official examples usehttps://toapis.com(andhttps://toapis.cnfor mainland China). This series also useshttps://api.toapis.com. - Shared auth: One API key in
Authorization: Bearer. There is no separate public OAuth scope document for these video calls. - Client choice: Use the OpenAI SDK against
base_url="https://api.toapis.com/v1"for chat-style work and for a familiar key/origin setup. For Grok Video, this guide uses the documented REST JSON body sovideo_generation_modeand image URL fields stay explicit.
2. Compatible Origin, Model List, and Video Paths
Keep the origin, the /v1 prefix, and the key together. Mixing a ToAPIs key with https://api.openai.com/v1, or a ToAPIs origin with a vendor-native Grok path, is a different — and undocumented — setup.
| Step | Documented path | Notes |
|---|---|---|
| List models | GET /v1/models?type=video | Default GET /v1/models returns text models only. Use type=video or type=all |
| Upload a local image | POST /v1/uploads/images (multipart file) | Read data.url. Do not send base64 on the generation call |
| Create a Grok Video job | POST /v1/videos/generations | Body includes model, prompt, and the 1.5 mode/media fields |
| Poll status | GET /v1/videos/generations/{id} | Terminal states are completed and failed |
| Chat (not video) | POST /v1/chat/completions | Shares the origin and key only |
On grok-video-1.5, set video_generation_mode to text_to_video, first_frame_image_to_video, or reference_images_to_video so the JSON matches the media you send. The field-level contract is in the hands-on Grok Video guide and the Grok Video 1.5 API reference.

Figure 1: Point the client at a ToAPIs /v1 origin, discover grok-video-1.5 or grok-video-1.0 with the models list, then submit and poll on /v1/videos/generations — not on chat/completions.
If you are configuring a desktop client rather than application code, the Chatbox setup guide covers the host-field pattern for chat. Do not expect that same chat path to return a video file.
3. Production Implementation: cURL & Python
International examples in this series use https://api.toapis.com. Official docs tell mainland China users to use https://toapis.cn. Keep one origin per environment.
Step 1: Discover the ID, then dispatch with 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"
}'
Inspect the models list for the exact id string before you hard-code it. If grok-video-3 is absent, do not send it.
Step 2: Python — shared origin, REST video calls
The OpenAI SDK is shown only for the shared base_url and API key. Video create and poll stay on the documented generations paths so the 1.5 body fields are not lost in an unofficial client mapping.
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))
If the list call returns an unexpected envelope, log the raw JSON and align the parser with the List models page for your account. Do not invent a fallback that sends grok-video-3 when the ID is missing.
4. Error Handling & Status Matrix
The categories below are diagnostic starting points, not a guarantee of exact ToAPIs error codes. A successful HTTP query still requires you to read task status. See the error reference.
| HTTP or task state | Common category | Recommended action |
|---|---|---|
400 | Unknown model ID, mode/media mismatch, or a video body sent to a chat path | Confirm the ID in GET /v1/models?type=video, that you posted to /v1/videos/generations, and that 1.5 jobs set a matching video_generation_mode |
401 | Missing or invalid API key | Use a ToAPIs key, not an OpenAI platform key, and confirm the Bearer header |
404 | Wrong origin, missing /v1, or an invented path such as /videos/tasks/{id} | Switch to GET /v1/videos/generations/{id} on the origin you used to submit |
429 | Rate or concurrency limit | Honor Retry-After when present; back off with jitter |
5xx or client timeout | Temporary gateway or upstream issue | Query the existing task id before resubmitting |
status: failed | Generation did not succeed | Read error.code and error.message. Do not retry an unchanged policy-rejected payload |
5. Pricing & FinOps ROI
- Compatibility does not change the billable SKU. You are billed for the catalog model ID you send (
grok-video-1.5orgrok-video-1.0), not for “using the OpenAI SDK.” - Do not reuse planning-draft unit prices. The Grok Video 1.5 reference does not guarantee a fixed per-second price. Official vendor reference rows on the ToAPIs pricing page are display-only and may not match account billing.
- Failed discovery is cheap; duplicate generation is not. Cache the models list for a short period, but always check task status after a client timeout before you create another job.
- ToAPIs billing is typically pay-as-you-go — confirm the active terms on your account.
6. Frequently Asked Questions
See the FAQ block in frontmatter. Summary: a compatible base URL does not unlock grok-video-3; include /v1 once; poll /v1/videos/generations/{id}; do not assume an SDK videos.create helper; chat completions will not return an MP4.
7. Action Checklist
- Create a key on the ToAPIs Developer Portal.
- Point your client at
https://api.toapis.com/v1(orhttps://toapis.cn/v1in mainland China) withAuthorization: Bearer. - Call
GET /v1/models?type=videoand record the exact Grok Video IDs your key can see. - Smoke-test
POST /v1/videos/generationswithgrok-video-1.5andvideo_generation_mode: "text_to_video", then poll the same id. - Next: the hands-on Grok Video guide for mode and image-field details, and the Grok Video 1.5 model guide for live catalog status.







