> ## 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 1.5 API
> xAI image-to-video API for animating one or more reference images into short video clips
## Overview
Grok Imagine Video 1.5 animates reference images into short videos using a text prompt. Use this page when you already have one or more source images and want prompt-guided motion, camera movement, or scene changes.
| Capability | Value |
| ---------------- | ------------------------------------------------------- |
| Model ID | `grok-imagine-video-1-5` |
| Mode | `image-to-video` |
| Prompt length | 1-5000 characters |
| Reference images | 1-7 public image URLs |
| Duration | Integer or integer string from `1` through `15` seconds |
| Resolutions | `480p`, `720p`, `1080p` |
| Aspect ratios | `auto`, `1:1`, `16:9`, `9:16`, `3:2`, `2:3` |
| Output | MP4 video URL array in `resultJson.resultUrls` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ---------------------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/grok-imagine-video-1-5` | Submit a video generation task |
| `GET` | `/statusTask/grok-imagine-video-1-5?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 an image-to-video task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/grok-imagine-video-1-5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"prompt": "turn this product photo into a smooth rotating studio shot",
"image_urls": [
"https://example.com/product.png"
],
"resolution": "480p",
"duration": 5
}
}'
```
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-1-5?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/video.mp4\"]}",
"createTime": 1767965610929,
"completeTime": 1767965652317,
"costTime": 41388
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "CONTENT_VIOLATION",
"failMsg": "Content does not meet safety guidelines",
"createTime": 1767965610929,
"completeTime": 1767965652317,
"costTime": 41388
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;
```
## Request body
### Image-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-video",
"prompt": "make this portrait move with a subtle cinematic camera push",
"image_urls": [
"https://example.com/ref.jpg"
],
"aspect_ratio": "16:9",
"resolution": "720p",
"duration": "8"
}
}
```
The `mode` field is optional on this endpoint. If omitted, APIXO uses `image-to-video`.
## Parameters
Result delivery mode. Omit this field or use `async` for polling with `statusTask`, or use `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
Grok Imagine Video 1.5 input parameters.
Optional generation mode. This endpoint supports `image-to-video` only.
Text prompt describing the desired motion, camera movement, and scene changes. Supports 1-5000 characters. Empty prompts are rejected.
Source image URLs. Provide 1-7 public, directly accessible image URLs. Empty strings and non-string array items are rejected.
Output resolution tier. Supported values: `480p`, `720p`, `1080p`. Values are trimmed and normalized to lowercase.
Output duration in seconds. Accepts a JSON integer or integer string from `1` through `15`. Decimal values and negative values are not valid.
Output aspect ratio. Supported values: `auto`, `1:1`, `16:9`, `9:16`, `3:2`, `2:3`. Values are trimmed and normalized to lowercase when possible.
Use public, directly accessible image URLs. Choose clear source images with the subject visible and little obstruction for more predictable motion.
## Response format
### Submit task response
`POST /generateTask/grok-imagine-video-1-5` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique task identifier used with the status endpoint.
### Status response fields
Unique task identifier.
Current task state: `processing`, `success`, or `failed`.
JSON string containing generated video URLs in `resultUrls`. Present when `state` is `success`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds when available.
## 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-1-5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"prompt": "make this character smile and look toward the camera",
"image_urls": [
"https://example.com/character.jpg"
],
"resolution": "720p",
"duration": 10
}
}'
```
The callback payload uses the same top-level shape as status polling with `code`, `message`, and `data`. Successful callbacks include the final `state` and `resultJson`. See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Grok Imagine Video 1.5 is billed per second. The selected `resolution` determines the per-second unit price, and the submitted `duration` determines the billable seconds.
| Resolution | APIXO price | Minimum valid request cost |
| ---------- | ----------------- | -------------------------- |
| `480p` | `$0.02 / second` | `$0.02` for 1 second |
| `720p` | `$0.035 / second` | `$0.035` for 1 second |
| `1080p` | `$0.048 / second` | `$0.048` for 1 second |
Formula:
```text theme={null}
total cost = duration * resolution unit price
```
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Grok Imagine Video 1.5 tasks are asynchronous. Actual latency may vary by prompt complexity, source image accessibility, duration, resolution, route queue load, and provider-side processing time.
| Workload | Typical generation time | Recommended first poll | Poll interval |
| ---------------------------- | ------------------------------------------------------- | ----------------------- | ------------- |
| Image-to-video, 1-15 seconds | Varies by prompt, image count, resolution, and duration | 30s after task creation | 5s |
For production workloads, use callback mode to avoid frequent polling while video tasks run.
Result URLs are temporary. Download and store important outputs promptly after task completion.
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](/docs/api-reference/system).
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `400` | Invalid request body, missing `input`, unsupported `mode`, missing `prompt`, missing `image_urls`, invalid `resolution`, invalid `duration`, or invalid media array | 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 |
| `403` | Key or route cannot access the model | Check permissions and route strategy |
| `404` | Task not found when polling | Check the `taskId` |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error or unknown task failure | Retry with backoff |
| `502` | Upstream error | Retry with backoff |
| `504` | Upstream timeout | Retry later or use callback mode for long-running jobs |
### Validation notes
| Condition | Backend behavior |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Missing `input` | Request fails before task creation. |
| Missing `mode` | APIXO uses `image-to-video`. |
| Unsupported `mode` | Request fails before task creation. This endpoint only supports `image-to-video`. |
| Missing `prompt` | Request fails before task creation. |
| Empty `prompt` or more than 5000 characters | Request fails before task creation. |
| Missing `image_urls` | Request fails before task creation. |
| `image_urls` is not an array, contains empty strings, or contains non-string items | Request fails before task creation. |
| More than 7 `image_urls` | Request fails before task creation. |
| Missing `resolution` | Request fails before task creation. |
| Unsupported `resolution` | Request fails before task creation. Supported values are `480p`, `720p`, and `1080p`. |
| Missing `duration` | Request fails before task creation. |
| `duration` outside `1` through `15`, decimal, or negative | Request fails before task creation. |
| Missing `aspect_ratio` | Defaults to `auto`. |
| Unsupported `aspect_ratio` | Request fails before task creation. Use `auto`, `1:1`, `16:9`, `9:16`, `3:2`, or `2:3`. |
### Task failure codes
`failCode` is generated from APIXO's mapped provider error. 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 by the provider | 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` | Provider-side rate limit was reached | Retry with exponential backoff |
| `Timeout` | Provider-side timeout | Retry later or use callback mode |
| `Unknown error` | The provider returned an unmapped failure | Retry with backoff or contact support with the `taskId` |
See [Error Codes](/docs/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/docs/models)
* [Video Models](/docs/models/video)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Routing Strategies](/docs/concepts/routing-strategies)
* [Try Grok Imagine Video 1.5 in the APIXO Playground](https://apixo.ai/models/grok-imagine-video-1-5)
* [Pricing](https://apixo.ai/pricing)