Grok Videos Generation API Integration Guide

This document introduces the integration guide for the Grok Videos Generation API, which can generate Grok Imagine (xAI) videos through input text prompts, input images, and optional reference images.

Application Process

To use Grok Videos Generation API, first open the Ace Data Cloud Console and copy your API Token.

If you are not logged in, you will be redirected to sign in and brought back to this page automatically.

A single API Token works across every service on the platform — no need to subscribe per service. New accounts receive free starter credit; when it runs low you can top up your shared balance in the console.

📘 Full documentation: Grok Videos Generation API →

Model Description

This API supports two models:

  • grok-imagine-video-1.5-fast (default): Supports text-to-video (only pass prompt) and image-to-video (pass image_url), with a lower price.
  • grok-imagine-video-1.5: Supports image-to-video only, must provide image_url.

Basic Usage

First, understand the basic usage method: input the prompt prompt, model model, and other parameters to generate the corresponding video.

Here we set the Request Headers, including:

  • accept: The desired response format, set to application/json for JSON format.
  • authorization: The API key for calling the API, selectable after application.

Also set the Request Body, including:

  • prompt: Text prompt describing the desired video content. Required when using grok-imagine-video-1.5-fast for text-to-video; optional when passing image_url.
  • model: The model to generate the video, optional grok-imagine-video-1.5-fast (default) or grok-imagine-video-1.5.
  • image_url: Input image URL for image-to-video. Required when model is grok-imagine-video-1.5.
  • reference_image_urls: Optional array of reference image URLs to guide the style or content of the video.
  • aspect_ratio: Aspect ratio of the generated video, optional 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3.
  • resolution: Output resolution, optional 480p (default) or 720p. Higher resolution consumes more quota.
  • duration: Duration of the generated video (seconds), range 1–15, default 8. Billing is based on output seconds.
  • callback_url: Asynchronous callback URL. If set, the API immediately returns a task_id, and the result will be POSTed to this URL upon task completion.

Click the "Try" button to test, and the result will be similar to the following:

{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}

The returned result contains multiple fields, described as follows:

  • success: Whether the video generation request was successful.
  • task_id: The ID of this video generation task.
  • trace_id: The trace ID for this request, used for troubleshooting.
  • data: List of generated video results.
    • id: Unique identifier of the generated video.
    • video_url: URL of the generated video.
    • state: Status of the video generation task, options are pending / succeeded / failed.

You only need to obtain the generated video from the video_url link in the data field.

The corresponding CURL command is as follows:

curl -X POST 'https://api.acedata.cloud/grok/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast",
  "resolution": "480p",
  "duration": 8
}'

The corresponding Python code is as follows:

import requests

url = "https://api.acedata.cloud/grok/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video-1.5-fast",
    "resolution": "480p",
    "duration": 8
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Image-to-Video

If you want to generate a video based on an input image, you can pass image_url. When using grok-imagine-video-1.5, this field is required:

{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 8
}

Reference Image Guidance

If you want to guide the style or content of the generated video with one or more reference images, you can pass an array of image URLs in reference_image_urls:

{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}

Asynchronous Callback

Video generation requires some processing time. If you do not want to keep a long connection waiting, you can pass callback_url. The API will immediately return a task_id, and the final result will be POSTed to this URL upon task completion:

{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast",
  "duration": 8,
  "callback_url": "https://your-domain.com/callback/grok"
}

The immediate return result is as follows:

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

Query Task Result

If you use asynchronous callback or want to actively query the task status, you can use the Grok Tasks API (POST https://api.acedata.cloud/grok/tasks) to query the latest status and result by task_id.

Billing Description

This service charges based on the "output seconds" of the generated video. The unit price is jointly determined by model and resolution. Total price = unit price × duration (default 8 seconds). 720p is more expensive than 480p, and grok-imagine-video-1.5 is more expensive than grok-imagine-video-1.5-fast. Please refer to the pricing page for specific unit prices.

Error Handling

When there is a problem with the request, the API will return the corresponding error code and description. Common ones are:

  • 400: Invalid request parameters, e.g., missing prompt for text-to-video, missing image_url for grok-imagine-video-1.5, or duration out of the 1–15 range.
  • 401: Authentication failure, invalid token or token does not match the API.
  • 403: Insufficient balance, or prompt rejected by content review.
  • 429: Too many requests, upstream rate limiting triggered, please try again later.
  • 500: Internal server error or upstream generation failure.