Grok Imagine Image to Video API
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/image-to-video |
|---|---|
| Type | Video generation (image-to-video) |
| Endpoint | POST /v1/tasks |
| Pricing | See HiAPI Pricing |
Grok Imagine image-to-video animates one or more reference images into a cinematic short clip, guided by an optional motion prompt, with selectable aspect ratio, motion mode (fun/normal/spicy), 480p/720p/1080p resolution, and 6-30s duration, 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
Pass a product shot or poster as reference to generate an ad clip with camera motion.
image_urlspromptTurn portrait photos into natural motion clips for social and demos.
image_urlsdurationAdd camera moves like push-ins to landscape or scene stills; mode supports fun, normal, and spicy.
image_urlsmodePass up to 7 reference images and reference them with @image1 etc. in the prompt.
image_urlsRequest parameters
model string required Fixed value grok-imagine/image-to-video.
input object required Business parameters. Put Grok Imagine Image to Video-specific configuration here.
image_urls string[] required Reference image URLs or asset:// asset IDs, 1-7 images. Supports JPEG/PNG/WEBP, 10MB each. SVG is not supported. Reference specific images with @image1 etc. in the prompt. When resolution is 1080p, exactly 1 image is allowed.
prompt string optional Text prompt describing the desired video motion (optional, English works best), up to 5000 characters.
aspect_ratio enum optional Aspect ratio of the output video. It only applies in multi-image reference mode; with a single input image the parameter has no effect and the output follows the input image ratio.
mode enum optional Generation mode affecting motion style and intensity. fun is more creative, normal is more balanced, spicy is more dynamic. When external images (image_urls) are used, the upstream may process the request as normal.
duration integer optional Video duration in seconds, 6-30. Billed per second. Clips of 16-30 seconds, and multi-image clips longer than 10 seconds, are generated in segments and stitched, so visible seams are possible.
resolution enum optional Output resolution tier. 720p is higher quality, 480p is faster and cheaper; 1080p is the highest quality and only accepts a single input image. Actual pixels follow the input image ratio.
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.
when enum optional Callback trigger timing. Use final.
Example requests
One reference image + motion prompt, lowest-cost validation.
{
"model": "grok-imagine/image-to-video",
"input": {
"image_urls": [
"https://example.com/reference.jpg"
],
"prompt": "camera slowly pushes forward, gentle motion",
"duration": 6,
"resolution": "480p"
}
}1080p output for the highest quality; this tier accepts a single input image only.
{
"model": "grok-imagine/image-to-video",
"input": {
"image_urls": [
"https://example.com/reference.jpg"
],
"prompt": "the subject slowly turns and smiles, hair gently moving",
"mode": "normal",
"duration": 8,
"resolution": "1080p"
}
}With multiple reference images, aspect_ratio applies and the output uses the selected framing.
{
"model": "grok-imagine/image-to-video",
"input": {
"image_urls": [
"https://example.com/reference-1.jpg",
"https://example.com/reference-2.jpg"
],
"prompt": "@image1 keeps the face, @image2 sets the background, the camera slowly orbits, soft studio light",
"mode": "normal",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}
}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 image-to-video?
Grok Imagine image-to-video is an AI video generation API on HiAPI that animates reference images into a cinematic short clip, called via POST /v1/tasks with model set to grok-imagine/image-to-video.
How many reference images can I pass?
image_urls accepts 1-7 images (JPEG/PNG/WEBP, 10MB each); SVG is not supported. When resolution is 1080p, exactly 1 image is allowed. You can reference specific images with @image1 etc. in the prompt.
Why does the output aspect ratio ignore my aspect_ratio value?
aspect_ratio only applies in multi-image reference mode. With a single input image the parameter has no effect and the output always follows the input image ratio; pass at least 2 reference images to select a framing.
Is 1080p a fixed 1920x1080 frame?
No. 1080p is a quality tier and actual pixels follow the input image ratio — a 4:3 input renders around 1664x1248 at 1080p.
Is the prompt required?
For image-to-video the prompt is optional and describes the desired motion direction and pacing; you can generate with just reference images.
Are long videos generated in segments?
Clips of 16-30 seconds, and multi-image clips longer than 10 seconds, are generated in segments and stitched, so visible seams are possible. Keep clips within 15 seconds (10 seconds with multiple images) when continuity matters.