# Grok Imagine API Documentation

> Generate videos with the Grok Imagine model through the AI Studio API.

## Overview

Use the AI Studio API to create Grok Imagine generation tasks and query their status. The flow is asynchronous: create a task first, then poll the task endpoint with the returned `taskId`.

## Authentication

All requests require an API key in the `Authorization` header.

```http
Authorization: Bearer YOUR_API_KEY
```

## Available models

| modelId | Version | Provider | Runtime model |
| --- | --- | --- | --- |
| `video:grok-imagine-text-to-video` | Grok Imagine Text to Video | Grok Imagine Text to Video | grok-imagine/text-to-video |
| `video:grok-imagine-image-to-video` | Grok Imagine Image to Video | Grok Imagine Image to Video | grok-imagine/image-to-video |
| `video:grok-imagine-video-upscale` | Grok Imagine Video Upscale | Grok Imagine | grok-imagine/upscale |
| `video:grok-imagine-video-extend` | Grok Imagine Video Extend | Grok Imagine | grok-imagine/extend |
| `video:grok-imagine-video-1-5-preview` | Grok Imagine Video 1.5 Preview | Grok Imagine Video 1.5 Preview | grok-imagine-video-1-5-preview |
| `video:fal-xai-grok-imagine-video-text-to-video` | Grok Imagine Text to Video | xAI | xai/grok-imagine-video/text-to-video |
| `video:fal-xai-grok-imagine-video-image-to-video` | Grok Imagine Image to Video | xAI | xai/grok-imagine-video/image-to-video |
| `video:fal-xai-grok-imagine-video-v1-5-image-to-video` | Grok Imagine 1.5 Image to Video | xAI | xai/grok-imagine-video/v1.5/image-to-video |
| `video:fal-xai-grok-imagine-video-reference-to-video` | Grok Imagine Reference to Video | xAI | xai/grok-imagine-video/reference-to-video |
| `video:fal-xai-grok-imagine-video-edit-video` | Grok Imagine Video Edit | xAI | xai/grok-imagine-video/edit-video |

## 1. Create generation task

### Endpoint

