Grok Imagine 1.0 Video Generation API: Endpoints, Auth Scopes, and Error Handling
Target Models:
grok-imagine-video-official,grok-imagine-video-1.5-official
Inference Endpoint:https://api.toapis.com/v1/videos/generations
Related: Grok Video hands-on guide · OpenAI-compatible access · Official Imagine generation · Official Imagine extend
1. TL;DR & Performance Overview
- IDs: Requests titled around “Grok Imagine 1.0” need the strings ToAPIs actually publishes. The public catalog snapshot dated 2026-11-10 lists
grok-imagine-video-officialandgrok-imagine-video-1.5-official(those two also appear under image-generation as well asopenai-video). A 2026-11-17 check of agrok-imagine-1.0docs path returned HTTP 404. - Auth: Send
Authorization: Bearer $TOAPIS_API_KEY. The official pages do not document OAuth scopes, granular permission names, or a scope-discovery endpoint for these calls. - Endpoints: Create with
POST /v1/videos/generations. Poll withGET /v1/videos/generations/{id}. Extend official-channel output withPOST /v1/videos/{video_id}/extend, orPOST /v1/videos/extendplusvideo_urlswhen you only have a public video URL. Upload stills withPOST /v1/uploads/images. - Capabilities:
grok-imagine-video-officialcovers text-to-video, image-to-video, and multi-reference generation at480por720p, duration 1–15 seconds, and extend by 2–10 seconds.grok-imagine-video-1.5-officialis first-frame image-to-video only, requires exactly oneimage, allows1080p, and does not support extend. - Pricing shape (no fixed unit price on the reference pages): output billed per second by resolution; each input image billed per image; extend also bills the source video duration. Confirm live account rates.
2. Endpoints, Authentication, and Model Contracts
Official docs use https://toapis.com (and https://toapis.cn for mainland China). Other guides in this series use https://api.toapis.com. Pick one origin and keep it consistent. Every path below uses the same Bearer header.
| Action | Method and path | Model notes |
|---|---|---|
| Upload a still | POST /v1/uploads/images | Multipart file. JPEG, PNG, WebP, or GIF, maximum 30 MB. Read data.url |
| Create a video | POST /v1/videos/generations | Both official Imagine IDs |
| Query status | GET /v1/videos/generations/{id} | Same path for generate and extend tasks |
| Extend from a prior task | POST /v1/videos/{video_id}/extend | grok-imagine-video-official only. video_id is the previous generation task id |
| Extend from a public URL | POST /v1/videos/extend | Same official ID; video_urls is required when there is no path id |
| Catalog ID | Documented jobs | Duration | Resolution | Images | Extend |
|---|---|---|---|---|---|
grok-imagine-video-official | Text-to-video, first-frame, and multi-reference | 1–15 seconds (default 8) | 480p, 720p | Optional image plus reference_images; up to 7 total | 2–10 seconds (duration default 6) |
grok-imagine-video-1.5-official | First-frame image-to-video only | 1–15 seconds (default 8) | 480p, 720p, 1080p | image is required (exactly one first frame). Additional reference_images still count toward a 7-image total | Not supported |
Aspect-ratio values in the official Imagine references include 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, and 1:1. Send a value you have confirmed for that ID and channel.
There is no documented public scope string to request “generate,” “extend,” or “upload” separately. Access is whatever the API key, user group, and channel configuration already allow. If a call fails with a permission or availability reason, check the key’s model list and the error reference rather than appending an invented scope query parameter.

