tencent cloud

LLM Service TokenHub

DokumentasiLLM Service TokenHubAPI Integration GuideVideo Generation ModelMiniMax API Guide

MiniMax API Guide

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-10 22:08:17
Diterjemahkan oleh AI

Overview

MiniMax Video (Hailuo Video) is a video generation model series launched by MiniMax, supporting capabilities such as text-to-video, image-to-video (first frame / first and last frames), and multimodal reference-to-video, with features including native 2K output and native stereo sound.
This document describes how to call two MiniMax video models through TokenHub: minimax-video-h3 and minimax-video-h3-max.
Note:
Both models uniformly use the content multimodal array for parameter passing. 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 asset types in the content array and the role field.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
Note:
In all examples below, YOUR_API_KEY must be replaced with your own API Key. The authentication method is the request header Authorization: Bearer YOUR_API_KEY.

Call Process

Video generation is a time-consuming task (typically 1 to 3 minutes), so the API uses an asynchronous call mode, which is divided into two steps:
1. Submit a task: Call POST /v1/wand/minimax-video-v2/generation, which returns a task_id upon success.
2. Poll for results: Call the query task result API with the task_id until task.status = succeeded, and obtain the video URL from task.content.url.
Note:
All API responses include request_id (at the top level, used for troubleshooting). Query APIs additionally return tokenhub_usage (usage consumption, including tokenhub_usage.total_tokens). Task status enumeration: queued / running / succeeded / failed / cancelled, subject to the actual response.

Model List

Model Name
model Parameter Value
Supported Capability
Video Duration (s)
Resolution Tier
Selection Recommendations
MiniMax-Video-H3
minimax-video-h3
Text-to-video / image-to-video (first and last frames) / multimodal reference-based generation
4 ~ 15
768P / 2K (1080P input is downgraded to 768P, and 4K input is downgraded to 2K)
Flagship model: 2K direct output, multimodal reference (image/video/audio), and native stereo sound.
MiniMax-Video-H3-Max
minimax-video-h3-max
Text-to-video / image-to-video (first frame / last frame), middle frames not supported.
5 to 15 (4 seconds not supported)
480P / 768P (2K not supported; 1080P / 2K / 4K input is silently downgraded to 768P).
H3 fast version: faster output and lower cost; does not support intermediate frames or multimodal reference video generation.
Note:
Rules for ratio (aspect ratio): required for text-to-video and cannot be adaptive; determined by the input image for image-to-video (always adaptive); optional for multimodal reference-to-video.

Text-to-Video

1. API Description

To generate a video using only text prompts, describe camera language such as camera movements directly in natural language within the prompt.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model name. Value: minimax-video-h3, minimax-video-h3-max
content
Yes
array[object]
Multimodal input array. For text-to-video, it contains only one text element. Subfields: type (text), text (prompt).
resolution
Yes
string
Video resolution. h3: 768P / 2K (1080P input is downgraded to 768P, and 4K input is downgraded to 2K); h3-max: only 480P / 768P, 2K not supported (1080P / 2K / 4K input is silently downgraded to 768P).
duration
Yes
integer
Video duration in seconds. h3: an integer from 4 to 15; h3-max: an integer from 5 to 15 (4 seconds not supported).
ratio
Yes
string
Aspect ratio. Required for text-to-video and cannot be adaptive (adaptive is processed as 16:9). Options: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16.
aigc_watermark
No
boolean
Whether to add an AIGC watermark. Default value: false.

3. Sample Request

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 faster version, replace model in the example with minimax-video-h3-max. Note that h3-max does not support 2K or a duration of 4 seconds.

4. Output Parameters

Field
Type
Description
task_id
string
Task ID of the generated task, used for polling to query task status.
request_id
string
Unique request identifier used for troubleshooting.
Note:
The submission response does not include base_resp. Whether the submission is successful depends on the HTTP status code and whether a task_id is returned.

5. Sample Response

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

6. Error Codes

When a request fails, an error code is returned. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". After a task is submitted successfully, the task status during the generation phase can be obtained through the "Query Task Result" API.

Image-to-Video (First Frame / First and Last Frames)

1. API Description

