Grok Imagine

Grok Imagine is xAI's video generation model. It supports text-to-video and image-to-video with optional fun, normal, and spicy motion modes.

Models

Model Name	Mode
`grok-imagine-text-to-video`	Text-to-video
`grok-imagine-image-to-video`	Image-to-video, single or multi-image reference

Pricing

Billed per second × resolution:

Resolution	Credits/sec
`480p`	2.4
`720p`	4.5

A 6-second 480p clip costs about 15 credits; a 10-second 720p clip costs about 45 credits.

Create Task

POST https://api.aivideoapi.ai/v1/videos/generations

Request Body

Field	Type	Required	Description
`model`	string	Yes	One of the model names above
`input`	object	Yes	Generation parameters
`callback_url`	string	No	URL to receive task completion/failure notifications

Common Input

Field	Type	Required	Description
`prompt`	string	varies	Text prompt, max 5000 characters. Required for text-to-video; optional for image-to-video
`aspect_ratio`	string	No	`2:3`, `3:2`, `1:1`, `16:9`, or `9:16`; default `2:3`. Only applies when multiple images are provided in image-to-video; single-image mode follows the source image aspect ratio
`mode`	string	No	Generation mode affecting style and intensity of motion. See values below. Default `normal`
`duration`	integer	No	6-30 seconds, default `6`
`resolution`	string	No	`480p` or `720p`, default `480p`
`nsfw_checker`	boolean	No	Default `true`. Set to `false` to disable content filtering

`mode` values

Value	Description
`fun`	More creative and playful interpretation
`normal`	Balanced approach with good motion quality
`spicy`	More dynamic and intense motion effects (not available for external image inputs)

Note: spicy is text-to-video only. Image-to-video requests (with image_urls) must use fun or normal.

Text-to-Video Input

Only the common fields apply. prompt is required.

Image-to-Video Input

Field	Type	Required	Description
`image_urls`	string[]	Yes	1-7 public HTTP(S) image URLs. JPEG/PNG/WEBP, max 10MB each. Reference uploaded images in `prompt` using `@image1`, `@image2`, etc.

Examples

Text-to-Video

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-text-to-video",
    "input": {
      "prompt": "A couple of doors open one by one in a surreal hallway, revealing tiny living rooms inside.",
      "aspect_ratio": "2:3",
      "duration": 6,
      "resolution": "480p"
    }
  }'

Image-to-Video

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-to-video",
    "input": {
      "image_urls": ["https://example.com/portrait.png"],
      "prompt": "She slowly turns and smiles as the camera pushes in.",
      "duration": 6,
      "resolution": "720p"
    }
  }'

Image-to-Video (multiple images with @image references)

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-to-video",
    "input": {
      "image_urls": [
        "https://example.com/person.jpg",
        "https://example.com/coffee.jpg"
      ],
      "prompt": "@image1 sits at the desk; @image2 is placed in front of her and she picks it up.",
      "aspect_ratio": "16:9",
      "duration": 6
    }
  }'

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24"
  }
}

Query Task

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Status transitions: pending -> processing -> completed or failed.

Processing

{
  "id": "706cd3db-1a9e-4b4d-a1f2-b7642116a154",
  "status": "processing",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624146,
  "progress": null
}

Completed (Text-to-Video)

{
  "id": "706cd3db-1a9e-4b4d-a1f2-b7642116a154",
  "status": "completed",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624146,
  "completed_at": 1779624200,
  "output": {
    "urls": [
      "https://your-r2-bucket.example.com/videos/2026/05/24/21328ece-4fe3-4b4b-8a60-516080938e78.mp4?..."
    ],
    "metadata": {
      "model": "grok-imagine/text-to-video",
      "costTime": 41,
      "completeTime": 1779624193000
    }
  }
}

Completed (Image-to-Video)

{
  "id": "45168da4-8b09-4208-bc7d-dc872c1a7602",
  "status": "completed",
  "model": "grok-imagine-image-to-video",
  "created_at": 1779624320,
  "completed_at": 1779624386,
  "output": {
    "urls": [
      "https://your-r2-bucket.example.com/videos/2026/05/24/0c36f21f-f270-49d5-a3f4-dc0c05b4cb86.mp4?..."
    ],
    "metadata": {
      "model": "grok-imagine/image-to-video",
      "costTime": 52,
      "completeTime": 1779624376000
    }
  }
}

Video URLs expire in 24 hours. Download promptly after generation completes.

Failed

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624000,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

When a task fails, pre-charged credits are automatically refunded.

Callback

Pass callback_url when creating the task. The system will automatically send a POST request to your URL when the task completes or fails.

On Task Completed

{
  "id": "706cd3db-1a9e-4b4d-a1f2-b7642116a154",
  "status": "completed",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624146,
  "completed_at": 1779624200,
  "output": {
    "urls": [
      "https://your-r2-bucket.example.com/videos/2026/05/24/21328ece-4fe3-4b4b-8a60-516080938e78.mp4?..."
    ],
    "metadata": {
      "model": "grok-imagine/text-to-video",
      "costTime": 41,
      "completeTime": 1779624193000
    }
  }
}

On Task Failed

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "grok-imagine-text-to-video",
  "created_at": 1779624000,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

HTTP Status	Code	Type	Description
400	`invalid_request`	invalid_request_error	Missing or invalid parameters
401	`invalid_api_key`	authentication_error	API key is invalid, disabled, or deleted
402	`insufficient_credits`	billing_error	Credit balance too low, please top up
403	`ip_not_allowed`	permission_error	Request IP not in the key's allowlist
404	`model_not_found`	invalid_request_error	Model does not exist or is inactive
404	`task_not_found`	invalid_request_error	Task ID does not exist
429	`rate_limit_exceeded`	rate_limit_error	Too many requests, please slow down
429	`spend_limit_exceeded`	billing_error	Key spend limit reached (hourly/daily/total)
500	`internal_error`	api_error	Unexpected server error
503	`upstream_error`	upstream_error	Upstream AI provider returned an error

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

The key does not start with sk-
The key has been disabled or deleted
The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

The input contains sensitive or prohibited content
The provider is temporarily unavailable
The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.