> ## Documentation Index
> Fetch the complete documentation index at: https://wholly.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Imagine Image to Video

> API reference for creating image-to-video generation tasks

Create a video generation task using the `grok-imagine/image-to-video` model.

## Authentication

All API requests require a Bearer token.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

### Top-level fields

<ParamField body="model" type="string" required>
  Must be `grok-imagine/image-to-video`.
</ParamField>

<ParamField body="input" type="object" required>
  Input parameters for the video generation task.

  <ParamField body="image_urls" type="string[]">
    External reference image URLs. Supports JPEG, PNG, and WEBP. Each image can be up to 10 MB. Do not use together with `task_id`.

    Use `@image(n)` in the prompt to reference an uploaded image, for example `@image1 a sunset over the ocean`.

    Only one image is supported at `1080p`. Spicy mode is unavailable when using external images.
  </ParamField>

  <ParamField body="prompt" type="string">
    Optional English-language prompt describing motion, actions, camera work, timing, environment, and motion dynamics. Maximum length: 5000 characters.
  </ParamField>

  <ParamField body="mode" default="normal" type="string">
    Generation mode:

    * `fun` — more creative and playful interpretation
    * `normal` — balanced motion quality
    * `spicy` — more dynamic and intense motion effects; unavailable for external images
  </ParamField>

  <ParamField body="duration" type="string">
    Generated video duration in seconds. Supported range: `6`–`30`, in one-second steps.
  </ParamField>

  <ParamField body="resolution" default="480p" type="string">
    Supported values: `480p`, `720p`, `1080p`.
  </ParamField>

  <ParamField body="aspect_ratio" default="16:9" type="string">
    Applies to multi-image generation. In single-image mode, video dimensions follow the source image dimensions.

    Supported values: `2:3`, `3:2`, `1:1`, `16:9`, `9:16`.
  </ParamField>
</ParamField>

## Request Example

```json theme={null}
{
  "model": "grok-imagine/image-to-video",
  "input": {
    "image_urls": [
      "https://demo.com/17622476923735116.png"
    ],
    "prompt": "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.",
    "mode": "normal",
    "duration": "6",
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}
```

## Response

### Successful Response

<ResponseField name="code" type="number">
  Response status code.
</ResponseField>

<ResponseField name="msg" type="string">
  Response message. Contains the error description when the request fails.

  **Example:** `success`
</ResponseField>

<ResponseField name="data" type="object" required>
  The task data object containing task id.

  <ResponseField name="taskId" type="string" required>
    The unique identifier for this task.

    **Example:** `task_123456`
  </ResponseField>
</ResponseField>

## Query Task Status

After submitting a task, use the unified query endpoint to check the task progress and retrieve the generated results.

<Card title="Get Task Details" icon="search" href="/get-task-detail">
  Check task status, monitor generation progress, and retrieve results.
</Card>

### Error Response

```json theme={null}
{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}
```

## Response Codes

|  Code | Meaning                                                                   |
| ----: | ------------------------------------------------------------------------- |
| `200` | Success — the request was successfully processed.                         |
| `401` | Unauthorized — authentication credentials are missing or invalid.         |
| `402` | Insufficient Credits — the account does not have enough credits.          |
| `404` | Not Found — the requested resource or interface does not exist.           |
| `408` | Upstream service issue — no result has been returned for over 10 minutes. |
| `422` | Validation Error — request parameters failed validation.                  |
| `429` | Rate Limited — request frequency limit has been exceeded.                 |
| `433` | Request Limit — sub-key usage exceeded the limit.                         |
| `455` | Service Unavailable — system is undergoing maintenance.                   |
| `500` | Server Error — an unexpected error occurred while processing the request. |
| `501` | Generation Failed — content generation failed.                            |
| `505` | Feature Disabled — the requested feature is disabled.                     |