Grok Video API

Integrate asynchronous Grok video generation with model discovery, task creation, polling, content download, image references, and JavaScript-ready request patterns.

Overview

GEThttps://img.gpt88.cc/v1/models

POSThttps://img.gpt88.cc/v1/videos/generations

GEThttps://img.gpt88.cc/v1/videos/{id}

GEThttps://img.gpt88.cc/v1/videos/{id}/content

Field	Type	Required	Description
`Base URL`	string	Required	`https://img.gpt88.cc`
`Authentication`	header	Required	`Authorization: Bearer <YOUR_API_KEY>`
`Request format`	string	Required	`application/json`
`Task type`	async	Required	The create endpoint returns a task object before the final video is ready.

Base URLstringRequired
https://img.gpt88.cc
AuthenticationheaderRequired
Authorization: Bearer <YOUR_API_KEY>
Request formatstringRequired
application/json
Task typeasyncRequired
The create endpoint returns a task object before the final video is ready.

Authentication

Create or copy an API key in Agent API Keys and send it as a Bearer token. Keep the key on your backend; do not expose it in a browser bundle or mobile app.

auth-header.txtbash

Authorization: Bearer <YOUR_API_KEY>

List available models

list-models.shbash

curl -H "Authorization: Bearer $GPT88_API_KEY" https://img.gpt88.cc/v1/models

Field	Type	Required	Description
`id`	string	Required	Model ID, such as `grok-image-video`.
`object`	string	Required	Always `model`.
`capabilities`	string[]	Optional	Supported capabilities such as `video`, `image`, and `streaming`.
`modalities`	string[]	Optional	Supported modalities, including `video` and `image`.

idstringRequired
Model ID, such as grok-image-video.
objectstringRequired
Always model.
capabilitiesstring[]
Supported capabilities such as video, image, and streaming.
modalitiesstring[]
Supported modalities, including video and image.

Use the live model response instead of hard-coding a model list. The examples below use grok-image-video.

Create a video task

Field	Type	Required	Description
`model`	string	Required	Use `grok-image-video` or another ID returned by the model list.
`prompt`	string	Required	The video generation prompt.
`seconds`	integer	Optional	Suggested values are 4, 6, 8, 10, 12, or 15 depending on the model and input images.
`aspect_ratio`	string	Optional	For example `16:9` or `9:16`.
`resolution`	string	Optional	Common values are `720p` and `480p`.
`image_urls`	array<string>	Optional	Public HTTPS image URLs or complete base64 data URLs.
`input_reference`	object \| string	Optional	Single-reference compatibility field. Do not combine it with another image field.
`reference_images`	array<string>	Optional	Multi-reference compatibility field. Do not combine it with `input_reference`.

modelstringRequired
Use grok-image-video or another ID returned by the model list.
promptstringRequired
The video generation prompt.
secondsinteger
Suggested values are 4, 6, 8, 10, 12, or 15 depending on the model and input images.
aspect_ratiostring
For example 16:9 or 9:16.
resolutionstring
Common values are 720p and 480p.
image_urlsarray<string>
Public HTTPS image URLs or complete base64 data URLs.
input_referenceobject | string
Single-reference compatibility field. Do not combine it with another image field.
reference_imagesarray<string>
Multi-reference compatibility field. Do not combine it with input_reference.

create-video.shbash

curl -X POST "https://img.gpt88.cc/v1/videos/generations" \
  -H "Authorization: Bearer $GPT88_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-image-video",
    "prompt": "A cinematic red sports car driving through rainy neon streets at night",
    "seconds": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

Poll task status

Save id first. For compatibility with older responses, also accept request_id or task_id when selecting the ID. Poll every five seconds for up to five minutes, and do not submit a duplicate generation task while the original is running.

poll-video.shbash

curl "https://img.gpt88.cc/v1/videos/<VIDEO_ID>" \
  -H "Authorization: Bearer $GPT88_API_KEY"

Treat status: completed as success. failed, cancelled, and expired are terminal failures. A progress value of 100 does not prove that the task succeeded; always inspect the status field.

Download the video

When the task is completed, request the content endpoint and save the response as binary data.

download-video.shbash

curl "https://img.gpt88.cc/v1/videos/<VIDEO_ID>/content" \
  -H "Authorization: Bearer $GPT88_API_KEY" \
  -o generated-video.mp4

If a response includes a relative url or video_url, resolve it against the image API host. The content endpoint is usually the most stable way to download the final file.

Common errors

401: recopy the API key and check the Bearer header.
403: inspect account permissions, balance, and model availability.
400 prompt or model required: send both fields and copy the exact model ID from GET /v1/models.
Reference image fetch failed: use a directly reachable HTTPS URL or a complete data URL.
Timeout: keep the task ID and continue polling instead of submitting the same generation again.
JSON returned from download: verify the task is completed and that you called /v1/videos/<id>/content with the key.