MiniMax H3 Video Generation API Integration Guide

This article introduces the integration and usage of the MiniMax H3 Video Generation API. This interface supports text-to-video generation, control of the first and last frames, and multi-modal reference video generation, using a unified V2 multi-modal content structure to create tasks.

Application Process

To use the MiniMax H3 Video Generation API, first go to the 辰汐ai Console to obtain your API Token for future use.

If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and will return to the current page automatically after completion.

One API Token can call all services on the platform, no need to apply separately for each service. The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the console.

📘 Complete Documentation: MiniMax H3 Video Generation API →

It is recommended to save the Token as an environment variable and not to write it into the source code or submit it to the version control system:

export ACEDATACLOUD_API_KEY="YOUR_API_KEY"

Interface Overview

  • Base URL: https://api.acedata.cloud
  • Endpoint: POST /minimax/videos
  • Authentication Method: Include authorization: Bearer {token} in the HTTP Header
  • Request Headers:
    • accept: application/json
    • content-type: application/json
  • Model: MiniMax-H3
  • Input Structure: Pass text, images, videos, and audio through the unified content
  • Output Mode: By default, wait synchronously for generation to complete and return the complete task; when passing async: true or callback_url, immediately return task_id and trace_id
  • Result Query: Use the MiniMax H3 Task Query API to get status and completed video
  • Asynchronous Callback: Optional, receive the final task result through callback_url

You do not need to pass action to select the generation mode; the interface will automatically determine the purpose based on the material types and role in content.

Suitable Scenarios

Scenario Input Combination Common Uses
Text-to-Video Text Advertising creativity, storyboard rehearsal, short videos, atmospheric shots
First Frame to Video Text + First Frame Image Make product images, posters, character photos, or illustrations come to life naturally
Last Frame / First and Last Frame Video Text + Last Frame, or Text + First Frame + Last Frame Control the opening and closing, transitions, growth changes, and before-and-after comparisons
Multi-modal Reference Video Text + Reference Images / Videos / Audio Maintain consistency in characters and products, replicate actions, camera movements, audio tones, or editing rhythms

Calling Process

By default, if async is not passed, /minimax/videos will wait for generation to complete and directly return the complete task. If you need to release the connection immediately, pass async: true or callback_url:

  1. Save the task_id and trace_id from the immediate response.
  2. If no callback is configured, call /minimax/tasks every 10 seconds to query.
  3. When task.status changes to succeeded, get the video from task.content.url.
  4. When the status is failed or cancelled, stop polling and read task.error.

Top-Level Request Parameters

Parameter Type Required Default Value Description
model string Yes - Fixed to MiniMax-H3
content object[] Yes - Multi-modal content array, must contain one non-empty text item
resolution string Yes - 768P or 2K
duration integer Yes - Generation duration, an integer between 4-15 seconds
ratio string Conditionally Required adaptive adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
async boolean No false When true, immediately returns task identifier, results can be obtained through the task interface
callback_url string No - Public callback URL to receive the final task result; automatically enables asynchronous mode when provided

The rules for ratio depend on the workflow:

  • Text-to-Video: Required and cannot be adaptive.
  • First Frame, Last Frame, or First and Last Frame Video: The aspect ratio is determined by the input image; it is recommended to omit or pass adaptive.
  • Multi-modal Reference Video: Can be omitted, default is adaptive; a fixed ratio can also be explicitly specified.

The interface does not accept legacy or compatible fields such as prompt, image_urls, audio_urls, messages, and first_frame_image. When receiving such parameter errors, please remove the old fields and migrate to content; for example, change "prompt": "A cat waving" to "content": [{"type": "text", "text": "A cat waving"}]. Do not send both new and old formats simultaneously.

Content Item Parameters

Each content item must have a type, and the other fields are determined by the type:

type Data Field role Description
text text Not passed Each request must contain one non-empty text item, up to 7000 characters
image_url image_url.url first_frame First frame image; if there is only one image and role is omitted, it is also treated as the first frame
image_url image_url.url last_frame Last frame image; can be used alone or combined with first_frame to control the start and end
image_url image_url.url reference_image Reference subject, character, product, clothing, scene, or style
video_url video_url.url reference_video Reference action, camera movement, performance, or editing structure
audio_url audio_url.url reference_audio Reference audio tone, dialogue, music, or rhythm

Media addresses support three forms:

  • Publicly accessible HTTPS URL, recommended for large files.
  • mm_file://{file_id}, referencing files that have already been uploaded or have existing results.
  • Base64 data URI corresponding to the media type. Base64 will increase the size by about one-third, please ensure the entire request body does not exceed 64 MB.

Material Specifications and Quantity Limits