```http
POST https://localhost:3000/api/ai-studio/execute
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

### Request example

```json
{
  "modelId": "video:grok-imagine-text-to-video",
  "isPublic": true,
  "payload": {
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A couple of doors open to the right one by one randomly and stay open, to show the inside, each is either a living room, or a kitchen, or a bedroom or an office, with little people living inside.",
      "aspect_ratio": "2:3",
      "mode": "normal",
      "duration": "6",
      "resolution": "480p"
    }
  }
}
```

### Success response

```json
{
  "success": true,
  "data": {
    "modelId": "video:grok-imagine-text-to-video",
    "generationId": "generation-id",
    "reservedCredits": 20,
    "taskId": "provider-task-id",
    "state": "queued"
  }
}
```

## 2. Query task status

### Endpoint

```http
GET https://localhost:3000/api/ai-studio/tasks/{taskId}
Authorization: Bearer YOUR_API_KEY
```

### Success response

```json
{
  "success": true,
  "data": {
    "generationId": "generation-id",
    "taskId": "provider-task-id",
    "modelId": "video:grok-imagine-text-to-video",
    "state": "succeeded",
    "mediaUrls": [
      "https://example.com/result.mp4"
    ],
    "reservedCredits": 20,
    "refundedCredits": 0
  }
}
```

## Request fields

### Grok Imagine Text to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"grok-imagine/text-to-video"` | grok-imagine/text-to-video | The model name to use for generation. Required field. - Must be `grok-imagine/text-to-video` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video generation task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"A couple of doors open to the right one by one randomly and stay open, to show the inside, each is either a living room, or a kitchen, or a bedroom or an office, with little people living inside."` | - | Text prompt describing the desired video motion. Required field. - Should be detailed and specific about the desired visual motion<br>- Describe movement, action sequences, camera work, and timing<br>- Include details about subjects, environments, and motion dynamics<br>- Maximum length: 5000 characters<br>- Supports English language prompts |
| `aspect_ratio` | enum | No | `"2:3"` | 2:3, 3:2, 1:1, 16:9, 9:16 | Specifies the width-to-height ratio of the generated video. Controls the aspect ratio of the output. - **2:3**: Portrait orientation (vertical)<br>- **3:2**: Landscape orientation (horizontal)<br>- **1:1**: Square format<br>- **16:9**: Wide screen format<br>- **9:16**: Tall screen format Default: 2:3 |
| `mode` | enum | No | `"normal"` | fun, normal, spicy | Specifies the generation mode affecting the style and intensity of motion. - **fun**: More creative and playful interpretation<br>- **normal**: Balanced approach with good motion quality<br>- **spicy**: More dynamic and intense motion effects Default: normal |
| `duration` | number | No | `6` | - | The duration of the generated video (in seconds) (6-30). (Minimum: 6, Maximum: 30, Step: 1) |
| `resolution` | enum | No | `"480p"` | 480p, 720p | The resolution of the generated video. |
| `nsfw_checker` | boolean | No | `-` | - | Defaults to false. You can set it to false based on your needs. If set to false, our content filtering will be disabled, and all results will be returned directly by the model itself.<br>Note: There is no guarantee that everything can be filtered out; if you are not satisfied with the results, you will need to make your own arrangements. |

### Grok Imagine Image to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"grok-imagine/image-to-video"` | grok-imagine/image-to-video | The model name to use for generation. Required field. - Must be `grok-imagine/image-to-video` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video generation task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `image_urls` | string[] | No | `["https://file.aiquickdraw.com/custom-page/akr/section-images/1762247692373tw5di116.png"]` | - | Provide an external image URL as a reference for video generation. Up to 7 images are supported. Do not use it simultaneously with task_id. In your prompt, reference an uploaded image by typing @image(n) followed by a space (for example: @image1 a sunset over the ocean).<br>- Supports JPEG, PNG, and WEBP formats<br>- Maximum file size for each image: 10MB<br>- The Spicy mode is not available when using external images<br>- The array can contain a maximum of seven URLs |
| `task_id` | string | No | `"task_grok_12345678"` | - | Task ID from a previously generated Grok image. Use with index to select a specific image. Do not use with image_urls. - Use task ID from grok-imagine/text-to-image generations<br>- Supports all modes including Spicy<br>- Maximum length: 100 characters |
| `index` | number | No | `0` | - | When using task_id, specify which image to use (Grok generates 6 images per task). Only works with task_id. - 0-based index (0-5)<br>- Ignored if image_urls is provided<br>- Default: 0 |
| `prompt` | string | No | `"POV hand comes into frame handing the girl a cup of take away coffee, the girl steps out of the screen looking tired, then takes it and she says happily: \"thanks! Back to work\" she exits the frame and walks right to a different part of the office."` | - | Text prompt describing the desired video motion. Optional field. - Should be detailed and specific about the desired visual motion<br>- Describe movement, action sequences, camera work, and timing<br>- Include details about subjects, environments, and motion dynamics<br>- Maximum length: 5000 characters<br>- Supports English language prompts |
| `mode` | enum | No | `"normal"` | fun, normal, spicy | Specifies the generation mode affecting the style and intensity of motion. Note: Spicy mode is not available for external image inputs. - **fun**: More creative and playful interpretation<br>- **normal**: Balanced approach with good motion quality<br>- **spicy**: More dynamic and intense motion effects (not available for external images) Default: normal |
| `duration` | number | No | `6` | - | The duration of the generated video (in seconds) (6-30). (Minimum: 6, Maximum: 30, Step: 1) |
| `resolution` | enum | No | `"480p"` | 480p, 720p | The resolution of the generated video. |
| `aspect_ratio` | enum | No | `"16:9"` | 2:3, 3:2, 1:1, 16:9, 9:16 | Image ratio selection only applies to multi-image generation mode. In single-image mode, the video width and height are referenced to the image width and height. |
| `nsfw_checker` | boolean | No | `-` | - | Defaults to false. You can set it to false based on your needs. If set to false, our content filtering will be disabled, and all results will be returned directly by the model itself.<br>Note: There is no guarantee that everything can be filtered out; if you are not satisfied with the results, you will need to make your own arrangements. |

