Skip to content

MiniMax โ€‹

Updated

Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generationAuthentication: Tokenhub API Key / Bearer

MiniMax Video (Hailuo Video) is MiniMax's video generation model family, supporting text-to-video, image-to-video (first frame / first-and-last frame), and multimodal reference-to-video, with features such as direct 2K output and native stereo audio. H3 supports text plus multimodal reference generation from images, video, and audio; H3 Max supports text and first-frame / last-frame input.

Both models pass parameters via the same content multimodal array. The submission endpoint is POST /v1/wand/minimax-video-v2/generation and the query endpoint is GET /v1/wand/minimax-video-v2/tasks/{task_id}. Text-to-video, image-to-video, and multimodal reference-to-video share the same submission endpoint, distinguished by the material type and role inside the content array.

Basic Information โ€‹

ItemValue
Call pathTokenhub API
Guardrail bypass supportSupported

Prerequisites โ€‹

Note: In all examples below, replace YOUR_API_KEY with your own API Key. Authentication uses the request header Authorization: Bearer YOUR_API_KEY.

Supported Specifications by Version โ€‹

VersionResolutionRatioDurationSelection guidance
minimax-video-h3768P / 2K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:164 ~ 15 secondsFlagship: direct 2K output, multimodal references (image / video / audio), native stereo audio.
minimax-video-h3-max480P / 768P21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:165~15 secondsH3 high-speed version: faster output, lower cost; does not support intermediate frames or multimodal reference-to-video.

Note: ratio (aspect ratio) rules: required and cannot be adaptive for text-to-video; determined by the input image for image-to-video (always adaptive); optional for multimodal reference-to-video.

Input Modes โ€‹

VersionInput
minimax-video-h3Text-to-video / image-to-video (first and last frame) / reference-based multimodal generation
minimax-video-h3-maxText-to-video / image-to-video (first frame / last frame); intermediate frames are not supported.

Resolution Conversion โ€‹

VersionInput resolutionOutput resolution
minimax-video-h31080P / 4K768P / 2K
minimax-video-h3-max1080P / 2K / 4K768P

H3 Max does not support intermediate frames or multimodal reference input.

Call Procedure โ€‹

Video generation is a long-running operation (typically 1~3 minutes), so API uses an asynchronous call pattern consisting of the following two steps.

  1. Submit the task: Call POST /v1/wand/minimax-video-v2/generation; on success, task_id is returned.
  2. Poll for the result: Call the task result query API with task_id until the state becomes task.status = succeeded, then retrieve the video URL from task.content.url.

Note: Every API response includes a top-level request_id used for troubleshooting. The query API also returns tokenhub_usage, which indicates usage (including tokenhub_usage.total_tokens). The task state enumeration is queued / running / succeeded / failed / cancelled; refer to the actual response.

Text-to-Video โ€‹

API Description โ€‹

To generate a video using only a text prompt, describe camera work and other shot behavior directly in natural language within the prompt.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

Request Parameters โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel name. Values: minimax-video-h3, minimax-video-h3-max
contentRequiredarray[object]The multimodal input array. For text-to-video, it contains only one text element. Subfields: type (text), text (the prompt).
resolutionRequiredstringVideo resolution. h3: 768P / 2K (1080P input is downgraded to 768P, and 4K input is downgraded to 2K); h3-max: supports only 480P / 768P and does not support 2K (1080P / 2K / 4K input is downgraded to 768P without a separate notice).
durationRequiredintegerVideo duration in seconds. h3: an integer in 4~15; h3-max: an integer in 5~15 (4 seconds is not supported).
ratioRequiredstringAspect ratio. Required for text-to-video, and adaptive cannot be used (adaptive is handled as 16:9). Options: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16.
aigc_watermarkOptionalbooleanWhether to add an AIGC watermark. Default: false.

Request Example โ€‹

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "An orange kitten on the windowsill looks toward the camera"
    }
  ],
  "resolution": "2K",
  "duration": 6,
  "ratio": "16:9"
}'

Note: To call the high-speed version, replace model in the example with minimax-video-h3-max. h3-max does not support the 2K or 4 seconds duration.

Response Parameters โ€‹

FieldTypeDescription
task_idstringThe task ID of the created task, used to poll and query the task state.
request_idstringA unique request identifier used for troubleshooting.

