# Grok Imagine API ドキュメント

> AI Studio API で Grok Imagine モデルを使用して動画を生成します。

## 概要

AI Studio API を使用して Grok Imagine の生成タスクを作成し、タスク状態を確認します。処理は非同期です。まずタスクを作成して `taskId` を取得し、その後タスク API で結果を確認します。

## 認証

すべてのリクエストで `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 |