### Grok Imagine Video Upscale

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"grok-imagine/upscale"` | grok-imagine/upscale | The model name to use for generation. Required field. - Must be `grok-imagine/upscale` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video upscaling task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `task_id` | string | Yes | `"task_grok_12345678"` | - | Task ID from a previously successful video generation task. Required field. - Must be from a AI Studio video generation model (e.g., grok-imagine/text-to-video)<br>- The original video generation must have completed successfully<br>- Only AI Studio–generated task IDs are supported |

### Grok Imagine Video Extend

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"grok-imagine/extend"` | grok-imagine/extend | The model name to use for generation. Required field. - Must be `grok-imagine/extend` for this endpoint |
| `input` | object | Yes | `-` | - | Input parameters for the video upscaling task |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `task_id` | string | Yes | `"task_grok_12345678"` | - | Task ID from a previously successful video generation task. Required field. - Must be from a AI Studio video generation model (e.g., grok-imagine/text-to-video)<br>- The original video generation must have completed successfully<br>- Only AI Studio–generated task IDs are supported |
| `prompt` | string | Yes | `"The camera slowly pans forward, showing the protagonist walking deeper into the forest, with the sunlight filtering through the leaves and casting dappled shadows."` | - | Text instructions describing the required movement of the video. Required field. - Provide a detailed description of how you would like the video to expand and continue.<br>- You can specify camera movements, scene changes, object actions, etc.<br>- The more specific the prompt words are, the more likely the generated effect will match your expectations.<br>- Supports input in both Chinese and English. |
| `extend_at` | number | Yes | `2` | - | The starting position of the video extension. Optional field. |
| `extend_times` | number | Yes | `-` | - | Duration of video extension (in seconds). Required field. - `6`: Expand 6 seconds of video content<br>- `10`: Expand 10 seconds of video content<br>- The longer the extension duration, the longer the time required for generation<br>- Select the appropriate duration based on the complexity of the scene |

### Grok Imagine Video 1.5 Preview

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"grok-imagine-video-1-5-preview"` | grok-imagine-video-1-5-preview | The model name used for generation. This endpoint must use `grok-imagine-video-1-5-preview`. |
| `input` | object | Yes | `-` | - | Input parameters for the generation task. |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | No | `-` | - | Prompt for video generation. Maximum length: 4096 characters. |
| `image_urls` | string[] | No | `-` | - | Upload image files to be used as API input. Supported file types: image/jpeg, image/png, image/webp, image/jpg. Maximum file size: 20MB. Supports multi-file upload, up to 1 file. |
| `aspect_ratio` | enum | No | `"auto"` | 1:1, 16:9, 9:16, 3:2, 2:3, auto | Aspect ratio for video generation. |
| `resolution` | enum | No | `"480p"` | 480p, 720p | Resolution for video generation. |
| `duration` | number | No | `8` | - | Video duration in seconds. Range: [1, 15]. Default: 8. Minimum: 1. Maximum: 15. Step: 1. |
| `nsfw_checker` | boolean | No | `-` | - | Defaults to false. You can set it to false based on your needs. If set to false, our content filtering will be disabled, and all results will be returned directly by the model itself.<br>Note: There is no guarantee that everything can be filtered out; if you are not satisfied with the results, you will need to make your own arrangements. |

### Grok Imagine Text to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"Anime schoolgirl bursting out of house door, cherry blossoms blowing, morning light, speed lines indicating rush, chibi-ready expressions, classic shojo aesthetic, vibrant colors"` | - | Text description of the desired video. |
| `resolution` | enum | No | `"720p"` | 480p, 720p | Resolution of the output video. |
| `duration` | number | No | `6` | - | Video duration in seconds. |
| `aspect_ratio` | enum | No | `"16:9"` | 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16 | Aspect ratio of the generated video. |

#### Input fields

_No fields are configured for this model._

### Grok Imagine Image to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"Medieval knight in ornate armor walking through a mystical forest, bioluminescent plants pulsing with light, ancient stone ruins overgrown with glowing vines, over-the-shoulder camera, dark fantasy aesthetic, volumetric fog and Lumen lighting"` | - | Text description of desired changes or motion in the video. |
| `resolution` | enum | No | `"720p"` | 480p, 720p | Resolution of the output video. |
| `duration` | number | No | `6` | - | Video duration in seconds. |
| `aspect_ratio` | object | No | `"auto"` | - | Aspect ratio of the generated video. |
| `image_url` | string | Yes | `"https://v3b.fal.media/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"` | - | URL of the input image for video generation. |

#### Input fields

_No fields are configured for this model._