Note: The submission response does not include base_resp. Whether submission succeeded is judged by the HTTP status code and whether task_id is returned.

Response Example โ€‹

json
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

Error Codes โ€‹

If a request fails, an error code is returned. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". After a task is submitted successfully, the task state during the generation phase can be checked via the "Query task result" API.

Image-to-Video (First Frame / First and Last Frame) โ€‹

API Description โ€‹

Uses an image as the first frame, optionally also designating it as the last frame, and then combines it with a text prompt to generate a video. The output aspect ratio follows the input image.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

Request Parameters โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel name. Values: minimax-video-h3, minimax-video-h3-max
contentRequiredarray[object]The multimodal input array: text 1 + image_url item 1~2 (role is first_frame / last_frame; role can be omitted for the first frame). Image constraints: JPG / JPEG / PNG / WEBP / HEIC / HEIF, width and height [256, 5760] px, aspect ratio [0.4, 2.5], single image โ‰ค 30 MB; URL or Base64 is supported.
โ€ข URL: must be publicly accessible (http / https).
โ€ข Base64: total size of all images โ‰ค 75 MB, and โ‰ค 100 MB after Base64 encoding; format is data:image/<format>;base64,<encoded> (use jpeg for jpg images).
resolutionRequiredstringVideo resolution. h3: 768P / 2K (1080P input is downgraded to 768P, and 4K input is downgraded to 2K); h3-max: supports only 480P / 768P and does not support 2K (1080P / 2K / 4K input is downgraded to 768P without a separate notice).
durationRequiredintegerVideo duration in seconds. h3: an integer in 4~15; h3-max: an integer in 5~15 (4 seconds is not supported).
ratioOptionalstringAspect ratio. The default for image-to-video is adaptive (determined by the input image), and you can also explicitly specify 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16. Other values are ignored without an error.
aigc_watermarkOptionalbooleanWhether to add an AIGC watermark. Default: false.

Note: minimax-video-h3-max supports the first and last frame but does not support intermediate frames.

Request Example โ€‹

First-frame and last-frame generation:

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "Transition naturally from the first frame to the last frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/start.jpg"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/end.jpg"
      },
      "role": "last_frame"
    }
  ],
  "resolution": "768P",
  "duration": 6
}'

Response Parameters โ€‹

Same as the output parameters of "Text-to-Video".

Response Example โ€‹

json
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

Error Codes โ€‹

If a request fails, an error code is returned. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". The task state descriptions are the same as in "Text-to-Video".

Multimodal Reference-to-Video (H3 Only) โ€‹

API Description โ€‹

Generates a video by combining text with reference images, reference videos, or reference audio. This feature supports only minimax-video-h3. minimax-video-h3-max does not support multimodal reference input; if reference_image, reference_video, or reference_audio is present in content, a parameter error is returned immediately. Audio alone cannot be the input. At least one reference video or image must be included.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

Request Parameters โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel name. Value: minimax-video-h3
contentRequiredarray[object]The multimodal input array: text 1 + reference material (role is reference_image / reference_video / reference_audio). Reference images: up to 9; reference videos: up to 3; reference audio clips: up to 3; all material: up to 12 items. For subfields and material constraints, see the table below.
resolutionRequiredstringVideo resolution. Options: 768P / 2K.
durationRequiredintegerVideo duration in seconds. Options: an integer in 4~15.
ratioOptionalstringAspect ratio. The default is adaptive (automatic), and it can also be explicitly set to 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16.
aigc_watermarkOptionalbooleanWhether to add an AIGC watermark. Default: false.

Subfields of content array elements:

