Create Image-to-Video Task

Hailuo image-to-video API guide: turn a first-frame image plus prompt and camera directives into video with MiniMax-Hailuo models, with parameters and examples.

(Hailuo Image-to-Video)

This endpoint lets you upload a starting-frame image (a static image) and combine it with a text description and camera directives to generate a dynamic video.

Quick Start

Video generation is asynchronous. The whole flow takes three steps:

1. Submit the task → get a task_id
2. Poll the status → wait for status to become completed and return a public URL

📌 Basics

Endpoint: POST /v1/video/generations
Authentication: Bearer Token (Authorization: Bearer {{YOUR_API_KEY}})
Content type: application/json

📥 Request Parameters (Request Body)

Parameter	Type	Required	Description
model	`string`	Yes	Model name. Recommended: `MiniMax-Hailuo-2.3`, `MiniMax-Hailuo-2.3-Fast`, `I2V-01-Director`.
prompt	`string`	Yes	Video motion description (max 2000 characters). Supports camera control via directives such as `[Push in]`, `[Truck left]`.
duration	`integer`	Yes	Video duration in seconds. Options: `6` or `10` (depending on the model).
metadata	`object`	Yes	Extended metadata.
└─ first_frame_image	`string`	Yes	Starting-frame image. Supports a public URL or a Base64 Data URL.
└─ resolution	`string`	No	Resolution. Options: `512P`, `768P`, `1080P`.
└─ prompt_optimizer	`boolean`	No	Whether to automatically optimize the prompt (default true).
└─ callback_url	`string`	No	Callback URL for task status notifications.
└─ aigc_watermark	`boolean`	No	Whether to add a watermark (default false).

🖼️ Image Requirements

Formats: JPG, JPEG, PNG, WebP
Size: less than 20MB
Dimensions: shorter side > 300px, aspect ratio between 2:5 and 5:2.

🎥 Camera Directives (Partial List)

Add [] directives to the prompt for precise camera movement:

Dolly: [Push in], [Pull out]
Trucking/Pedestal: [Truck left], [Truck right], [Pedestal up], [Pedestal down]
Pan/Tilt: [Pan left], [Pan right], [Tilt up], [Tilt down]
Zoom: [Zoom in], [Zoom out]

📝 Request Example

{
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "Contemporary dance, the people in the picture are performing, [Push in]",
  "duration": 6,
  "metadata": {
    "first_frame_image": "https://example.com/start_frame.png",
    "resolution": "1080P",
    "prompt_optimizer": true,
    "aigc_watermark": false
  }
}

📤 Response

Status code: 200 OK

Field	Type	Description
task_id	`string`	Unique task identifier for querying progress later.
status	`string`	Current status (e.g. `queued`, `processing`).

💡 Developer Tips

Image-prompt consistency: The prompt should describe motion that builds on the content of first_frame_image. If the image is a static landscape but the prompt describes intense human action, results may be poor.
Fast model: If generation speed matters, use the MiniMax-Hailuo-2.3-Fast model.
Resolution strategy: The MiniMax-Hailuo-02 model supports at most 768P when generating 10s videos.

Create Image-to-Video Task

On this page