Hailuo image-to-video requires two kinds of control: a creative brief for the motion and a valid model configuration. In MiniMax’s API, a longer duration and a higher resolution are not always compatible. A successful submission also creates a task, not an immediately downloaded video.
This guide covers the MiniMax-Hailuo-2.3 API workflow for readers planning an integration or evaluating its inputs. Hailuo’s consumer account interface is a separate workflow.
If you want browser-based character media without building an API integration, Cherrypop’s creator lets you start with an original character and continue into media. The technical workflow below serves a different need; no shared API or matching provider controls are implied.
Check the duration and resolution together
MiniMax’s image-to-video API reference lists six- or ten-second output at 768P for Hailuo 2.3 and 2.3 Fast, while 1080P supports six seconds for those models. Validate the pair rather than treating each dropdown or field independently.
| Named model | Six seconds | Ten seconds |
|---|---|---|
| MiniMax-Hailuo-2.3 | 768P or 1080P | 768P |
| MiniMax-Hailuo-2.3-Fast | 768P or 1080P | 768P |
If your brief needs ten seconds at the highest listed resolution, it contains a configuration conflict for these models. Resolve the conflict before submitting: shorten the action, accept the supported resolution or evaluate a different documented workflow. Do not assume that an invalid pair will be adjusted in the way you prefer.
For example, a six-second 1080P request can become invalid if your application changes only its duration to ten seconds. Validate the complete model-duration-resolution combination whenever one field changes. The table covers the two named 2.3 models; it is not a limit for every MiniMax model or a measure of output quality.
Prepare the first frame as an input asset
The API’s first_frame_image accepts a public image URL or a Base64-encoded Data URL, such as data:image/jpeg;base64,.... Include the Data URL prefix; the reference does not specify a bare Base64 string. MiniMax documents JPEG, PNG and WebP support, a file below 20 MB, a short edge above 300 pixels and an aspect ratio within 2:5 to 5:2. These are API requirements, not a statement about every upload surface carrying the Hailuo name.
Before sending an image URL, verify that the integration can retrieve the intended image. A page containing a photograph is different from a direct image response. Keep a checksum or stable local copy of the input so that a later retry does not silently use a replaced file at the same address.
For an example project, use an original photograph of a desk lamp. Decide whether the lamp itself should move or whether you only want a camera move around it. An uncluttered view of the hinge, base and shade gives you a clearer acceptance reference than a picture where those parts are hidden.
Do not add confidential imagery merely to test connectivity. A simple object image is enough to establish whether your asset preparation and retrieval work. Keep access credentials out of filenames, prompt text and ordinary diagnostic logs.
Make prompt behavior part of the experiment record
MiniMax documents an optional prompt of up to 2,000 characters and a prompt_optimizer setting that defaults to true. Both named 2.3 models support bracketed camera commands such as [Push in]. If you are comparing exact wording, record the optimizer setting as well as the text so you can distinguish the instruction you supplied from a request that allows automatic optimization.
An illustrative lamp brief is: “The desk lamp stays fixed while the camera moves slowly closer to its shade.” It identifies the moving element and the stationary element. Begin with one clear movement before adding a sequence of camera actions.
For an integration, a useful attempt record contains the input identifier, exact model, duration, resolution, prompt and optimizer setting. Give the attempt a purpose such as checking whether the base stays anchored. That produces a result you can act on, even when the clip is unsuitable.
Avoid interpreting every failure as a prompt issue. A request can fail validation, a task can fail while processing, or a completed video can fail the creative brief. Those are different failure classes with different next actions.
Submit and track the Hailuo image-to-video task
Send JSON to POST https://api.minimax.io/v1/video_generation with Content-Type: application/json and Authorization: Bearer API_KEY. The required body fields are model and first_frame_image. Set duration and resolution explicitly when they matter to the brief. Keep the key in your server configuration.
Inspect base_resp.status_code as well as the HTTP response. MiniMax defines code 0 as request success; the creation response supplies a task_id. Its documented errors include 2013 for invalid input parameters, 1004 for authentication failure and 1008 for insufficient balance. Changing the creative prompt will not repair incorrect credentials or a depleted balance.
The task-status reference specifies GET /v1/query/video_generation on the same API host, with task_id as a required query parameter and Bearer authentication. Only tasks under the current account can be queried. A successful query can still describe unfinished work: read status separately from base_resp.status_code.
The query states are Preparing, Queueing, Processing, Success and Fail. On success, the reference lists file_id, video_width and video_height. The creation page’s callback section instead documents lowercase processing, success and failed, despite saying the response structure matches the query API. Keep that documented spelling difference explicit if you later add callbacks; this guide follows polling.
| Stage | What you have | What should happen next |
|---|---|---|
| Request prepared | Validated input and chosen settings | Submit once and retain the response |
| Task accepted | Task identifier | Query that task’s state |
| Work pending | Preparing, Queueing or Processing | Keep it pending rather than create a duplicate |
| Work succeeded | File identifier and output metadata | Retrieve and verify the video |
| Work failed | Failure state and available diagnostic data | Classify the failure before deciding on another attempt |
The table is a suggested application design, not an API deduplication guarantee. If a submission times out after being sent, query the task if you retained its ID. If no ID reached your application, mark the submission as unresolved and review the account or contact provider support before resubmitting. The documented status endpoint requires an ID; it cannot resolve that uncertainty from your local clip name.
Store the task ID as soon as it is available. An application that keeps it only in a temporary browser view can lose track of work that continues after the page closes. A visible pending state is more honest than marking the job failed merely because the current screen stopped waiting.
Retrieve the file, then inspect the result
MiniMax’s video-download reference specifies GET /v1/files/retrieve with a file_id query parameter and Bearer authentication. Use the file ID returned by the successful task, preserving its full decimal value. The response is file information, including file.download_url; download the video from that URL as a separate step.
The reference says the download URL is valid for one hour. Save the video promptly alongside its task record. Do not treat the URL as a permanent archive or interpret its expiry as a reason to regenerate the video. The reference does not establish how long the underlying generated file remains retrievable.
After downloading, check that the file opens and that its dimensions and duration fit the chosen configuration. Then perform the creative review. A Success status establishes completion of a processing task; it does not establish that the lamp stayed fixed or that the video belongs in the final edit.
Inspect the shade, hinge and base at several moments. Watch for a camera move that becomes an object move, or an attractive lighting change that was never requested. Name the defect before changing anything. If the source obscures the hinge, prepare a better source; if the timing is wrong, revisit duration or the action description.
A small integration test worth completing first
Before building a large queue, run one authorized object-image request through every stage in your own account. Confirm that its task record survives a refresh, that pending work stays pending and that success leads to a saved, playable file. Separately exercise your application’s error handling with fixture responses for authentication failure, invalid parameters and a failed task; a successful generation alone cannot verify those paths.
Set a finite retry policy and separate request errors from creative retries. Keep a budget record for all submitted attempts, including outputs you reject. A batch’s useful yield is accepted clips divided by completed attempts, not the number of API responses that returned without a transport error.
Current account prices, processing speed and consumer-plan entitlements are outside this guide’s verified scope. Consult the actual selected configuration before committing a batch. The first milestone is one traceable, reviewable clip, with its input and cost intact from preparation to download.
When you want to create with a character instead
An API integration is useful when you need to manage submissions, task records and files in your own application. If your immediate goal is an original companion character, Cherrypop offers a browser workflow: define appearance, personality and a scenario, then continue into chat and supported media creation.
The Cherrypop video entry includes image-to-video and continuation modes. Treat that as an alternative task path, not an implementation of the API described above or a promise of identical duration, resolution or output quality.
Cherrypop is free to start with limits; relevant media may require Premium or Cherries. Check the displayed operation cost. Create the character and opening scenario when the interaction matters as much as the clip.