Grok: Create Video Generation Task (4 Models, Text + Image)

Submit an asynchronous video generation task using xAI’s Grok video models. The API accepts a prompt plus optional duration, aspect ratio, resolution, and reference images — then immediately returns a task id for polling. Grok supports both text-to-video and image-to-video modes, with four distinct model variants offering different duration ranges, resolution caps, and reference image constraints.

Base URL

https://zcbservice.aizfw.cn/kyyReactApiServer

Endpoint

POST /v1/grok/videos

Authentication

Authorization: Bearer YOUR_API_KEY

Models

Choose the model that best fits your duration, resolution, and billing needs:

Model	Duration	Aspect Ratios	Resolution	Reference Images	Billing
`grok_video3`	6–30s (default 10s)	`16:9` / `9:16` / `1:1` / `3:2` / `2:3`	`480p` / `720p` (default `720p`)	Up to 7	Per second
`grok_video3_pro`	Fixed 10s	`16:9` (default)	`720p` (default)	Supported	Per call
`grok_video3_max`	`6` / `10` / `12` / `16` / `20` / `30`s (default 10s)	`16:9` / `9:16` / `1:1`	`480p` / `720p` (default `720p`)	Up to 5 (public URL only)	Per second
`grok_video3_stable`	`6` or `10`s (default 10s)	`16:9` / `9:16` / `3:2` / `2:3` / `1:1`	`480p` / `720p` (default `720p`)	Up to 7 (public URL only)	Per call

grok_video3_max and grok_video3_stable require reference images to be publicly accessible URLs — base64-encoded images are not supported for these models.

Request Parameters

string

required

The Grok model to use. See the model table above for capabilities.Supported values:

grok_video3
grok_video3_pro
grok_video3_max
grok_video3_stable

string

required

Text description of the video you want to generate. Include subject, action, camera movement, and visual style for best results.Example: "A cat dancing in the rain, cinematic style"

integer

Output video duration in seconds. Behavior varies by model:

Model	Supported Values	Default
`grok_video3`	Any integer `6`–`30`	`10`
`grok_video3_pro`	Fixed `10` — do not set	`10`
`grok_video3_max`	`6`, `10`, `12`, `16`, `20`, `30`	`10`
`grok_video3_stable`	`6` or `10`	`10`

string

Output video aspect ratio. Defaults to 16:9 for all models.

Model	Supported Ratios
`grok_video3`	`16:9`, `9:16`, `1:1`, `3:2`, `2:3`
`grok_video3_pro`	`16:9`
`grok_video3_max`	`16:9`, `9:16`, `1:1`
`grok_video3_stable`	`16:9`, `9:16`, `3:2`, `2:3`, `1:1`

string

Output resolution. Defaults to 720p for all models.

Model	Supported Resolutions
`grok_video3`	`480p`, `720p`
`grok_video3_pro`	`720p`
`grok_video3_max`	`480p`, `720p`
`grok_video3_stable`	`480p`, `720p`

array

Array of reference image URLs for image-to-video generation. When omitted, the request is treated as text-to-video.Constraints by model:

grok_video3 — up to 7 images
grok_video3_pro — reference images supported
grok_video3_max — up to 5 images; must be public URLs
grok_video3_stable — up to 7 images; must be public URLs

Example: ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"]

Passing image_urls switches the request to image-to-video mode. Do not pass image_urls for pure text-to-video generation.

Response Fields

string

Unique task identifier. Save this — you’ll use it to poll the Query Video Task endpoint.

string

Object type. Always "video".

integer

Unix timestamp of when the task was created.

string

The model name used for this task.

string

Task status at creation. Always "queued" on successful submission.

string

Error message. null on successful submission.

Code Examples

curl --request POST \
  --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/grok/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "grok_video3_max",
    "prompt": "A cat dancing in the rain, cinematic style",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

curl --request POST \
  --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/grok/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "grok_video3_max",
    "prompt": "The cat leaps and dances playfully in the rain",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "image_urls": [
      "https://example.com/cat-reference.jpg"
    ]
  }'

curl --request POST \
  --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/grok/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "grok_video3_pro",
    "prompt": "A cinematic aerial shot of a mountain range at sunrise",
    "aspect_ratio": "16:9"
  }'

import requests

response = requests.post(
    "https://zcbservice.aizfw.cn/kyyReactApiServer/v1/grok/videos",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "grok_video3_max",
        "prompt": "A cat dancing in the rain, cinematic style",
        "duration": 10,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)

task = response.json()
print("Task ID:", task["id"])
print("Status:", task["status"])

Example Response

{
  "id": "video_grok_1234567890",
  "object": "video",
  "created": 1774836724,
  "model": "grok_video3_max",
  "status": "queued",
  "error": null
}

Key Constraints

Omit image_urls for text-to-video; include it for image-to-video
For grok_video3_max: only the enumerated duration values are accepted — do not pass arbitrary seconds
For grok_video3_stable: reference images must be publicly accessible URLs (no base64)
More reference images generally means longer queue and generation time
grok_video3_pro has a fixed 10-second duration — do not set the duration field

Next Steps

Use the returned id to poll the Query Video Task endpoint for status updates and to retrieve video_url when generation completes.

Overview

Text APIs

Image APIs

Video APIs

Asset Management

Grok: Create Video Generation Task (4 Models, Text + Image)

Base URL

Endpoint

Authentication

Models

Request Parameters

Response Fields

Code Examples

Example Response

Key Constraints

Next Steps

​Base URL

​Endpoint

​Authentication

​Models

​Request Parameters

​Response Fields

​Code Examples

​Example Response

​Key Constraints

​Next Steps

Base URL

Endpoint

Authentication

Models

Request Parameters

Response Fields

Code Examples

Example Response

Key Constraints

Next Steps