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

# Grok Imagine Video API: xAI Text-to-Video & Image-to-Video

> Generate 6-30-second videos with the Grok Imagine Video API. Compare text and image inputs, resolution-based image limits, request examples, and per-second billing.

## Overview

The model ID remains `grok-video`. Use the preferred REST URLs below. The previous `/generateTask/grok-video` and `/statusTask/grok-video` URLs remain supported with the same parameters and pricing.

Grok Imagine Video is an xAI video model for text-to-video generation and image-to-video workflows. Use this page when you are ready to call the API after trying the model in the APIXO playground.

| Capability | Value |
| - | - |
| Model ID | `grok-video` |
| Modes | `text-to-video`, `image-to-video` |
| Prompt length | 1-5000 characters |
| Duration | 6-30 seconds |
| Resolutions | `480p`, `720p`, `1080p` |
| Aspect ratios | `1:1`, `3:2`, `2:3`, `16:9`, `9:16` |
| Image-to-video sources | Up to 7 image URLs (`1080p` accepts 1), or a completed `grok-image` task with `task_id` and `index` |
| Output | MP4 video URL in `resultJson.resultUrls` |

## Choose the Grok video endpoint

| APIXO endpoint | Modes | Duration | Direct image inputs |
| - | - | - | - |
| [Grok Imagine Video](https://apixo.ai/docs/models/video/grok-imagine-video.md) | Text-to-video and image-to-video | 6-30 whole seconds | 1-7 at `480p` or `720p`; 1 at `1080p` |
| [Grok Imagine Video 1.5](https://apixo.ai/docs/models/video/grok-imagine-video-1-5.md) | Image-to-video only | 1-15 whole seconds | Up to 7 at `480p` or `720p`; 1 at `1080p`; dedicated frame controls are also available |

These endpoints generate new clips; neither exposes video-input editing or native video extension. For dedicated first/last frames, timed keyframes, and loop images, use [Grok Imagine Video 1.5](https://apixo.ai/docs/models/video/grok-imagine-video-1-5.md). Grok Imagine Video does not expose those frame controls. Multiple `image_urls` entries remain reference images, not a first/last-frame pair. xAI's native Extend feature is a separate API capability; do not send its parameters to these APIXO endpoints.

For a longer sequence assembled from separate clips, see the [Grok longer-video workflow](https://apixo.ai/blog/grok-video-longer-clips-workflow). It explains clip planning and editing, and distinguishes this workflow from native video extension.

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/generateTask/grok-imagine-video` | Submit a generation task |
| `GET` | `/statusTask/grok-imagine-video?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

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

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

This minimal request submits a text-to-video task and returns a `taskId`.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/grok-imagine-video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-video",
      "prompt": "a peaceful lakeside at sunset with gentle waves",
      "duration": 6,
      "resolution": "480p",
      "aspect_ratio": "3:2",
      "style": "normal"
    }
  }'
```

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

Save the `taskId`; you need it to poll for the final result.

## Poll for result

```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/grok-imagine-video?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Processing response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1767965610929
  }
}
```

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/xxx.mp4\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965655929,
    "costTime": 45000
  }
}
```

Failed response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "SensitiveContent",
    "failMsg": "Content was rejected by safety checks, please adjust the prompt",
    "createTime": 1767965610929,
    "completeTime": 1767965620132
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;
```

## Request body

### Text-to-video

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-video",
    "prompt": "a cinematic city street after rain, soft reflections, slow camera push",
    "duration": 6,
    "resolution": "480p",
    "aspect_ratio": "3:2",
    "style": "normal"
  }
}
```

### Image-to-video with image URLs

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "image-to-video",
    "prompt": "make this scene into a short cinematic pan",
    "image_urls": [
      "https://example.com/ref.jpg"
    ],
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "style": "fun"
  }
}
```

### Image-to-video from a Grok Imagine Image task

Use a successfully completed [Grok Imagine Image](https://apixo.ai/docs/models/image/grok-imagine-image.md) task and select an available result with `index` (`0` through `5`). This animates a still image into a new video; it does not extend a previous video. Do not include `image_urls` in the same request.

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "image-to-video",
    "prompt": "turn this character into a walking animation",
    "task_id": "task_previous_grok_image",
    "index": 0,
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "style": "spicy"
  }
}
```

## Parameters

**request\_type** `string` (default: async)

Result delivery mode. Omit this field or use `async` for polling with `statusTask`, or use `callback` for webhook delivery.

**callback\_url** `string`

Required when `request_type` is `callback`. Provide a public HTTPS URL that can receive the final task payload. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md).

