# Grok Imagine API 文档

> 通过 AI Studio API 使用 Grok Imagine 模型生成视频。

## 概览

使用 AI Studio API 创建 Grok Imagine 生成任务并查询任务状态。接口采用异步流程：先创建任务拿到 `taskId`，再通过任务查询接口轮询结果。

## 认证方式

所有请求都需要在 `Authorization` 请求头中携带 API Key。

```http
Authorization: Bearer YOUR_API_KEY
```

## 可用模型

| modelId | 版本 | 服务商 | 运行模型 |
| --- | --- | --- | --- |
| `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. 创建生成任务

### 接口地址

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

### 请求示例

```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"
    }
  }
}
```

### 成功响应

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

## 2. 查询任务状态

### 接口

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

### 成功响应

```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
  }
}
```

## 请求字段

### Grok Imagine Text to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `"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 | 否 | `"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 | 否 | `6` | - | The duration of the generated video (in seconds) (6-30). (Minimum: 6, Maximum: 30, Step: 1) |
| `resolution` | enum | 否 | `"480p"` | 480p, 720p | The resolution of the generated video. |
| `nsfw_checker` | boolean | 否 | `-` | - | 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 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video generation task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `image_urls` | string[] | 否 | `["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 | 否 | `"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 | 否 | `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 | 否 | `"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 | 否 | `"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 | 否 | `6` | - | The duration of the generated video (in seconds) (6-30). (Minimum: 6, Maximum: 30, Step: 1) |
| `resolution` | enum | 否 | `"480p"` | 480p, 720p | The resolution of the generated video. |
| `aspect_ratio` | enum | 否 | `"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 | 否 | `-` | - | 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 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video upscaling task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `task_id` | string | 是 | `"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 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the video upscaling task |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `task_id` | string | 是 | `"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 | 是 | `"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 | 是 | `2` | - | The starting position of the video extension. Optional field. |
| `extend_times` | number | 是 | `-` | - | 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 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the generation task. |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 否 | `-` | - | Prompt for video generation. Maximum length: 4096 characters. |
| `image_urls` | string[] | 否 | `-` | - | 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 | 否 | `"auto"` | 1:1, 16:9, 9:16, 3:2, 2:3, auto | Aspect ratio for video generation. |
| `resolution` | enum | 否 | `"480p"` | 480p, 720p | Resolution for video generation. |
| `duration` | number | 否 | `8` | - | Video duration in seconds. Range: [1, 15]. Default: 8. Minimum: 1. Maximum: 15. Step: 1. |
| `nsfw_checker` | boolean | 否 | `-` | - | 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 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `"720p"` | 480p, 720p | Resolution of the output video. |
| `duration` | number | 否 | `6` | - | Video duration in seconds. |
| `aspect_ratio` | enum | 否 | `"16:9"` | 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16 | Aspect ratio of the generated video. |

#### input 字段

_该模型暂无字段配置。_

### Grok Imagine Image to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `"720p"` | 480p, 720p | Resolution of the output video. |
| `duration` | number | 否 | `6` | - | Video duration in seconds. |
| `aspect_ratio` | object | 否 | `"auto"` | - | Aspect ratio of the generated video. |
| `image_url` | string | 是 | `"https://v3b.fal.media/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"` | - | URL of the input image for video generation. |

#### input 字段

_该模型暂无字段配置。_

### Grok Imagine 1.5 Image to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `"720p"` | 480p, 720p, 1080p | Resolution of the output video. |
| `duration` | number | 否 | `6` | - | Video duration in seconds. |
| `image_url` | string | 是 | `"https://v3b.fal.media/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"` | - | URL of the input image for video generation. |

#### input 字段

_该模型暂无字段配置。_

### Grok Imagine Reference to Video

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `"480p"` | 480p, 720p | Resolution of the output video. |
| `reference_image_urls` | string[] | 是 | `["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 | 否 | `8` | - | Video duration in seconds. |
| `aspect_ratio` | enum | 否 | `"16:9"` | 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16 | Aspect ratio of the generated video. |

#### input 字段

_该模型暂无字段配置。_

### Grok Imagine Video Edit

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"Colorize the video"` | - | Text description of the desired edit. |
| `resolution` | enum | 否 | `"auto"` | auto, 480p, 720p | Resolution of the output video. |
| `video_url` | string | 是 | `"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 字段

_该模型暂无字段配置。_

## 价格

创建生成任务时会预扣积分。创建任务响应中的 `reservedCredits` 是本次请求最终预留的积分数量。

| 模型 | 类型 | 规格 | 价格 | 计费方式 |
| --- | --- | --- | --- | --- |
| Grok Imagine Text to Video | 文生视频 | 480p | 2 积分/秒 | 输出秒数 × 2 |
| Grok Imagine Text to Video | 文生视频 | 720p | 3 积分/秒 | 输出秒数 × 3 |
| Grok Imagine Image to Video | 图生视频 | 480p | 2 积分/秒 | 输出秒数 × 2 |
| Grok Imagine Image to Video | 图生视频 | 720p | 3 积分/秒 | 输出秒数 × 3 |
| Grok Imagine Video Upscale | 文/图生视频 | - | 10 积分 | 单次生成固定价格 |
| Grok Imagine Video Extend | 文/图生视频 | 6 | 20 积分 | 单次生成固定价格 |
| Grok Imagine Video Extend | 文/图生视频 | 10 | 30 积分 | 单次生成固定价格 |
| Grok Imagine Video 1.5 Preview | 文/图生视频 | 480p | 1.6 积分/秒 | 输出秒数 × 1.6 |
| Grok Imagine Video 1.5 Preview | 文/图生视频 | 720p | 3 积分/秒 | 输出秒数 × 3 |
| Grok Imagine Text to Video | 文生视频 | 480p | 10 积分/秒 | 输出秒数 × 10 |
| Grok Imagine Text to Video | 文生视频 | 720p | 14 积分/秒 | 输出秒数 × 14 |
| Grok Imagine Image to Video | 图生视频 | 480p | 10 积分/秒 | 输出秒数 × 10 |
| Grok Imagine Image to Video | 图生视频 | 720p | 14 积分/秒 | 输出秒数 × 14 |
| Grok Imagine 1.5 Image to Video | 图生视频 | 480p | 16 积分/秒 | 输出秒数 × 16 |
| Grok Imagine 1.5 Image to Video | 图生视频 | 720p | 28 积分/秒 | 输出秒数 × 28 |
| Grok Imagine Reference to Video | 文/图生视频 | 480p | 10 积分/秒 | 输出秒数 × 10 |
| Grok Imagine Reference to Video | 文/图生视频 | 720p | 14 积分/秒 | 输出秒数 × 14 |
| Grok Imagine Video Edit | 文/图生视频 | auto | 16 积分 | 单次生成固定价格 |
| Grok Imagine Video Edit | 文/图生视频 | 480p | 12 积分 | 单次生成固定价格 |
| Grok Imagine Video Edit | 文/图生视频 | 720p | 16 积分 | 单次生成固定价格 |

## 常见错误

| 状态 | 含义 |
| --- | --- |
| `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 |