Overview
Video generation using xAI's Grok model. Suitable for creative and coherent video synthesis from descriptive text prompts.
Primary Endpoint
/api/v1/grokVideo/startGenerate videos using Grok Imagine. Supports both text-to-video and image-to-video modes. **Modes:** - `text-to-video`: Generate video from a text prompt. Requires `prompt`. - `image-to-video`: Generate video from a reference image. Requires at least one image in `image_urls` (or `image_url`). **Duration:** `6`, `10`, or `15` seconds. **Model version:** `legacy` (default) uses the existing Grok Imagine path. `1.5` uses Grok Imagine Video 1.5 and only supports `image-to-video`. **Mode:** `fun`, `normal` (default), or `spicy`. This is an asynchronous API. After calling this endpoint, poll `/api/v1/grokVideo/{_id}` to check task status until `current_status` becomes `completed` or `failed`. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/grokVideo/allRecords` — Get Grok Video task list. - `GET /api/v1/grokVideo/{_id}` — Get Grok Video task detail. - `DELETE /api/v1/grokVideo/{_id}` — Delete Grok Video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | No | Name of the video generation task (optional, for identifying the task) |
| model_type | enum: text-to-video | image-to-video | No | Generation mode. `text-to-video` generates video from text prompt, `image-to-video` generates video from a reference image.; default: "text-to-video" |
| model_version | enum: legacy | 1.5 | No | Model version. `1.5` uses Grok Imagine Video 1.5 and only supports image-to-video.; default: "legacy" |
| prompt | string | No | Text prompt describing the video content. Required for text-to-video mode, optional for image-to-video mode. |
| mode | enum: fun | normal | spicy | No | Generation style mode. For image-to-video, upstream may fallback spicy to normal.; default: "normal" |
| image_urls | array<string> | No | Array of reference image URLs for image-to-video mode. At least one image is required when `model_type` is `image-to-video`. |
| image_url | string | No | Single reference image URL (alternative to `image_urls`). Will be prepended to `image_urls` array. |
| aspect_ratio | enum: auto | 1:1 | 16:9 | 9:16 | 4:3 | 3:4 | 3:2 | 2:3 | No | Video aspect ratio. Legacy text-to-video supports 1:1/16:9/9:16; legacy image-to-video can additionally accept 4:3/3:4/3:2/2:3 depending on the selected generation path. Grok 1.5 accepts the full list including auto.; default: "16:9" |
| duration | enum: 6 | 10 | 15 | No | Video duration in seconds.; default: "6" |
| nsfw_checker | boolean | No | Whether to enable additional NSFW checking for Grok 1.5.; default: false |
| minor_suspected_skip | boolean | No | Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.; default: false |
| webhook_url | string | No | HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048 |
| webhook_token | string | No | Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256 |
Request schema and conditional rules
{
"allOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the video generation task (optional, for identifying the task)",
"example": "My Grok Video"
},
"model_type": {
"type": "string",
"enum": [
"text-to-video",
"image-to-video"
],
"description": "Generation mode. `text-to-video` generates video from text prompt, `image-to-video` generates video from a reference image.",
"default": "text-to-video",
"example": "text-to-video"
},
"model_version": {
"type": "string",
"enum": [
"legacy",
"1.5"
],
"description": "Model version. `1.5` uses Grok Imagine Video 1.5 and only supports image-to-video.",
"default": "legacy",
"example": "1.5"
},
"prompt": {
"type": "string",
"description": "Text prompt describing the video content. Required for text-to-video mode, optional for image-to-video mode.",
"example": "A cat playing with a ball of yarn in a cozy living room, warm lighting, cinematic style"
},
"mode": {
"type": "string",
"enum": [
"fun",
"normal",
"spicy"
],
"description": "Generation style mode. For image-to-video, upstream may fallback spicy to normal.",
"default": "normal",
"example": "normal"
},
"image_urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of reference image URLs for image-to-video mode. At least one image is required when `model_type` is `image-to-video`.",
"example": [
"https://example.com/reference.jpg"
]
},
"image_url": {
"type": "string",
"description": "Single reference image URL (alternative to `image_urls`). Will be prepended to `image_urls` array.",
"example": "https://example.com/image.jpg"
},
"aspect_ratio": {
"type": "string",
"enum": [
"auto",
"1:1",
"16:9",
"9:16",
"4:3",
"3:4",
"3:2",
"2:3"
],
"description": "Video aspect ratio. Legacy text-to-video supports 1:1/16:9/9:16; legacy image-to-video can additionally accept 4:3/3:4/3:2/2:3 depending on the selected generation path. Grok 1.5 accepts the full list including auto.",
"default": "16:9",
"example": "16:9"
},
"duration": {
"type": "string",
"enum": [
"6",
"10",
"15"
],
"description": "Video duration in seconds.",
"default": "6",
"example": "6"
},
"nsfw_checker": {
"type": "boolean",
"description": "Whether to enable additional NSFW checking for Grok 1.5.",
"default": false
},
"minor_suspected_skip": {
"type": "boolean",
"default": false,
"description": "Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."
}
},
"required": []
},
{
"$ref": "#/components/schemas/WebhookInput"
}
]
}Response Fields
- code: integer
- message: string
- data: object
- data._id: string
- Task ID
- data.name: string
- Task name
- data.model_type: string
- Generation mode
- data.prompt: string
- Generation prompt
- data.aspect_ratio: string
- Video aspect ratio
- data.resolution: string
- Output video resolution
- data.duration: string
- Video duration in seconds
- data.current_status: string
- Current task status (initialized, sent, pending, processing, completed, failed, blocked)
- data.coins: number
- Credits consumed
- data.createdAt: string
- Task creation time
- trace_id: string
- Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.
Request Example
curl -X POST "https://www.a2e.com.cn/api/v1/grokVideo/start" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Related Endpoints
Responses
Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.
Bad Request - Invalid parameters
Unauthorized - Invalid or missing bearer token