**input** `object` *required*

Grok Imagine Video input parameters.

**properties**

**mode** `string` *required*

Generation mode. Supported values: `text-to-video`, `image-to-video`.

**prompt** `string` *required*

Text prompt describing the desired video. Supports 1-5000 characters. Empty prompts are rejected.

**duration** `integer|string` *required*

Output duration in seconds. Supports integers from `6` through `30`. Numeric strings such as `"10"` are accepted and normalized before billing.

**resolution** `string` *required*

Output resolution. Supported values: `480p`, `720p`, `1080p`. Values are trimmed and normalized to lowercase.

**aspect\_ratio** `string`

Output aspect ratio. Supported values: `1:1`, `3:2`, `2:3`, `16:9`, `9:16`. If omitted, `text-to-video` uses `3:2` and `image-to-video` uses `16:9`.

**style** `string` (default: normal)

Motion style. Supported values: `fun`, `normal`, `spicy`. `spicy` is intended for task continuation or recreation workflows.

**image\_urls** `string[]`

Reference image URLs for the direct `image-to-video` method. Supports 1-7 public, non-empty URLs for `480p` and `720p`; `1080p` accepts 1 URL. Do not combine this with the `task_id` + `index` method.

**task\_id** `string`

APIXO task ID from a successfully completed `grok-image` task. Use with `index` to animate one of its image results into a new video. This is not video extension. Do not combine with `image_urls`.

**index** `integer`

Result index from the completed `grok-image` task. Required with `task_id`. Supported range: `0` through `5`.

## Response format

### Submit task response

`POST /generateTask/grok-imagine-video` returns a task ID when the task is accepted:

**code** `integer`

API status code. `200` means the task was accepted.

**message** `string`

Human-readable status message.

**data.taskId** `string`

Unique task identifier used with the status endpoint.

### Status response fields

**taskId** `string`

Unique task identifier.

**state** `string`

Current task state: `processing`, `success`, or `failed`.

**resultJson** `string`

JSON string containing the generated video URLs in `resultUrls`. Present when `state` is `success`.

**failCode** `string`

Machine-readable failure code. Present when `state` is `failed`.

**failMsg** `string`

Human-readable failure message. Present when `state` is `failed`.

**createTime** `integer`

Task creation timestamp in Unix milliseconds.

**completeTime** `integer`

Task completion timestamp in Unix milliseconds. Present after completion.

**costTime** `integer`

Processing duration in milliseconds. Present after completion.

## Webhook callback mode

Use callback mode when your backend should receive the final result automatically instead of polling.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/grok-imagine-video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "text-to-video",
      "prompt": "a clean product reveal video with a slow camera push-in",
      "duration": 6,
      "resolution": "480p",
      "aspect_ratio": "3:2",
      "style": "normal"
    }
  }'