### Grok Imagine 1.5 Image to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"Medieval knight in ornate armor walking through a mystical forest, bioluminescent plants pulsing with light, ancient stone ruins overgrown with glowing vines, over-the-shoulder camera, dark fantasy aesthetic, volumetric fog and Lumen lighting"` | - | Text description of desired changes or motion in the video. |
| `resolution` | enum | No | `"720p"` | 480p, 720p, 1080p | Resolution of the output video. |
| `duration` | number | No | `6` | - | Video duration in seconds. |
| `image_url` | string | Yes | `"https://v3b.fal.media/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"` | - | URL of the input image for video generation. |

#### Input fields

_No fields are configured for this model._

### Grok Imagine Reference to Video

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"A @Image1 running through a sunlit meadow, cinematic slow motion"` | - | Text prompt describing the video to generate. Use @Image1, @Image2, etc. to reference specific images from reference_image_urls in order. |
| `resolution` | enum | No | `"480p"` | 480p, 720p | Resolution of the output video. |
| `reference_image_urls` | string[] | Yes | `["https://v3b.fal.media/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"]` | - | One or more reference image URLs to guide the video generation as style and content references. Reference in prompt as @Image1, @Image2, etc. Maximum 7 images. |
| `duration` | number | No | `8` | - | Video duration in seconds. |
| `aspect_ratio` | enum | No | `"16:9"` | 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16 | Aspect ratio of the generated video. |

#### Input fields

_No fields are configured for this model._

### Grok Imagine Video Edit

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"Colorize the video"` | - | Text description of the desired edit. |
| `resolution` | enum | No | `"auto"` | auto, 480p, 720p | Resolution of the output video. |
| `video_url` | string | Yes | `"https://v3b.fal.media/files/b/0a8b9112/V5Z_NIPE3ppMDWivNo6_q_video_019.mp4"` | - | URL of the input video to edit. The video will be resized to a maximum area of 854x480 pixels and truncated to 8 seconds. |

#### Input fields

_No fields are configured for this model._

## Pricing

Credits are reserved when a generation task is created. The `reservedCredits` value in the create-task response is the final amount reserved for that request.

| Model | Type | Spec | Price | Billing |
| --- | --- | --- | --- | --- |
| Grok Imagine Text to Video | Text to Video | 480p | 2 credits/s | Output seconds × 2 |
| Grok Imagine Text to Video | Text to Video | 720p | 3 credits/s | Output seconds × 3 |
| Grok Imagine Image to Video | Image to Video | 480p | 2 credits/s | Output seconds × 2 |
| Grok Imagine Image to Video | Image to Video | 720p | 3 credits/s | Output seconds × 3 |
| Grok Imagine Video Upscale | Text/Image to Video | - | 10 credits | Fixed per generation |
| Grok Imagine Video Extend | Text/Image to Video | 6 | 20 credits | Fixed per generation |
| Grok Imagine Video Extend | Text/Image to Video | 10 | 30 credits | Fixed per generation |
| Grok Imagine Video 1.5 Preview | Text/Image to Video | 480p | 1.6 credits/s | Output seconds × 1.6 |
| Grok Imagine Video 1.5 Preview | Text/Image to Video | 720p | 3 credits/s | Output seconds × 3 |
| Grok Imagine Text to Video | Text to Video | 480p | 10 credits/s | Output seconds × 10 |
| Grok Imagine Text to Video | Text to Video | 720p | 14 credits/s | Output seconds × 14 |
| Grok Imagine Image to Video | Image to Video | 480p | 10 credits/s | Output seconds × 10 |
| Grok Imagine Image to Video | Image to Video | 720p | 14 credits/s | Output seconds × 14 |
| Grok Imagine 1.5 Image to Video | Image to Video | 480p | 16 credits/s | Output seconds × 16 |
| Grok Imagine 1.5 Image to Video | Image to Video | 720p | 28 credits/s | Output seconds × 28 |
| Grok Imagine Reference to Video | Text/Image to Video | 480p | 10 credits/s | Output seconds × 10 |
| Grok Imagine Reference to Video | Text/Image to Video | 720p | 14 credits/s | Output seconds × 14 |
| Grok Imagine Video Edit | Text/Image to Video | auto | 16 credits | Fixed per generation |
| Grok Imagine Video Edit | Text/Image to Video | 480p | 12 credits | Fixed per generation |
| Grok Imagine Video Edit | Text/Image to Video | 720p | 16 credits | Fixed per generation |

## Common errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request payload |
| `401` | Missing or invalid API key |
| `402` | Insufficient credits or plan limit |
| `404` | Model or task not found |
| `429` | Rate limit exceeded |
| `500` | Server error |