Skip to content
HiAPI Docs
HiAPI
Playground Get API Key
English
English 中文

Grok Imagine Text to Video API

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

Image, video, and audio models are called through theUnified 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 (fun/normal/spicy), aspect ratio, 480p/720p/1080p resolution, and 6-30s duration, all through one HiAPI API key.

Production guidance

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), normal (balanced), and spicy (more dynamic).

mode
Storyboards and previews

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

resolutionduration

Request parameters

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, spicy is more dynamic.

default normal enum: funnormalspicy
duration integer optional

Video duration in seconds, 6-30. Billed per second. Clips of 16-30 seconds are generated in segments and stitched, so visible seams are possible.

default 6
resolution enum optional

Output resolution tier. 720p is higher quality, 480p is faster and cheaper; 1080p is the highest quality. 1080p is a quality tier, not a fixed 1920x1080 frame: actual pixels follow the selected aspect_ratio.

default 480p enum: 480p720p1080p
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; http(s) 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"
  }
}
Spicy 1080p clip

spicy adds more dynamic motion; 1080p is the highest quality tier and follows the selected aspect ratio.

Request body
{
  "model": "grok-imagine/text-to-video",
  "input": {
    "prompt": "A rally car drifting through a neon-lit tunnel, sparks flying, fast camera pan, high energy",
    "aspect_ratio": "16:9",
    "mode": "spicy",
    "duration": 6,
    "resolution": "1080p"
  }
}

Getting the result

  1. The response returns a taskId immediately without waiting for generation to finish.
  2. In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
  3. When status=success, download the generated video from output[].url.
  4. 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 / 1080p. 480p is faster and cheaper, 720p is higher quality, 1080p is the highest quality — validate prompts at 480p first, then render in HD.

Is 1080p a fixed 1920x1080 frame?

No. 1080p is a quality tier and actual pixels follow the selected aspect_ratio (a 4:3 ratio renders around 1664x1248); exact dimensions depend on the output.

What does the mode parameter do?

mode controls motion style and intensity: fun is more creative, normal is more balanced, spicy is more dynamic. Default is normal, and all three modes are priced the same.

Are long videos generated in segments?

Clips of 16-30 seconds are generated in segments and stitched, so visible seams are possible. Keep clips within 15 seconds when continuity matters.

Next steps