ParameterRequiredTypeDescription
typeRequiredstringMaterial type. Enumerated values: text / image_url / video_url / audio_url.
textConditionally requiredstringText prompt. Required when type=text (each request must include a non-empty text item).
image_urlConditionally requiredobjectImage material. Required when type=image_url. URL or Base64 is supported. Constraints: JPG / JPEG / PNG / WEBP / HEIC / HEIF, width and height [256, 5760] px, aspect ratio [0.4, 2.5], single image โ‰ค 30 MB; Base64 format is data:image/<format>;base64,<encoded> (use jpeg for jpg). Structure: { "url": "..." }
video_urlConditionally requiredobjectVideo material. Required when type=video_url. URL or Base64 is supported. Constraints: MP4 / MOV, each segment 2~15 seconds with a total duration โ‰ค 15 seconds, single file โ‰ค 50 MB; the total Base64 size of all reference videos โ‰ค 64 MB, format is data:video/<format>;base64,<encoded> (use quicktime for mov). Structure: { "url": "..." }
audio_urlConditionally requiredobjectAudio material. Required when type=audio_url. URL or Base64 is supported. Constraints: WAV / MP3, each segment 2~15 seconds, single file โ‰ค 15 MB; the total size of all audio โ‰ค 48 MB and โ‰ค 64 MB after Base64 encoding, format is data:audio/<format>;base64,<encoded> (use mpeg for mp3). Structure: { "url": "..." }
roleOptionalstringMaterial purpose. Enumerated values: first_frame / last_frame / reference_image / reference_video / reference_audio.

Note: Image-to-video and multimodal reference generation are mutually exclusive. If any of the reference_image / reference_video / reference_audio roles is present in content, first_frame / last_frame cannot be used, and vice versa. Reference videos: MP4 / MOV (H.264 / H.265), no larger than 50 MB, up to 3 segments, each segment 2~15 seconds with a total duration no longer than 15 seconds, width and height resolution 256~5760 px, frame rate 23.976~60 fps. Reference audio: WAV / MP3, no larger than 15 MB, up to 3 segments, each segment 2~15 seconds with a total duration no longer than 15 seconds. Audio alone cannot be the input. The total request body size cannot exceed 64 MB. For large files, use a public network URL instead of Base64.

Request Example โ€‹

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "The character in the reference image moves naturally within the scene of the reference video"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/character.jpg"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/scene.mp4"
      },
      "role": "reference_video"
    }
  ],
  "resolution": "768P",
  "duration": 6,
  "ratio": "16:9"
}'

Response Parameters โ€‹

Same as the output parameters of "Text-to-Video".

Response Example โ€‹

json
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

Error Codes โ€‹

If a request fails, an error code is returned. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". The task state descriptions are the same as in "Text-to-Video".

Querying Task Results โ€‹

API Description โ€‹

The task query method shared by all generation features. After submitting a task and receiving task_id, poll the task state via the unified task query endpoint. On success, retrieve the video URL from the result.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/tasks/{task_id}

Note: The {task_id} in the path is the task_id returned when the task was submitted, shown as YOUR_TASK_ID in the examples. Video generation takes roughly 1~3 minutes, so polling every 3~5 seconds is recommended.

Request Parameters โ€‹

ParameterRequiredTypeDescription
task_idRequiredstringThe task ID (path parameter), which is the task_id returned when the task was submitted.

Request Example โ€‹

bash
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Parameters โ€‹

FieldTypeDescription
taskobjectThe task object.
task.idstringTask ID.
task.modelstringThe model name used (for example, MiniMax-H3, MiniMax-H3-Max).
task.statusstringTask state: queued / running / succeeded / failed.
task.task_typestringTask type (for example, generation (video generation)).
task.created_atintegerTask creation time, as a Unix timestamp in seconds.
task.updated_atintegerTask update time, as a Unix timestamp in seconds.
task.contentobjectThe content of the created task result, returned on success.
task.content.urlstringThe download URL of the generated video. It is a temporary URL valid for 12 hours, so download and save it immediately.
task.durationintegerVideo duration in seconds.
task.resolutionstringVideo resolution (for example, 768P).
task.ratiostringVideo aspect ratio (for example, 16:9).
task.usageobjectThe video usage information for the task.
task.usage.input_image_countintegerThe number of input images.
task.usage.input_secondsintegerInput video duration in seconds.
task.usage.output_secondsintegerOutput video duration in seconds.
task.usage.total_secondsintegerTotal video duration in seconds.
tokenhub_usageobjectThe usage for this request.
tokenhub_usage.total_tokensintegerThe number of tokens consumed by this task, used for billing and settlement.
request_idstringA unique request identifier used to locate and troubleshoot problems.

Note: The query response is a task object without base_resp or a top-level status. The task identifier and state are located in task.id / task.status.

Response Example โ€‹

Generation succeeded:

json
{
  "task": {
    "id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
    "model": "MiniMax-H3-Max",
    "task_type": "generation",
    "status": "succeeded",
    "created_at": 1772345678,
    "updated_at": 1772345810,
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "content": {
      "url": "https://example.com/output-video.mp4"
    },
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    }
  },
  "tokenhub_usage": {
    "total_tokens": 102655
  },
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

