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

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	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	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. 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. It explains clip planning and editing, and distinguishes this workflow from native video extension.

Endpoint and authentication

Base URL:

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:

Authorization: Bearer YOUR_API_KEY

Submit requests also require:

Content-Type: application/json

Copy-paste async quickstart

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

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:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

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

Poll for result

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

Processing response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1767965610929
  }
}

Success response:

{
  "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:

{
  "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:

const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;

Request body

Text-to-video

{
  "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

{
  "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 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.

{
  "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

string

default:"async"

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

string

Required when request_type is callback. Provide a public HTTPS URL that can receive the final task payload. See Webhooks.

object

required

Grok Imagine Video input parameters.

Show properties

string

required

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

string

required

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

integer|string

required

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

string

required

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

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.

string

default:"normal"

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

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.

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.

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:

integer

API status code. 200 means the task was accepted.

string

Human-readable status message.

string

Unique task identifier used with the status endpoint.

Status response fields

string

Unique task identifier.

string

Current task state: processing, success, or failed.

string

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

string

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

string

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

integer

Task creation timestamp in Unix milliseconds.

integer

Task completion timestamp in Unix milliseconds. Present after completion.

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.

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 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. The rates below match the main API Pricing 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:

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.

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

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.

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 for the full error reference.

MCP integration

The complete model schema 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.

​Overview

​Choose the Grok video endpoint

​Endpoint and authentication

​Copy-paste async quickstart

​Poll for result

​Request body

​Text-to-video

​Image-to-video with image URLs

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

​Parameters

​Response format

​Submit task response

​Status response fields

​Webhook callback mode

​Billing

​Latency and polling

​Errors and troubleshooting

​HTTP errors

​Validation notes

​Task failure codes

​MCP integration

​Related links

Overview

Choose the Grok video endpoint

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Request body

Text-to-video

Image-to-video with image URLs

Image-to-video from a Grok Imagine Image task

Parameters

Response format

Submit task response

Status response fields

Webhook callback mode

Billing

Latency and polling

Errors and troubleshooting

HTTP errors

Validation notes

Task failure codes

MCP integration

Related links