```

Callback delivery uses the same final payload shape as the status response. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md) for delivery requirements and retry behavior.

## Billing

New non-LLM requests use **1 credit = `$0.001`**. Calculate the full amount, including billable quantity and add-ons, apply the applicable account discount, then round the request total upward to the next whole credit. Agreed fixed unit prices retain their precision and replace the standard price and discount; final rounding still applies. See [credit conversion and rounding](https://apixo.ai/docs/pricing.md#credit-conversion-and-rounding).

The rates below match the main [API Pricing](https://apixo.ai/pricing/api) catalog's public base-price table updated on October 30, 2026. Check that page for current rates and any account discount before budgeting.

Grok Imagine Video is billed per second. The selected `resolution` determines the per-second unit price, and the submitted `duration` determines the billable seconds.

| Resolution | APIXO price | Market display reference | Minimum valid request cost |
| - | - | - | - |
| `480p` | `$0.024 / second` | `$0.060 / second` | `$0.144` for 6 seconds |
| `720p` | `$0.045 / second` | `$0.080 / second` | `$0.270` for 6 seconds |
| `1080p` | `$0.080 / second` | `$0.120 / second` | `$0.480` for 6 seconds |

The market display reference is a separately specified comparison value and does not affect the amount charged.

Formula:

```text theme={null}
total cost = duration * resolution unit price
```

A 10-second request costs `$0.240` at `480p`, `$0.450` at `720p`, or `$0.800` at `1080p`, before any account discount. These totals apply to both supported modes.

These are USD API usage charges. Studio monthly credits do not apply to API calls.

For current API rates in USD, see [API pricing](https://apixo.ai/pricing/api).

## Latency and polling

The user manual lists typical Grok Imagine Video generation time at about 40s-60s. Actual latency may vary by prompt complexity, duration, resolution, queue load, and storage transfer time.

| Workload | Typical generation time | Recommended first poll | Poll interval |
| - | - | - | - |
| `480p`, `720p`, or `1080p`, 6-30 seconds | About 40s-60s | 30s after task creation | 5s |

> [!TIP]
>
> For production workloads, use callback mode to avoid frequent polling while video tasks run.

Result URLs are valid for 15 days. Download and store important outputs promptly.

For image-to-video, use exactly one source method: either `image_urls`, or `task_id` with `index`. Public image URLs should point directly to JPG, PNG, or WebP files and should be accessible by APIXO.

Prompts can be written in English or Chinese. More specific camera motion, scene timing, subject action, lighting, and style details usually produce better results.

Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](https://apixo.ai/docs/api-reference/system.md).

## Errors and troubleshooting

### HTTP errors

| Code | Meaning | What to do |
| - | - | - |
| `400` | Invalid request body, missing `mode`, missing `prompt`, invalid `duration`, invalid `resolution`, malformed image input, or invalid `task_id` / `index` | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `404` | Task not found when polling | Check the `taskId` |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Internal error or unknown task failure | Retry with backoff or contact support if it persists |
| `502` | Service or network error | Retry with backoff |
| `503` | Service temporarily unavailable | Retry later |
| `504` | Service timeout | Retry later or use callback mode for long-running jobs |

### Validation notes

| Parameter | Backend behavior |
| - | - |
| `input.mode` | Required for routing. Must be `text-to-video` or `image-to-video`. |
| `input.prompt` | Required string. Must not be empty and must not exceed 5000 characters. |
| `input.duration` | Required. Accepts an integer or an integer string. Must resolve to a value from `6` through `30`. |
| `input.resolution` | Required string. `480p`, `720p`, and `1080p` are accepted after trimming and lowercasing. |
| `input.aspect_ratio` | Optional. Must be one of `1:1`, `3:2`, `2:3`, `16:9`, `9:16` when provided. Defaults are `3:2` for `text-to-video` and `16:9` for `image-to-video`. |
| `input.image_urls` | For direct `image-to-video`, one accepted source method. Must be a non-empty array of strings. `480p` and `720p` accept up to 7 URLs; `1080p` accepts 1 URL. |
| `input.task_id` | For `image-to-video`, the alternate source method. Must be an existing completed APIXO `grok-image` task. |
| `input.index` | Required with `task_id`. Must be an integer from `0` through `5`. |
| `input.style` | Optional. Must be `fun`, `normal`, or `spicy`; defaults to `normal` when omitted. |

### Task failure codes

`failCode` identifies the task failure. Common values include:

| Fail code | Meaning | What to do |
| - | - | - |
| `SensitiveContent` | Prompt or input/output content was rejected by safety checks | Change the prompt or reference image |
| `PromptInvalid` | Prompt was invalid or rejected | Rewrite the prompt and retry |
| `ImageFormatIncorrect` | Reference image format could not be processed | Use a public, direct image URL in a common image format |
| `RateLimited` | A rate limit was reached | Retry with exponential backoff |
| `Timeout` | The task timed out | Retry later or use callback mode |
| `InternalError` | The service was temporarily unavailable | Retry later |
| `Unknown error` | An unknown task failure occurred | Retry with backoff or contact support with the `taskId` |

See [Error Codes](https://apixo.ai/docs/api-reference/errors.md) for the full error reference.

## MCP integration

The [complete model schema](https://apixo.ai/docs/models/schemas/video/grok-imagine-video.json) declares result decoding in `mcp.result` and supported file bindings in `mcp.attachments`. These are client integration metadata, not generation input parameters. Attachment paths: `image_urls`. Preserve the user's file order. Model parameter validation remains on the API.

## Related links

* [Generation API Overview](https://apixo.ai/docs/models.md)
* [Video Models](https://apixo.ai/docs/models/video)
* [Generate Task](https://apixo.ai/docs/api-reference/generate-task.md)
* [Status Task](https://apixo.ai/docs/api-reference/status-task.md)
* [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md)
* [Error Codes](https://apixo.ai/docs/api-reference/errors.md)
* [Parameter Specification](https://apixo.ai/docs/api-reference/parameters.md)
* [Routing Strategies](https://apixo.ai/docs/concepts/routing-strategies.md)
* [Try Grok Imagine Video in the APIXO Playground](https://apixo.ai/models/grok-video)
* [API pricing](https://apixo.ai/pricing/api)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.