Figure 1: One Bearer API key authorizes upload, generation or extend, and status polling; the official 1.5 ID does not add an extend branch.
For the non-official Grok Video family (grok-video-1.0 / grok-video-1.5), see the hands-on Grok Video guide. Those IDs are a different contract and do not inherit this extend path.
3. Production Implementation: cURL & Python
Step 1: cURL — official-channel text-to-video
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-official",
"prompt": "A golden retriever running on a green field in sunny weather",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
A first-frame job on grok-imagine-video-1.5-official uses the same path, requires "image": "https://example.com/portrait.jpg", and may set "resolution": "1080p". Replace the example URL with a public address — upload the file first if it is local:
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@/path/to/first-frame.jpg"
Step 2: Python — generate, poll, and optional extend
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_imagine(
prompt: str,
*,
model: str = "grok-imagine-video-official",
duration: int = 10,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-imagine-video-1.5-official" and not image_url:
raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if image_url:
payload["image"] = image_url
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(
f"{BASE}/v1/videos/generations",
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) -> dict:
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={"Authorization": f"Bearer {API_KEY}"}, 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
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")
def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
if not (2 <= duration <= 10):
raise ValueError("official extend duration is documented as 2-10 seconds")
res = requests.post(
f"{BASE}/v1/videos/{source_task_id}/extend",
headers=HEADERS,
json={
"model": "grok-imagine-video-official",
"prompt": prompt,
"duration": duration,
},
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 extend envelope: {data}")
return task_id
if __name__ == "__main__":
task_id = dispatch_imagine(
"A golden retriever running on a green field in sunny weather",
duration=10,
resolution="720p",
)
print("Task:", task_id)
result = poll_task(task_id)
print("Video:", result["result"]["data"][0]["url"])
To extend from a public MP4 instead of a task id, POST /v1/videos/extend with the same official model, prompt, duration, and a video_urls list. Do not call extend with grok-imagine-video-1.5-official.
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. The error reference distinguishes request errors, failed-task error.reason values, and webhook payloads.
| HTTP or task state | Common category | Recommended action |
|---|---|---|
400 | Invalid field, missing required image on 1.5-official, image-count overflow, or extend sent to a model that does not support it | Check the exact official ID, duration (1–15 on generate, 2–10 on extend), resolution (1080p only on 1.5-official), and that all media values are public URLs |
401 | Missing or invalid API key | Rotate the key and confirm Authorization: Bearer. Do not add an undocumented scope parameter as a workaround |
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: queued or in_progress | Not an error | Wait and poll again |
status: failed with content_policy_rejected | Safety or copyright review | Inspect prompt and every reference asset; compliant input can still produce a rejected output |
status: failed with insufficient_user_balance or token_quota_exceeded | Wallet or token allowance | Check both balance and periodic limits |
status: failed with generation_timeout, model_unavailable, or service_busy | Upstream timeout or availability | Check the existing id first; then retry with backoff only if the task is terminal |
5. Pricing & FinOps ROI
The official Imagine generation and extend pages describe a billing shape, not a fixed public unit price:
Use the rates returned for your account and SKU, not draft numbers.
grok-imagine-video-1.5-officialalways includes one input-image charge, because a first-frame image is required.- Extend is not a free continuation. Official extend billing includes generated extension seconds and the source video duration. Stacked extends therefore charge the growing source length again — confirm that behavior against a live quote before you build a loop.
- Do not reuse planning-draft unit prices or SLA figures. Official vendor reference rows on the ToAPIs pricing page are display-only and may not match account billing.
- Draft at
720pand a mid-range duration, change one variable at a time, and never resubmit after a client timeout until you have checked task status.
6. Frequently Asked Questions
See the FAQ block in frontmatter. Summary: send grok-imagine-video-official or grok-imagine-video-1.5-official, not grok-imagine-1.0; auth is a Bearer API key with no public OAuth scope matrix; 1.5-official is first-frame only and cannot extend; extend duration is 2–10 seconds and bills the source length as well; always distinguish HTTP errors from status: failed.
7. Action Checklist
- Create a key on the ToAPIs Developer Portal.
- Confirm
grok-imagine-video-officialorgrok-imagine-video-1.5-officialappears for your key viaGET /v1/models?type=video. - Smoke-test a
720pofficial-channel generation, pollGET /v1/videos/generations/{id}, and download the file beforeexpires_at. - If you need a continuation, extend only with
grok-imagine-video-officialand a 2–10 secondduration, then confirm the quote includes source-duration billing. - Next: the official Imagine model guide and the official Imagine 1.5 model guide for live catalog status, and the hands-on Grok Video guide if you meant the non-official
grok-video-*family.







