Skip to content
Sign Up Free
MiniMax H3

MiniMax H3 video API: generation and regeneration

Connect to MiniMax H3 with a BetterToken API Key and choose fields, media and generation methods by Model ID and operation.

Generate videos from text, first and last frames or reference media. You can also regenerate your own eligible 768p H3 video at 2k. Regeneration accepts only the source task ID, not new media URLs.

Prepare your BetterToken API Key. The Base URL is https://bettertoken.ai/v1, with Authorization: Bearer YOUR_API_KEY for authentication. Copy the Model ID exactly, including capitalization.

Every request.json below follows the same workflow: quote, confirm creation, poll and download. A quote does not start generation; creating a task submits a paid request. See current costs in the model plaza.

Models and operations

The table below lists available values by operation. See each subsection for field defaults, media counts and combination constraints. Media sizes use 1 MB = 1048576 bytes.

Model IDOperationDuration (seconds)Output levelAspect ratioAudioMedia roles
MiniMax-H3image_to_video4–15, step 1768p, 2kadaptiveprovider_defaultfirst_frame, last_frame, reference_image, reference_video, reference_audio
MiniMax-H3reference_to_video4–15, step 1768p, 2kadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16provider_defaultreference_image, reference_video, reference_audio
MiniMax-H3text_to_video4–15, step 1768p, 2k21:9, 16:9, 4:3, 1:1, 3:4, 9:16provider_defaultNone
MiniMax-H3video_editinherited from the source task2kadaptive (inherited)provider_defaultsource task ID

provider_default uses the model’s audio settings and provides no on / off switch. Regeneration inherits the aspect ratio, duration and input from the source task.

Sample media

The image-to-video and image-reference examples use a blue ceramic mug on a white table. Keep the sample image to try them, or first replace it with public HTTPS media that you have the right to use and that meets this page’s limits.

Video generation reference: a blue ceramic mug on a white table

Text-to-video

MiniMax-H3

Use this operation when you have only a text description.

Set model to this subsection’s Model ID and operation to text_to_video. Use only the generation fields listed below. Put media in the media array.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoprovider_defaultprovider_default
duration.modestringNofixedfixed
duration.secondsintegerNo4–15, step 1 s; only for fixed duration4
output.aspect_ratiostringYes21:9, 16:9, 4:3, 1:1, 3:4, 9:16None
output.formatstringNomp4mp4
output.resolutionstringNo768p, 2k768p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "MiniMax-H3",
"operation": "text_to_video",
"prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "768p",
"aspect_ratio": "16:9"
}
}

Common 422 errors

422 error codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.

Image-to-video

MiniMax-H3

Use this operation to set the opening frame or both the first and last frames with images.

Set model to this subsection’s Model ID and operation to image_to_video. Use only the generation fields listed below. Put media in the media array.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoprovider_defaultprovider_default
duration.modestringNofixedfixed
duration.secondsintegerNo4–15, step 1 s; only for fixed duration4
output.aspect_ratiostringNoadaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo768p, 2k768p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
first_frameimage, optional, at most 1jpg, jpeg, png, webp, heic, heifsize at most 30 MB; width 256–5760 px; height 256–5760 px
last_frameimage, optional, at most 1jpg, jpeg, png, webp, heic, heifsize at most 30 MB; width 256–5760 px; height 256–5760 px
reference_imageimage, optional, at most 9jpg, jpeg, png, webp, heic, heifsize at most 30 MB; width 256–5760 px; height 256–5760 px
reference_videovideo, optional, at most 3mp4, movsize at most 50 MB; width 256–5760 px; height 256–5760 px; duration 2–15 s; frame rate at least 23.976 fps, and at most 60 fps; total for this role at most 15 s
reference_audioaudio, optional, at most 3wav, mp3size at most 15 MB; duration 2–15 s; total for this role at most 15 s

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Provide at least one of these roles: first_frame, last_frame.
  • Do not combine first or last frames with reference images, videos or audio. Use image-to-video for first and last frames, and reference generation for reference media.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "MiniMax-H3",
"operation": "image_to_video",
"prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "768p",
"aspect_ratio": "adaptive"
},
"media": [
{
"id": "first",
"type": "image",
"role": "first_frame",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

Common 422 errors

422 error codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
mutually_exclusive_rolesUse first/last frames and reference media separately.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

Reference generation

MiniMax-H3

Use this operation to preserve subject or motion characteristics from reference media.

Set model to this subsection’s Model ID and operation to reference_to_video. Use only the generation fields listed below. Put media in the media array.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoprovider_defaultprovider_default
duration.modestringNofixedfixed
duration.secondsintegerNo4–15, step 1 s; only for fixed duration4
output.aspect_ratiostringNoadaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16adaptive
output.formatstringNomp4mp4
output.resolutionstringNo768p, 2k768p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
reference_imageimage, optional, at most 9jpg, jpeg, png, webp, heic, heifsize at most 30 MB; width 256–5760 px; height 256–5760 px
reference_videovideo, optional, at most 3mp4, movsize at most 50 MB; width 256–5760 px; height 256–5760 px; duration 2–15 s; frame rate at least 23.976 fps, and at most 60 fps; total for this role at most 15 s
reference_audioaudio, optional, at most 3wav, mp3size at most 15 MB; duration 2–15 s; total for this role at most 15 s

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Provide at least one of these roles: reference_image, reference_video, reference_audio.
  • Do not combine first or last frames with reference images, videos or audio. Use image-to-video for first and last frames, and reference generation for reference media.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "MiniMax-H3",
"operation": "reference_to_video",
"prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "768p",
"aspect_ratio": "adaptive"
},
"media": [
{
"id": "reference",
"type": "image",
"role": "reference_image",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

Common 422 errors

422 error codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
mutually_exclusive_rolesUse first/last frames and reference media separately.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

Video regeneration

MiniMax-H3

Use this operation to regenerate your own 768p H3 video at 2k with the same content. It does not accept arbitrary video files.

The source task must meet all these conditions:

  • It belongs to your account and its Model ID is MiniMax-H3.
  • Generation succeeded and the video is still downloadable.
  • Its output is set to 768p.
  • It was created no more than 7 days ago.

The server also checks the source video’s format. Ineligible sources return 422 video_regeneration_source_invalid. Quote with the source task ID; do not modify a video file yourself to replace the source task.

Request fieldTypeRequiredValue
modelstringYesMiniMax-H3
operationstringYesvideo_edit
provider_options.hailuo.source_task_idstringYesYour eligible source task ID
watermarkbooleanNofalse / true, default false

Do not send prompt, duration, output, audio or media. Regeneration inherits the source task’s content and input, and outputs 2k, adaptive, MP4.

Replace REPLACE_WITH_YOUR_H3_TASK_ID with your own source task ID before quoting and creating. This creates a new paid task, so use a new state file.

{
"model": "MiniMax-H3",
"operation": "video_edit",
"provider_options": {
"hailuo": {
"source_task_id": "REPLACE_WITH_YOUR_H3_TASK_ID"
}
}
}

If the source task is ineligible or does not exist, quoting returns 422 video_regeneration_source_invalid with field_path set to provider_options.hailuo.source_task_id. The following example identifies this error and cannot be used for generation:

{
"model": "MiniMax-H3",
"operation": "video_edit",
"provider_options": {
"hailuo": {
"source_task_id": "video_DOES_NOT_EXIST"
}
}
}

Official resources

When calling BetterToken, use this page’s fields and the corresponding operation in the live model catalog.