MiniMax โ
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 โ
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Guardrail bypass support | Supported |
Prerequisites โ
- You have registered a Tencent Cloud account and activated the TokenHub service.
- You have obtained an API Key from the TokenHub console.
- You have enabled pay-as-you-go for the target model under Console - Online Inference - Vision Models.
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 โ
| Version | Resolution | Ratio | Duration | Selection guidance |
|---|---|---|---|---|
minimax-video-h3 | 768P / 2K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 | 4 ~ 15 seconds | Flagship: direct 2K output, multimodal references (image / video / audio), native stereo audio. |
minimax-video-h3-max | 480P / 768P | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 | 5~15 seconds | H3 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 โ
| Version | Input |
|---|---|
minimax-video-h3 | Text-to-video / image-to-video (first and last frame) / reference-based multimodal generation |
minimax-video-h3-max | Text-to-video / image-to-video (first frame / last frame); intermediate frames are not supported. |
Resolution Conversion โ
| Version | Input resolution | Output resolution |
|---|---|---|
minimax-video-h3 | 1080P / 4K | 768P / 2K |
minimax-video-h3-max | 1080P / 2K / 4K | 768P |
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.
- Submit the task: Call
POST /v1/wand/minimax-video-v2/generation; on success,task_idis returned. - Poll for the result: Call the task result query API with
task_iduntil the state becomestask.status = succeeded, then retrieve the video URL fromtask.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 โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model name. Values: minimax-video-h3, minimax-video-h3-max |
| content | Required | array[object] | The multimodal input array. For text-to-video, it contains only one text element. Subfields: type (text), text (the prompt). |
| resolution | Required | string | Video 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). |
| duration | Required | integer | Video duration in seconds. h3: an integer in 4~15; h3-max: an integer in 5~15 (4 seconds is not supported). |
| ratio | Required | string | Aspect 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_watermark | Optional | boolean | Whether to add an AIGC watermark. Default: false. |
Request Example โ
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 โ
| Field | Type | Description |
|---|---|---|
| task_id | string | The task ID of the created task, used to poll and query the task state. |
| request_id | string | A 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 โ
{
"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 โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model name. Values: minimax-video-h3, minimax-video-h3-max |
| content | Required | array[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). |
| resolution | Required | string | Video 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). |
| duration | Required | integer | Video duration in seconds. h3: an integer in 4~15; h3-max: an integer in 5~15 (4 seconds is not supported). |
| ratio | Optional | string | Aspect 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_watermark | Optional | boolean | Whether 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:
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 โ
{
"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 โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model name. Value: minimax-video-h3 |
| content | Required | array[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. |
| resolution | Required | string | Video resolution. Options: 768P / 2K. |
| duration | Required | integer | Video duration in seconds. Options: an integer in 4~15. |
| ratio | Optional | string | Aspect 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_watermark | Optional | boolean | Whether to add an AIGC watermark. Default: false. |
Subfields of content array elements:
| Parameter | Required | Type | Description |
|---|---|---|---|
| type | Required | string | Material type. Enumerated values: text / image_url / video_url / audio_url. |
| text | Conditionally required | string | Text prompt. Required when type=text (each request must include a non-empty text item). |
| image_url | Conditionally required | object | Image 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_url | Conditionally required | object | Video 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_url | Conditionally required | object | Audio 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": "..." } |
| role | Optional | string | Material 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 โ
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 โ
{
"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 โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| task_id | Required | string | The task ID (path parameter), which is the task_id returned when the task was submitted. |
Request Example โ
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 โ
| Field | Type | Description |
|---|---|---|
| task | object | The task object. |
| task.id | string | Task ID. |
| task.model | string | The model name used (for example, MiniMax-H3, MiniMax-H3-Max). |
| task.status | string | Task state: queued / running / succeeded / failed. |
| task.task_type | string | Task type (for example, generation (video generation)). |
| task.created_at | integer | Task creation time, as a Unix timestamp in seconds. |
| task.updated_at | integer | Task update time, as a Unix timestamp in seconds. |
| task.content | object | The content of the created task result, returned on success. |
| task.content.url | string | The download URL of the generated video. It is a temporary URL valid for 12 hours, so download and save it immediately. |
| task.duration | integer | Video duration in seconds. |
| task.resolution | string | Video resolution (for example, 768P). |
| task.ratio | string | Video aspect ratio (for example, 16:9). |
| task.usage | object | The video usage information for the task. |
| task.usage.input_image_count | integer | The number of input images. |
| task.usage.input_seconds | integer | Input video duration in seconds. |
| task.usage.output_seconds | integer | Output video duration in seconds. |
| task.usage.total_seconds | integer | Total video duration in seconds. |
| tokenhub_usage | object | The usage for this request. |
| tokenhub_usage.total_tokens | integer | The number of tokens consumed by this task, used for billing and settlement. |
| request_id | string | A 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:
{
"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 โ
| status | Description | Recommended handling |
|---|---|---|
| succeeded | Generation succeeded | Retrieve the video URL from task.content.url. |
| queued / running | Waiting in queue / generating | Poll once every 3~5 seconds until the task succeeds. |
| failed | Generation failed | Check 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 code | Business code | Error message | Description |
|---|---|---|---|
200 | 0 | Success | The request succeeded. |
401 | 1000 | Authentication failed | Authorization is missing or the apikey is invalid. |
401 | 1001 | Authorization is empty | The Authorization header was not passed. |
401 | 1002 | Authorization is invalid | The apikey is invalid or has expired. |
401 | 1003 | Authorization is not yet valid | The apikey is not yet valid. |
401 | 1004 | Authorization has expired | The apikey has expired. |
429 | 1100 | Account anomaly | Account anomaly (which may be due to overdue payment, suspension, or a ban). |
429 | 1101 | Account overdue (postpaid) | Payment for the postpaid account is overdue. |
429 | 1102 | Resource pack exhausted or expired | The resource pack has been exhausted or has expired. |
403 | 1103 | Access to the requested resource denied | The requested resource cannot be accessed (the corresponding model/feature is not subscribed). |
400 | 1200 | Bad request parameter | The request parameters are incorrect (a required field is missing, a type is wrong, an enumerated value is out of range, and so on). |
400 | 1201 | Invalid parameter | The parameter value is incorrect. Check the valid value range in the documentation. |
404 | 1202 | The requested method is invalid | The HTTP method is incorrect. |
404 | 1203 | The requested resource does not exist | The endpoint path is incorrect or the resource does not exist. |
400 | 1300 | Platform policy triggered | A platform policy was triggered (for example, content moderation failed or the input was non-compliant). |
400 | 1301 | Platform sensitive word list triggered | The content contains sensitive words or non-compliant prompts. |
429 | 1302 | API call frequency is too high | The call frequency is too high and rate limiting was triggered. |
429 | 1303 | Concurrency or QPS exceeds the limit | The concurrency count or QPS exceeded the preset quota. |
400 | 1304 | IP policy triggered | Blocking based on an IP address policy was triggered. |
500 | 5000 | Internal server error | Internal server error. |
503 | 5001 | Server temporarily unavailable | The service is temporarily unavailable (usually due to high load or maintenance). |
504 | 5002 | Server internal timeout | Server 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
2Koutput, multimodal references (reference image/video/audio), or a minimum duration of4 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, resolution768P/2K(1080Pinput is downgraded to768P, and4Kis downgraded to2K). - h3-max: duration
5~15 seconds(4 secondsis not supported); resolution supports only480P/768P, and1080P/2K/4Kinput is downgraded to768Pwithout 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.
4. Do generated video links expire? โ
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.