Material Format Single File Limit Size / Duration Quantity Limit
Image JPG, JPEG, PNG, WEBP, HEIC, HEIF Up to 30 MB Width and height both between 256-5760 px; aspect ratio 0.4-2.5 Up to 1 first frame, up to 1 last frame, up to 9 reference images
Video MP4, MOV; H.264/AVC or H.265/HEVC; audio track AAC or MP3 Up to 50 MB Each segment 2-15 seconds, total not exceeding 15 seconds; width and height both between 256-5760 px; aspect ratio 0.4-2.5; 23.976-60 fps Up to 3 segments of reference video
Audio WAV, MP3 Up to 15 MB Each segment 2-15 seconds, total not exceeding 15 seconds Up to 3 segments of reference audio

In multimodal reference scenarios, the total number of images, videos, and audios is limited to 12 files. First and last frame scenarios and reference material scenarios are mutually exclusive: once reference_image, reference_video, or reference_audio is used, first_frame or last_frame cannot be used, and vice versa.

Production-Level Capability Demonstration

The following are not concept images or placeholder materials, but real reference inputs and actual video outputs of the MiniMax H3 official production-level capability samples. The three sets of cases cover brand short films, live-action narratives, and fashion e-commerce, suitable for evaluating the model's most critical capabilities in commercial production.

Capability Key Observations
Consistency of Characters and Faces Stability of facial features, hairstyles, makeup, and character temperament after multiple camera switches
Facial Performance Eye contact, micro-expressions, emotional tension, and natural head movements in close-ups
Product Structure Retention Contours, materials, wearing relationships, and mirror reflections of products like glasses and handbags
Brand Visual Execution Consistency of scene atmosphere, film grain, colors, logo, and editing rhythm
Cinematic Narrative Ability to form complete segments through changes in shot distance, character staging, camera movement, rhythm, and sound

Here, "facial capability" refers to the consistency of character appearance, facial details, and performance control in video generation, not identity recognition, face comparison, or face-swapping interfaces.

High-End Brand Short Film: Unity of Characters, Products, and Brand Assets

Production Goal: 16:9 high-end fashion brand film. Establish a stark atmosphere with a desert road and vintage cars, maintain the appearance of the female lead with the structure of a black handbag, and naturally incorporate the brand logo at the end. This case focuses on testing cross-shot character consistency, product retention, cinematic quality, and brand cohesion.

Atmosphere and Scene Reference Character Reference
Desert road and vintage car brand film atmosphere reference Brand film female lead reference
Handbag Product Reference Brand Logo Reference
Black handbag product reference Brand logo reference

Open or download the brand short film directly

The corresponding content organization is as follows:

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "15 seconds, 16:9 high-end fashion brand film. A vintage car parked by a desert road, the female lead takes a black handbag from the trunk and leaves alone after a brief eye contact with the male lead. Maintain consistency of characters, handbag, and brand visuals; stark and high-end, cinematic grain, crisp editing, and naturally present the brand logo at the end."
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://cdn.acedata.cloud/uploads/6e65f865-f1c2-4f80-8b51-9a98d4d930b1" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://cdn.acedata.cloud/uploads/88d89cc3-e6cb-42b4-ab4c-1bbbf6c9f7c8" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://cdn.acedata.cloud/uploads/e91f7fff-f8e3-4da5-b882-87edbc3c9473" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://cdn.acedata.cloud/uploads/b68dac43-fb14-42b5-bf8b-fd4d65506520" },
      "role": "reference_image"
    }
  ],
  "resolution": "2K",
  "duration": 15,
  "ratio": "16:9"
}

Live-Action Vertical Short Drama: Face Consistency and Emotional Performance

Production Goal: 15 seconds, 9:16 dark romantic short film trailer. The male and female protagonists' appearance is locked in by reference images, with the space constrained by reference images of a castle; using medium close-ups and facial close-ups to express the confrontation of gazes, fear, restraint, and a sense of danger. This case is suitable for observing the stability of human facial features, micro-expressions, gaze relationships, and continuous performances.

Male and Female Protagonist References Castle Scene References
Live-action short film male and female protagonist references Dark castle scene references

Directly open or download the live-action short film

The prompt should clearly define the character relationships, emotions, and shot types, rather than just describing "dialogue between a man and a woman":

15 seconds, 9:16 live-action dark romantic short film trailer. The female protagonist accidentally enters a forbidden castle, awakening a sleeping vampire noble; he approaches dangerously and restrained, while she is fearful but does not yield. Maintain consistency in the facial features, hairstyles, and costumes of both characters, using medium close-ups and facial close-ups to express the confrontation of gazes and emotional tension, with dark cinematic lighting and a tight rhythm.

Fashion Glasses Advertisement: Maintain Facial Details and Product Structure