Generate a video using an image as the first frame (optionally as the last frame) combined with text prompts. The output aspect ratio follows the input image.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model name. Value: minimax-video-h3, minimax-video-h3-max
content
Yes
array[object]
Multimodal input array: 1 text + 1 to 2 image_url items (role is first_frame / last_frame; role can be omitted for the first frame). Image constraints: JPG / JPEG / PNG / WEBP / HEIC / HEIF; no more than 30 MB; width and height [256, 5760] px; aspect ratio [0.4, 2.5].
resolution
Yes
string
Video resolution. h3: 768P / 2K (1080P input is downgraded to 768P, and 4K input is downgraded to 2K); h3-max: only 480P / 768P, 2K not supported (1080P / 2K / 4K input is silently downgraded to 768P).
duration
Yes
integer
Video duration in seconds. h3: an integer from 4 to 15; h3-max: an integer from 5 to 15 (4 seconds not supported).
ratio
No
string
Aspect ratio. Defaults to adaptive for image-to-video (determined by the input image); 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
No
boolean
Whether to add an AIGC watermark. Default value: false.
Note:
minimax-video-h3-max supports first frames and last frames, but does not support intermediate frames.

3. Sample Request

First 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
}'

4. Output Parameters

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

5. Sample Response

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

6. Error Codes

When a request fails, an error code is returned. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". The task status description is the same as that in "Text-to-Video".

Multimodal Reference-to-Video (H3 Only)

1. API Description

Generate a video using a combination of text and reference images, reference videos, or reference audio as the reference. Only minimax-video-h3 supports this feature. minimax-video-h3-max does not support multimodal reference input, and if reference_image, reference_video, or reference_audio appears in content, a parameter error is returned directly. Audio-only input is not allowed. At least one reference video or image must be included.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model name. Value: minimax-video-h3
content
Yes
array[object]
Multimodal input array: 1 text + reference materials (role is reference_image / reference_video / reference_audio). Reference images: no more than 9; reference videos: no more than 3; reference audio clips: no more than 3; total materials: no more than 12. See the following table for subfields and material constraints.
resolution
Yes
string
Video resolution. Options: 768P / 2K.
duration
Yes
integer
Video duration in seconds. Options: an integer from 4 to 15.
ratio
No
string
Aspect ratio. Defaults to adaptive (automatic); can be explicitly set to 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16.
aigc_watermark
No
boolean
Whether to add an AIGC watermark. Default value: false.
Subfields of content array elements:
Parameter Name
Required
Type
Description
type
Yes
string
Material type. Enum values: text / image_url / video_url / audio_url.
text
Conditionally required
string
Text prompt. Required when type=text (each request must contain a non-empty text item).
image_url
Conditionally required
object
Image material. Required when type=image_url. Structure: { "url": "..." }
video_url
Conditionally required
object
Video material. Required when type=video_url. Structure: { "url": "..." }
audio_url
Conditionally required
object
Audio material. Required when type=audio_url. Structure: { "url": "..." }
role
No
string
Material purpose. Enum 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 roles reference_image / reference_video / reference_audio appears in content, first_frame / last_frame cannot appear, and vice versa.
Reference video: MP4 / MOV (H.264 / H.265), no more than 50 MB, no more than 3 segments, each segment 2 to 15 seconds with a total duration of no more than 15 seconds, resolution from 256 to 5760 px in width and height, and frame rate from 23.976 to 60 fps.
Reference audio: WAV / MP3, no more than 15 MB, no more than 3 segments, each segment 2 to 15 seconds with a total duration of no more than 15 seconds. Audio-only input is not allowed.
The total request body size must not exceed 64 MB. For large files, use a public network URL instead of Base64.

3. Sample Request

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"
}'

4. Output Parameters

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

5. Sample Response

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

6. Error Codes

When a request fails, an error code is returned. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". The task status description is the same as that in "Text-to-Video".

Querying the Task Result

1. API Description

Task query method shared by all generation capabilities: After a task is submitted and a task_id is returned, poll the task status through the unified task query endpoint. Upon success, obtain 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 (represented by YOUR_TASK_ID in the example). Video generation takes approximately 1 to 3 minutes, so polling every 3 to 5 seconds is recommended.

2. Input Parameters

Parameter Name
Required
Type
Description
task_id
Yes
string
Task ID (path parameter), which is the task_id returned when the task is submitted.

3. Sample Request

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

4. Output Parameters

