Grok Imagine Text to Video API

POST /v1/tasks

All models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	grok-imagine/text-to-video
Type	Video generation (text-to-video)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Grok Imagine text-to-video turns a single text prompt into a cinematic short clip, with selectable motion mode, aspect ratio, duration (6-30s), and 480p/720p resolution, all through one HiAPI API key.

Production guidance

For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Ads and brand films

Generate creative shots and ad cuts from a single prompt.

promptduration

Vertical social clips

Pick 9:16 to produce clips ready for vertical platforms.

aspect_ratioresolution

Motion style control

mode switches motion style and intensity between fun (creative) and normal (balanced).

mode

Storyboards and previews

Validate prompts cheaply at 480p, then render finals at 720p.

resolutionduration

Request parameters

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "grok-imagine/text-to-video",
  "input": {
    "prompt": "A cat walking on the beach at sunset, cinematic",
    "aspect_ratio": "2:3",
    "mode": "normal",
    "duration": 6,
    "resolution": "480p"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "grok-imagine/text-to-video",
  "input": {
    "prompt": "A cat walking on the beach at sunset, cinematic",
    "aspect_ratio": "2:3",
    "mode": "normal",
    "duration": 6,
    "resolution": "480p"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "grok-imagine/text-to-video",
  "input": {
    "prompt": "A cat walking on the beach at sunset, cinematic",
    "aspect_ratio": "2:3",
    "mode": "normal",
    "duration": 6,
    "resolution": "480p"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value grok-imagine/text-to-video.

example grok-imagine/text-to-video

input object required

Business parameters. Put Grok Imagine Text to Video-specific configuration here.

prompt string required

Text prompt describing the desired video visuals and motion (English works best), up to 5000 characters.

aspect_ratio enum optional

Aspect ratio of the output video.

default 2:3 enum: 2:33:21:116:99:16

mode enum optional

Generation mode affecting motion style and intensity. fun is more creative, normal is more balanced.

default normal enum: funnormal

duration integer optional

Video duration in seconds. Billed per second.

default 6

resolution enum optional

Output video resolution. 720p is higher quality, 480p is faster and cheaper.

default 480p enum: 480p720p

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Basic text-to-video

Low-cost test body to validate the prompt and motion.

Request body

{
  "model": "grok-imagine/text-to-video",
  "input": {
    "prompt": "A majestic tiger prowling through misty bamboo forest at golden hour, cinematic",
    "aspect_ratio": "16:9",
    "duration": 6,
    "resolution": "480p"
  }
}

HD vertical clip

720p + 9:16, ideal for social platforms.

Request body

{
  "model": "grok-imagine/text-to-video",
  "input": {
    "prompt": "A cyberpunk street under neon lights, rain reflecting the signs, slow push-in",
    "aspect_ratio": "9:16",
    "mode": "normal",
    "duration": 8,
    "resolution": "720p"
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the generated video from output[].url.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

What is Grok Imagine text-to-video?

Grok Imagine text-to-video is an AI video generation API on HiAPI that turns a text prompt into a cinematic short clip, called via POST /v1/tasks with model set to grok-imagine/text-to-video.

How do I choose duration and resolution?

duration supports 6-30 seconds and resolution supports 480p / 720p. 480p is faster and cheaper, 720p is higher quality — validate prompts at 480p first, then render at 720p.

What does the mode parameter do?

mode controls motion style and intensity: fun is more creative, normal is more balanced. Default is normal.