Production Goal: 9:16 high-end fashion glasses advertisement. Full-body images of the characters are responsible for body shape and walking, facial reference images are responsible for facial features and makeup, and product images are responsible for surrounding curves, lens reflections, temples, and cat-eye contours. This case tests facial close-ups, consistency among multiple people, wearing relationships, and product geometric structures.

Model and Styling References Facial Detail References Glasses Product References
Fashion advertisement model and styling references Model facial detail references Glasses product structure references

Directly open or download the fashion glasses advertisement

In product advertisements, the prompt should clearly separate the responsibilities of character references and product references: character materials constrain the face, makeup, body shape, and temperament; product materials constrain the outline, material, reflection, and wearing position. This is more stable than vaguely writing "generate a glasses advertisement."

Text-to-Video

When there is only one text item, it is a text-to-video. It is suitable for directly generating images from creative, script, or shot descriptions. The prompt can be organized in the order of "subject + action + scene + shot + light + sound."

curl -X POST 'https://api.acedata.cloud/minimax/videos' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "15 seconds cinematic perfume advertisement: On the black rocks of the coast in the morning, a transparent perfume bottle is surrounded by mist and waves. Macro shots showcase water droplets on the bottle and glass refraction, with the camera slowly pulling back from the product close-up to the vast sea; silver-blue tones, real natural light, high-end restraint, ending with a freeze frame of the product."
      }
    ],
    "resolution": "2K",
    "duration": 15,
    "ratio": "16:9"
  }'

The default synchronous mode will return the complete task after generation:

{
  "task": {
    "id": "f5977217-ed2c-40da-adbe-93d08235618f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "content": { "url": "https://cdn.acedata.cloud/minimax/f5977217.mp4" },
    "resolution": "2K",
    "duration": 15,
    "ratio": "16:9"
  }
}

If the request includes "async": true, the interface will return immediately:

{
  "task_id": "f5977217-ed2c-40da-adbe-93d08235618f",
  "trace_id": "trace_7f8c2b1a"
}

First Frame Video Generation

Mark the image as first_frame, and the model will start generating from that frame. It is suitable for making posters, product images, character design images, and photographic works come to life naturally.

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "The character breathes naturally and looks out the window, the hem of their clothing is blown by the breeze, and the camera slowly pushes in."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.acedata.cloud/b1c82e4937.png"
      },
      "role": "first_frame"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

Last Frame and First-Last Frame Video

Only providing last_frame allows the model to naturally generate to the specified frame; at the same time, providing first_frame and last_frame can clearly control the starting and ending points. Suitable for transitions, shape changes, growth processes, or product comparisons before and after.

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "The girl naturally grows from childhood to youth, with time passing smoothly, and the character always positioned in the center of the frame."
    },
    {
      "type": "image_url",
      "image_url": { "url": "YOUR_FIRST_FRAME_URL" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "YOUR_LAST_FRAME_URL" },
      "role": "last_frame"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

The dimensions and aspect ratios of the first and last frames should be as consistent as possible, and the differences in the subject's position, composition, and lighting should not be too large, making it easier to achieve a natural transition.

Multi-modal Reference Live Video

Reference materials can be used in combination: reference images control the appearance of characters or products, reference videos control actions and camera movements, and reference audio controls dialogue tone, music, or editing rhythm. The prompt should clearly specify what each type of material is meant to control, avoiding the situation of only uploading materials without providing the relationships.

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "Keep the facial features, hairstyle, and clothing of the reference character consistent, and complete the fashion short film according to the performance actions in the reference video; the camera rhythm follows the reference audio, with close-ups highlighting natural facial expressions."
    },
    {
      "type": "image_url",
      "image_url": { "url": "YOUR_CHARACTER_IMAGE_URL" },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": { "url": "YOUR_PERFORMANCE_VIDEO_URL" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "YOUR_AUDIO_URL" },
      "role": "reference_audio"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

Callback Notification

Passing in callback_url will automatically enable asynchronous mode: the creation interface immediately returns task_id and trace_id, and after the task is completed, it POSTs the final result to that address, with a structure consistent with the task query response.

The final status in the callback is succeeded, failed, or cancelled. Even when using callbacks, it is recommended to save task_id for proactive queries or to compensate for missed notifications.

Common Errors

HTTP Status Code Meaning Suggested Action
400 Parameter error or invalid material combination Check required fields, role, material quantity, and format
401 Token missing or invalid Check Authorization: Bearer ...
402 Insufficient balance or quota Supplement general balance in the console
422 Content security check failed Adjust prompts or materials and resubmit
429 Too many requests Retry after exponential backoff; task polling is recommended to be about 10 seconds apart
500 Service temporarily unavailable Retain request information and retry later

In synchronous responses, task.status: succeeded indicates that the video has been generated; asynchronous confirmation only means the task has entered the queue. Only when the task is ultimately successful will billing occur; querying the task itself is free and will not incur repeated charges.