Field
Type
Description
task
object
Task object.
task.id
string
Task ID.
task.model
string
Model name used, such as MiniMax-H3 and MiniMax-H3-Max.
task.status
string
Task status: queued / running / succeeded / failed.
task.task_type
string
Task type, such as generation (video generation).
task.created_at
integer
Task creation time, Unix timestamp in seconds.
task.updated_at
integer
Task update time, Unix timestamp in seconds.
task.content
object
Content of the generated task result, returned on success.
task.content.url
string
Download URL of the generated video. It is a temporary URL valid for 12 hours. Download and save it promptly.
task.duration
integer
Video duration in seconds.
task.resolution
string
Video resolution, such as 768P.
task.ratio
string
Video aspect ratio, such as 16:9.
task.usage
object
Task video usage information.
task.usage.input_image_count
integer
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
Usage consumption of this request.
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing and reconciliation.
request_id
string
Unique request identifier used for problem locating and troubleshooting.
Note:
The query response is a task object without base_resp or a top-level status. The task identifier and status are in task.id / task.status.

5. Sample Response

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"
}

6. Error Codes

status
Description
Handling Recommendation
succeeded
Generation succeeded
Obtain the video URL from task.content.url.
queued / running
Queued / Generating
Poll once every 3 to 5 seconds until the operation succeeds.
failed
Generation failed
Check the failure cause (see task.error), make modifications, and retry. If the failure persists, 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
Request succeeded.
401
1000
Authentication failed
Authorization is missing or the apikey is invalid.
401
1001
Authorization is empty
The Authorization header is not carried.
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 exception
Account exception (possibly due to overdue payment, suspension, or ban).
429
1101
Account in arrears (postpaid)
The postpaid account has an overdue payment.
429
1102
Resource pack depleted or expired
The resource pack has been used up or has expired.
403
1103
Access denied for the requested resource
No access to the requested resource (the corresponding model/capability is not subscribed).
400
1200
Invalid request parameters
Invalid request parameters (missing required fields, incorrect types, out-of-range enum values, and so on).
400
1201
Invalid parameters
Invalid parameter value. 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
Trigger the platform strategy
Triggers a platform policy (such as failed content moderation or non-compliant input).
400
1301
Trigger platform sensitive word list
The content contains sensitive words or non-compliant prompts.
429
1302
Too frequent API calls
The calls are too frequent, triggering rate limiting.
429
1303
Concurrency or QPS exceeds the limit
The concurrency or QPS exceeds the preset quota.
400
1304
Trigger IP strategy
Triggers IP address policy-based interception.
500
5000
Internal server error
Internal server error.
503
5001
Server is temporarily unavailable
The service is temporarily unavailable (usually due to high load or maintenance).
504
5002
Server internal timeout
Internal server timeout.

General Material Constraints

Image: JPG / JPEG / PNG / WEBP / HEIC / HEIF; no more than 30 MB; width and height from 256 to 5760 px; aspect ratio from 0.4 to 2.5; first frame no more than 1, last frame no more than 1, reference images no more than 9.
Video (reference video, h3 only): MP4 / MOV (H.264 / H.265, audio AAC / MP3); no more than 50 MB; no more than 3 segments; each segment 2 to 15 seconds with a total duration of no more than 15 seconds; width and height from 256 to 5760 px; aspect ratio from 0.4 to 2.5; frame rate from 23.976 to 60 fps.
Audio (reference audio, h3 only): WAV / MP3; no more than 15 MB; no more than 3 segments; each segment 2 to 15 seconds with a total duration of no more than 15 seconds.
Note:
The total request body size must not exceed 64 MB. For large files, use a public network URL instead of Base64.

FAQs

1. How to Choose Between the Two Models?

For 2K direct output, multimodal reference (reference image/video/audio), and a minimum duration of 4 seconds: minimax-video-h3.
For H3 image quality with faster generation and lower cost, without multimodal reference: minimax-video-h3-max.

2. What Are the Limits on Duration and Resolution?

h3: duration 4 to 15 seconds; resolution 768P / 2K (1080P input is downgraded to 768P, and 4K is downgraded to 2K).
h3-max: duration 5 to 15 seconds (4 seconds is not supported); resolution 480P / 768P only, and 1080P / 2K / 4K input is silently downgraded to 768P.

3. How Are Camera Movements Controlled?

Describe camera movements in natural language within the prompt, such as "the camera slowly pushes in" or "the camera pans left". No special command syntax is required.

4. Do Generated Video Links Expire?

The link will expire. The generated result is a temporary address valid for 12 hours. After the task succeeds, download the video file promptly and transfer it to your own storage. Do not rely on this link for long-term use.

Topik sebelumnya: Kling API GuideTopik selanjutnya: Hy API Guide

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation