Hands-on with Grok-Video-3 API: Everything You Need to Know About xAI's Video Engine
Target Models:
grok-video-1.5,grok-video-1.0
Inference Endpoint:https://api.toapis.com/v1/videos/generations
Related: OpenAI-compatible access · Grok Imagine official-channel API · Hailuo 2.3 video guide · Grok Video 1.5 reference
1. TL;DR & Performance Overview
- Catalog first: Requests for a hands-on Grok Video 3 integration still have to start from the IDs ToAPIs actually publishes. The public production catalog snapshot dated 2026-11-10 lists
grok-video-1.0andgrok-video-1.5on theopenai-videoendpoint. A 2026-11-17 check of thegrok-video-3documentation and model-guide URLs returned HTTP 404. - Contract: Submit asynchronously to
POST /v1/videos/generations, then pollGET /v1/videos/generations/{id}untilcompletedorfailed. Official examples usehttps://toapis.com(andhttps://toapis.cnfor mainland China). Other guides in this series usehttps://api.toapis.com. Pick one origin and keep it consistent. - Modes:
grok-video-1.5documentstext_to_video,first_frame_image_to_video, andreference_images_to_video. Setvideo_generation_modeexplicitly so a single reference image is not treated as a legacy first-frame job. - Media: Send public
http://orhttps://URLs only. Upload local files withPOST /v1/uploads/imagesand use the returneddata.url. Do not send base64. - Unverified claims to drop: Planning drafts that quote a
grok-video-3ID, a 99.95% SLA, a fixed$0.030–$0.038per-second rate, or a future audio ship date are not current ToAPIs documentation. Confirm live rates and channel support in your account.
2. Current Grok Video IDs and Generation Modes
Use the public model name in the model field. Do not substitute a supplier-native name, a URL slug, or an unpublished grok-video-3 string.
| Catalog ID | Documented jobs | Duration (docs) | Resolution | Image inputs |
|---|---|---|---|---|
grok-video-1.5 | Text, first-frame, or 1–7 reference images, selected with video_generation_mode | Integer 1–15 seconds | 480p or 720p in reference mode; text and first-frame may use 1080p when the channel supports it | First-frame: exactly one image or input_reference. Reference mode: 1–7 reference_images |
grok-video-1.0 | Text-to-video and image-to-video | Generation reference: 1–15 seconds (default 8). Model guide / playground: a 6-second cap on the currently available variant | 480p, 720p | Optional image plus reference_images; up to 8 images total |
For grok-video-1.5, new integrations should set the mode explicitly:
video_generation_mode | Required input | Must omit |
|---|---|---|
text_to_video | Non-empty prompt | Any image field |
first_frame_image_to_video | Exactly one first frame in image or input_reference | Conflicting values in both aliases; do not also send a reference list unless the reference for your account says otherwise |
reference_images_to_video | prompt plus 1–7 reference_images (strings or {"url":"..."} objects) | Relying on a single reference_images entry without this mode — legacy single-image input stays first-frame behavior |
A successful price quote does not guarantee that a generation channel is open. Modes are available only when enabled on a compatible channel; unsupported combinations can be rejected before a task is created.
Common aspect-ratio values in the Grok Video references are 16:9, 9:16, 3:2, 2:3, and 1:1. Availability still depends on the channel, so send a value you have confirmed for that ID.

Figure 1: Submit a prompt (and optional public image URLs) to POST /v1/videos/generations, poll the same task id, and read result.data[0].url only after status is completed.
If you need official-channel Grok Imagine features such as video extend, that is a different ID family — see the Imagine official-channel guide. For a second video contract with a different duration matrix, see the Hailuo 2.3 guide.
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. Paths, model IDs, and the Bearer header stay the same.
Step 1: cURL dispatch for 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"
}'
A first-frame job uses the same path with "video_generation_mode": "first_frame_image_to_video" and an image URL. A reference-image job sets "video_generation_mode": "reference_images_to_video" and a reference_images list, and keeps resolution at 480p or 720p.
Step 2: Python helper and poller
The snippet follows the documented task-status path and the queued / in_progress / completed / failed statuses. Confirm id, result.data[0].url, and the envelope against the API reference for your account before you ship.
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))
Store the prompt template version next to the task record so you can tell a model or mode change from a wording change. Download the file before expires_at; the status reference documents a 30-day retention window.
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 for request errors versus status: failed reasons such as content_policy_rejected, insufficient_user_balance, or generation_timeout.
| HTTP or task state | Common category | Recommended action |
|---|---|---|
400 | Invalid field, mode/media mismatch, or unsupported combination | Check the exact catalog ID, that video_generation_mode matches the image fields, that reference mode stays at 480p or 720p, and that image values are public URLs |
401 | Missing or invalid API key | Rotate the key in the ToAPIs dashboard and confirm the Authorization: Bearer header |
429 | Rate or concurrency limit | Honor Retry-After when present; back off with jitter; retry only when safe |
5xx or client timeout | Temporary gateway or upstream issue | Query the existing task id before resubmitting |
status: queued or in_progress | Not an error | Wait and poll again; do not create a second job |
status: failed | Generation did not succeed | Read error.code and error.message (and error.reason when present). Do not retry an unchanged policy-rejected payload |
5. Pricing & FinOps ROI
- Do not reuse planning-draft unit prices. The
grok-video-1.5API reference states that pricing follows the current account and SKU configuration and that the page does not guarantee a fixed per-second price. Official vendor reference rows on the ToAPIs pricing page are display-only and may not match what your account is billed. - A quote is not a channel guarantee. The 1.5 reference notes that a successful price quote does not mean a generation channel is available.
- Control spend in the prompt layer: draft at
720pand a mid-range duration such as 8 seconds, keep a versioned template, change one variable at a time, and do not resubmit after a client timeout until you have checked task status. - Official vendor contracts often add annual commitments, seat quotas, and prepayment floors. 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: grok-video-3 is not a current public catalog ID; start from grok-video-1.5 or grok-video-1.0; treat the 1.0 duration cap as a channel-specific check; synchronized audio is not documented; always poll the generations status path and persist the task id.
7. Action Checklist
- Create a key on the ToAPIs Developer Portal.
- Confirm
grok-video-1.5orgrok-video-1.0appears for your key viaGET /v1/models?type=video— do not sendgrok-video-3unless it later appears in that list and in the API reference. - Smoke-test the cURL snippet with
video_generation_mode: "text_to_video",duration: 8, andresolution: "720p". - Poll
GET /v1/videos/generations/{id}with a bounded deadline, and download the result beforeexpires_at. - Next: the OpenAI-compatible access guide if you are pointing an existing client at ToAPIs, the Grok Video 1.5 model guide for live catalog status, and the Grok Video 1.0 model guide before you rely on a duration above 6 seconds on that ID.