Error Codes โ€‹

statusDescriptionRecommended handling
succeededGeneration succeededRetrieve the video URL from task.content.url.
queued / runningWaiting in queue / generatingPoll once every 3~5 seconds until the task succeeds.
failedGeneration failedCheck the cause of failure (see task.error), fix it, and retry. If failures persist, contact technical support and provide the request_id.

For request-level error codes, see "Appendix: Unified Error Codes".

Appendix โ€‹

Unified Error Codes โ€‹

HTTP status codeBusiness codeError messageDescription
2000SuccessThe request succeeded.
4011000Authentication failedAuthorization is missing or the apikey is invalid.
4011001Authorization is emptyThe Authorization header was not passed.
4011002Authorization is invalidThe apikey is invalid or has expired.
4011003Authorization is not yet validThe apikey is not yet valid.
4011004Authorization has expiredThe apikey has expired.
4291100Account anomalyAccount anomaly (which may be due to overdue payment, suspension, or a ban).
4291101Account overdue (postpaid)Payment for the postpaid account is overdue.
4291102Resource pack exhausted or expiredThe resource pack has been exhausted or has expired.
4031103Access to the requested resource deniedThe requested resource cannot be accessed (the corresponding model/feature is not subscribed).
4001200Bad request parameterThe request parameters are incorrect (a required field is missing, a type is wrong, an enumerated value is out of range, and so on).
4001201Invalid parameterThe parameter value is incorrect. Check the valid value range in the documentation.
4041202The requested method is invalidThe HTTP method is incorrect.
4041203The requested resource does not existThe endpoint path is incorrect or the resource does not exist.
4001300Platform policy triggeredA platform policy was triggered (for example, content moderation failed or the input was non-compliant).
4001301Platform sensitive word list triggeredThe content contains sensitive words or non-compliant prompts.
4291302API call frequency is too highThe call frequency is too high and rate limiting was triggered.
4291303Concurrency or QPS exceeds the limitThe concurrency count or QPS exceeded the preset quota.
4001304IP policy triggeredBlocking based on an IP address policy was triggered.
5005000Internal server errorInternal server error.
5035001Server temporarily unavailableThe service is temporarily unavailable (usually due to high load or maintenance).
5045002Server internal timeoutServer internal timeout.

General Material Constraints โ€‹

Images: JPG / JPEG / PNG / WEBP / HEIC / HEIF, no larger than 30 MB, width and height 256~5760 px, aspect ratio 0.4~2.5, first frame up to 1, last frame up to 1, reference images up to 9 items.

Video (reference video, h3 only): MP4 / MOV (H.264 / H.265, audio AAC / MP3), no larger than 50 MB, up to 3 segments, each segment 2~15 seconds with a total duration no longer than 15 seconds, width and height 256~5760 px, aspect ratio 0.4~2.5, frame rate 23.976~60 fps.

Audio (reference audio, h3 only): WAV / MP3, no larger than 15 MB, up to 3 segments, each segment 2~15 seconds with a total duration no longer than 15 seconds.

Note: The total request body size cannot exceed 64 MB. For large files, use a public network URL instead of Base64.

FAQ โ€‹

1. Which of the two models should I choose? โ€‹

  • When you need direct 2K output, multimodal references (reference image/video/audio), or a minimum duration of 4 seconds: minimax-video-h3.
  • When you do not need multimodal references but want H3 image quality with faster generation and lower cost: minimax-video-h3-max.

2. What are the duration and resolution limits? โ€‹

  • h3: duration 4~15 seconds, resolution 768P / 2K (1080P input is downgraded to 768P, and 4K is downgraded to 2K).
  • h3-max: duration 5~15 seconds (4 seconds is not supported); resolution supports only 480P / 768P, and 1080P / 2K / 4K input is downgraded to 768P without a separate notice.

3. How do I control camera movement? โ€‹

Describe the camera movement in natural language in the prompt, such as "the camera slowly zooms in" or "the camera pans to the left". No special command syntax is required.

Links do expire. Generation results are temporary addresses valid for 12 hours. After the task succeeds, download the video file immediately and transfer it to your own storage. Do not rely on this link for long-term use.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages