> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xingchaoyiqing.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Grok: Create Video Generation Task (4 Models, Text + Image)
> POST /v1/grok/videos — Submit Grok video tasks with 4 model variants. Supports 6–30s duration, up to 7 reference images, and text-to-video mode.
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
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`
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"`
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` |
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` |
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 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
Unique task identifier. Save this — you'll use it to poll the [Query Video Task](/api-reference/video/grok-query) endpoint.
Object type. Always `"video"`.
Unix timestamp of when the task was created.
The model name used for this task.
Task status at creation. Always `"queued"` on successful submission.
Error message. `null` on successful submission.
## Code Examples
```bash cURL (Text-to-Video) theme={null}
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"
}'
```
```bash cURL (Image-to-Video) theme={null}
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"
]
}'
```
```bash cURL (Fixed Duration — grok_video3_pro) theme={null}
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"
}'
```
```python Python (Text-to-Video) theme={null}
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
```json theme={null}
{
"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](/api-reference/video/grok-query) endpoint for status updates and to retrieve `video_url` when generation completes.