Model description

MiniMax-H3 (Video Generation V2) supports text-to-video, image-to-video (with start and end frames), and multimodal reference-to-video capabilities, as well as H3-Context-IR prompt enhancement and upscaling regeneration from 768P to 2K.

Functional Interface Details

Create a video generation task

Create a video generation task. The model generates a video based on the incoming multimodal information such as text, images, videos, and audios. This interface is an asynchronous interface, and it will return task_idafter successful creation. You need to polling the task status through the task query interface, and obtain the generated video after the task succeeds.

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation

Request Header

Parameter Name	Field Type	Required or not	Description
Authorization	string	Yes	`Bearer {YOUR_AK}`
Content-Type	string	Yes	Please set the media type of the request body to `application/json`.

Request Body Parameters

Parameter Name	Field Type	Required or not	default value	Description
content	array	Yes	-	An array of multimodal input content that describes the information used to generate the video. Each element is distinguished by its `type` (`text`/ `image_url`/ `video_url`/ `audio_url`), and its usage can be labeled via the `role` parameter.
resolution	string	Yes	-	Video resolution. Current available values: `768P`, `2K`.
duration	integer	Yes	-	Video duration (in seconds), required, integer. Available values: `4`\~ `15`.
ratio	string	Conditions	`adaptive`	Specify the aspect ratio of the generated video; the default value is `adaptive` (automatic, the most suitable aspect ratio is selected via Self-Adaptation based on the input, and the actual ratio can be obtained from the `ratio`field of the query interface). Available values: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.
callback_url	string	No	-	The callback notification address for task status changes. After configuration, the MiniMax server will first send a verification request containing the `challenge`field (you need to return the `challenge`as-is within 3 seconds to complete the verification). Once the verification succeeds, a POST push will be sent to this address whenever the task status changes, and the structure of the push payload is consistent with the response of the task query interface.
aigc_watermark	boolean	No	`false`	Whether to add an AIGC identification watermark to the generated video, the default `false`.

Description of the content field:

Each request must contain a non-empty text field (prompt is required); a parameter error will be returned if it is missing.

Supported input combinations (corresponding to different generation scenarios): - Text-to-Video : Only one text element. - Image-to-Video - First Frame : text + 1 image_url (role= first_frame or left blank). - Image-to-Video - Last Frame: text + 1 image_url (role= last_frame). - Image-to-Video (First and Last Frame): text + 2 image_urls (with roles as first_frame and last_frame respectively). - Multimodal Reference Video Generation: a combination of text + reference image (role= reference_image) + reference video (role= reference_video) + reference audio (role= reference_audio); audio cannot be input alone, and at least 1 reference video or image must be included.

> Mutual Exclusivity Between Image-to-Video and Multimodal Reference-to-Video : If any of the roles reference_image / reference_video / reference_audio appears in content, first_frame / last_frame cannot appear (and vice versa), and the two sets of parameters cannot be mixed. Input Media Restrictions (Total request body size ≤ 64 MB. For large files, please use a public network URL instead of Base64), as detailed in the sub-table below.

Text-to-video (t2va, where content only contains text): ratiois required and cannot be set to adaptive; valid values are 21:9, 16:9, 4:3, 1:1, 3:4, 9:16.

Image-to-video (i2va, where content includes first_frame/ last_frameimages): The aspect ratio is determined by the input image, and ratiois always adaptive; passing other valid values will not trigger an error, but will be ignored and processed as adaptive.

Multimodal reference-to-video generation (r2va, with content including reference_image/ reference_video/ reference_audio): ratiois optional, defaulting to adaptive; any of the specific ratios listed above can also be explicitly specified.

content[] element field

Parameter Name	Field Type	Required or not	default value	Description
type	string	Yes	-	The type of input content. Enumeration values: `text`/ `image_url`/ `video_url`/ `audio_url`.
text	string	Conditions	-	Text prompt, required: A non-empty `text`describing the expected generated video must be included for all scenarios. The length is calculated by the number of characters, and a single `text`can contain up to 7000 characters.
image_url	object	Conditions	-	When `type= image_url`, this is the corresponding image object (refer to the content description above for restrictions on format, size, dimensions and quantity).
image_url.url	string	Yes	-	Image address, supported formats: public URL;`mm_file://{file_id}`(referencing existing files on the platform, e. g. file_id of uploaded or historical assets);`data: image/<format>;base64,<Base64>`data URI (`<format>`in lowercase).
video_url	object	Conditions	-	When `type= video_url`, this is the video object (reference video, only for multimodal reference scenarios; refer to the content description above for format/size/duration restrictions).
video_url.url	string	Yes	-	Video address, supported formats: public URL;`mm_file://{file_id}`(file_id of an existing file on the platform for reference);`data: video/mp4;base64,<Base64>`data URI. Note that the total size of the request body must be ≤ 64 MB; Base64 encoding will increase the size by approximately 33%, please use a public URL or mm_file:// for large videos.
audio_url	object	Conditions	-	When `type= audio_url`, this is the audio object (reference audio, only for multimodal reference scenarios; refer to the content description above for format/size/duration restrictions).
audio_url.url	string	Yes	-	Audio address, supported formats: public URL;`mm_file://{file_id}`(file_id of an existing file on the platform) `data: audio/<format>;base64,<Base64>`data URI (`<format>`in lowercase).
role	string	Conditions	-	Position or purpose of the content, conditionally required: - `first_frame`: First frame image (for image-to-video; when only one image is provided and role is left blank, it will be processed as first_frame by default). - `last_frame`: Last frame image (for image-to-video with start and end frames, must be used in pairs with first_frame). - `reference_image`: Reference image (for multimodal reference video generation). - `reference_video`: Reference video (for multimodal reference video generation). - `reference_audio`: Reference audio (multimodal reference for video generation, cannot be input alone).

Image image_urlRestriction

Item	Restrictions
Format	JPG、JPEG、PNG、WEBP、HEIC、HEIF
Single File Size	≤ 30 MB
Width and Height Range	[256, 5760] px
Aspect Ratio (Width/Height)	[0.4, 2.5]
Quantity	First frame ≤ 1, last frame ≤ 1, reference image ≤ 9

Video video_url (for multimodal reference scenarios only)

Item	Restrictions
Container / Format	MP4（`.mp4`）、MOV（`.mov`）
Encoding	Video: H. 264/AVC, H. 265/HEVC; Audio: AAC, MP3
Single File Size	≤ 50 MB
number	≤ 3
Single segment duration	[2,15] s; total duration ≤ 15 s
Width and Height Range	[256, 5760] px
Aspect Ratio (Width/Height)	[0.4, 2.5]
frame rate	[23.976, 60]

Audio audio_url (for multimodal reference scenarios only)

Item	Restrictions
Format	WAV、MP3
Single File Size	≤ 15 MB
number	≤ 3
Single segment duration	[2,15] s; total duration ≤ 15 s

Response Parameters

Parameter Name	Field Type	Description
task_id	string	Task ID, which is used for subsequent query of task status and results.

Request Example

Text-to-Video:

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "content": [
    {
      "type": "text",
      "text": "..."
        }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "16:9"
}'

Image-to-Video (First Frame):

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "content": [
    {
      "type": "text",
      "text": "Pull focus to the people in the background and add more steam to the ramen bowl."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png"
      },
      "role": "first_frame"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}'

Response Example

{
  "task_id": "424010985738629"
}

Create H3-Context-IR Task

H3-Context-IR deeply understands multimodal contexts such as text, images, audio and video, analyzes the relationships between creatives as well as between creatives and the target generation result, and conducts complex logical reasoning. The system will convert the understanding results into structured expressions, and enrich semantic details while keeping the user's original intention as intact as possible. This interface only returns enhanced prompts and does not create video generation tasks.

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/h3_context_ir

Request Header

Parameter Name	Field Type	Required or not	Description
Authorization	string	Yes	`Bearer {YOUR_AK}`
Content-Type	string	Yes	Please set the media type of the request body to `application/json`.

Request Body Parameters

Parameter Name	Field Type	Required or not	default value	Description
content	array	Yes	-	An array of multimodal context inputs, used to describe the relationships between the target video and various creatives. Each element distinguishes its type via `type` (`text`/ `image_url`/ `video_url`/ `audio_url`), and can have its usage labeled via `role`. Each request must contain a non-empty `text`entry (prompt is required); a parameter error will be returned if this is missing. The supported input combinations, mutual exclusion rules and media restrictions are the same as those specified in "3.1 Create Video Generation Task".
duration	integer	Yes	-	Target video duration (in seconds), required, integer. Valid values: `4`\~ `15`.
ratio	string	Conditions	`adaptive`	The aspect ratio of the target video, defaults to `adaptive`. Available values: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Text-to-video (t2va, where content only contains `text`): `ratio`is required and cannot be `adaptive`; available values are `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Image-to-video (i2va, where content includes `first_frame`and `last_frame`images): The aspect ratio is determined by the input image, and `ratio`is always `adaptive`; Passing other valid values will not throw an error, but will be ignored and processed as `adaptive`. Multimodal reference-generated video (r2va, content includes `reference_image`/ `reference_video`/ `reference_audio`): `ratio`is optional, defaulting to `adaptive`; Any of the specific ratios listed above can also be explicitly specified.
callback_url	string	No	-	Callback notification address for task status changes. After configuration, the MiniMax server will first send a verification request containing the `challenge`field (it needs to return the `challenge`as it is within 3 seconds to complete the verification). After successful verification, whenever the task status changes, it will POST push to this address. The push body structure is consistent with the response of the query task interface. Callback `status`values: `queued` (queued), `running` (running), `succeeded` (succeeded), `failed` (failed), `cancelled` (cancelled).

content[]The element fields are the same as those in Section 3.1.3.

Response Parameters

Parameter Name	Field Type	Description
task_id	string	Task ID, which is used for subsequent queries of task status and results.

Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/h3_context_ir' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "content": [
    {
      "type": "text",
      "text": "一个男孩在海边打篮球"
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}'

Response Example

{
  "task_id": "426586401755526"
}

Create a video regeneration task

Regenerate the source video that meets the output specifications of MiniMax-H3 768P into a 2K video. Two input modes are supported, source_task_idand content (including base_video), and exactly one of them must be provided (a parameter error will be returned if both are provided or neither is provided):

Regenerate by Task ID (source_task_id): Pass in the source_task_idof an existing successful video generation task to regenerate based on its output as the source. This mode requires allowlist access; the source task must belong to the current account, be in succeededstatus, and still be within the 7-day query window for task queries. There is no need to pass contentagain.
Regeneration based on source video (base_video): Provide one and only one source video entry with contentthat has type= video_urland role= base_video, and attach the rest of the inputs used to generate this 768P video as-is.

This interface is an asynchronous interface, and a task_idwill be returned after successful creation. You can query the task status via task polling; the task_typeis regeneration.

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_regeneration

Request Header

Parameter Name	Field Type	Required or not	Description
Authorization	string	Yes	`Bearer {YOUR_AK}`
Content-Type	string	Yes	Please set the media type of the request body to `application/json`.

Request Body Parameters

Parameter Name	Field Type	Required or not	default value	Description
source_task_id	string	Conditions	-	task_id of existing successfully completed video generation tasks , to regenerate based on the output of the original task. Usage restrictions: allowlist access is required; the source task must belong to the current account, be in `succeeded`status, and still be queryable via the task inquiry interface (created within the last 7 days). Exactly one of this parameter and `content` must be provided.
content	array	Conditions	-	Array of input content for video regeneration (sorted by source video mode). Please include the following in the array: All inputs actually fed into the model when generating the 768P source video must be submitted exactly as they are. Among them, `text`must use the final prompt that was actually fed into the model at that time, and the original prompt before H3-Context-IR processing must not be used; all reference images, videos and audios must also be consistent with those used during generation. Any inconsistency in the inputs may lead to failure to achieve the expected regeneration effect - One 768P source video item, `type= video_url`and `role= base_video`；there must be exactly one such item. `The base_video` must comply with the following MiniMax-H3 768P output specifications. This interface does not support general regeneration of arbitrary videos. --- Input media restrictions: The total size of the request body must be ≤ 64 MB. For large files, please use a public network URL instead of Base64.The restrictions on the format and per-file size of reference images/videos/audio are the same as those specified in "3.1 Create a Video Generation Task. As regards `source_task_id` , exactly one must be provided.
resolution	string	Yes	-	The target resolution for video regeneration, required. Currently supported `2K`.
callback_url	string	No	-	Callback URL for task status change, optional. Its behavior is the same as that of the `callback_url`when creating a video generation task.
aigc_watermark	boolean	No	-	Optional setting indicating whether to add an AIGC watermark to the generated video; the default value is `false`.

base_video Specifications

Project	Specifications
soundtrack	Must contain a soundtrack; videos without a soundtrack are not supported
frame rate	24 fps
Width / Height	shall all be divisible by 32
Area (Width × Height)	≤ 768 × 1344 (1,032,192 pixels)
Total Frames	107–362 frames, in increments of 17 frames per step (approximately 4–15 seconds)

content[] Element Field (Regenerated)

Parameter Name	Field Type	Required or not	default value	Description
type	string	Yes	-	The type of input content. Enumeration values: `text`/ `image_url`/ `video_url`/ `audio_url`.
text	string	Conditions	-	You must use the final prompt that was actually fed into the model when generating the 768P source video, and must not use the original prompt before H3-Context-IR processing. The length is calculated by the number of characters, and a single `text`can contain up to 7000 characters.
image_url	object	Conditions	-	When `type= image_url`, this is the corresponding image object (refer to the content description above for restrictions on format, size, dimensions and quantity).
image_url.url	string	Yes	-	Image address, supported formats: public URL;`mm_file://{file_id}`(referencing existing files on the platform, e. g. file_id of uploaded or historical assets);`data: image/<format>;base64,<Base64>`data URI (`<format>`in lowercase).
video_url	object	Conditions	-	When `type= video_url`, this is the video object (reference video, only for multimodal reference scenarios; refer to the content description above for format/size/duration restrictions).
video_url.url	string	Yes	-	Video address, supported formats: public URL;`mm_file://{file_id}`(file_id of an existing file on the platform for reference);`data: video/mp4;base64,<Base64>`data URI. Note that the total size of the request body must be ≤ 64 MB; Base64 encoding will increase the size by approximately 33%, please use a public URL or mm_file:// for large videos.
audio_url	object	Conditions	-	When `type= audio_url`, this is the audio object (reference audio, only for multimodal reference scenarios; refer to the content description above for format/size/duration restrictions).
audio_url.url	string	Yes	-	Audio address, supported formats: public URL;`mm_file://{file_id}`(file_id of an existing file on the platform) `data: audio/<format>;base64,<Base64>`data URI (`<format>`in lowercase).
role	string	Conditions	-	Position or purpose of the content, required conditionally: - `base_video`: source video for video regeneration (for `/v2/video_regeneration`only);The source video item must explicitly set this `role`, and there must be exactly 1 entry in `content`. - `first_frame`: first frame image (for image-to-video; processed as first_frame by default when there is only one image and role is not specified). - `last_frame`: The last frame image (for image-to-video with start and end frames, must be used in pairs with first_frame). - `reference_image`: Reference image (for multimodal reference video generation). - `reference_video`: Reference video (for multimodal reference video generation). - `reference_audio`: Reference audio (for multimodal reference video generation, cannot be input alone).

Response Parameters

Parameter Name	Field Type	Description
task_id	string	Task ID, which is used for subsequent query of task status and results.

Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_regeneration' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "content": [
    {
      "type": "text",
      "text": "..."
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://your-cdn.example.com/h3-t2va-768p.mp4"
      },
      "role": "base_video"
    }
  ],
  "resolution": "2K"
}'

Response Example

{
  "task_id": "424010985738631"
}

Query Task

Query task_idto check the status and results of a single video generation, H3-Context-IR, or video regeneration task within the last 7 days. After the task succeeds (status= succeeded), you can obtain the output from content: for video tasks, retrieve content. url; for H3-Context-IR tasks, retrieve the enhanced prompt from content. prompt.

Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/query/video_generation/{task_id}

Request Header

Parameter Name	Field Type	Required or not	Description
Authorization	string	Yes	`Bearer {YOUR_AK}`

Path Parameters

Parameter Name	Field Type	Required or not	Description
task_id	string	Yes	The ID of the task to be queried (the `task_id`returned when the task is created).

Response Parameters

Parameter Name	Field Type	Description
task	object	The task object returned by the H3 shared task query and list interface.
task.id	string	Task ID.
task.model	string	The name of the model used for the task, e. g. `MiniMax-H3`.
task.status	string	Task Status: - `queued`: Queued - `running`: Running - `succeeded`: Succeeded - `failed`: Failed - `cancelled`: Cancelled
task.error	object	Error message, not returned when the task succeeds; returned when the task fails `code`and `message`.
task.error.code	string	Error code.
task.error.message	string	Error prompt message.
task.created_at	integer	Unix timestamp (in seconds) indicating the task creation time.
task.updated_at	integer	The Unix timestamp (in seconds) indicating when the task status was last updated.
task.content	object	Task output content, which will be returned upon successful task completion.
task.content.url	string	This is a time-limited download URL for the video task output. Please download or transfer it in time; you can re-inquire to obtain a new one after it expires.
task.content.prompt	string	Structured augmented prompt generated by the H3-Context-IR task. Returned only when `task_type= h3_context_ir`and the task succeeds.
task.resolution	string	The resolution of the task output.
task.duration	integer	Duration of the task output (in seconds).
task.usage	object	The billable usage for this request. Video tasks return a field measured in seconds; H3-Context-IR tasks return a token usage field.
task.usage.total_seconds	integer	Total billable seconds this time = Input seconds + Output seconds.
task.usage.input_seconds	integer	Enter the billing seconds of the reference video (including the time count for the reference video).
task.usage.output_seconds	integer	Output the billed seconds of the video.
task.usage.input_image_count	integer	The number of images involved in this billing cycle.
task.usage.total_tokens	integer	The total number of tokens used in the H3-Context-IR task.
task.usage.prompt_tokens	integer	The number of input tokens for the H3-Context-IR task.
task.usage.completion_tokens	integer	The number of output tokens for the H3-Context-IR task.
task.ratio	string	The aspect ratio of the task product; an empty string may be returned when this parameter is not applicable to the current task type.
task.task_type	string	Task Type: - `generation`: Video Generation - `h3_context_ir`: H3-Context-IR (`/v2/h3_context_ir`) - `regeneration`: Video Regeneration (`/v2/video_regeneration`)
task.modality	string	Output modality. The video generation and video regeneration tasks return `video`; the H3-Context-IR task returns `text`.

Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/query/video_generation/{task_id}' \
--header 'Authorization: Bearer {YOUR_AK}'

Response Example

Video generated successfully:

{
  "task": {
    "id": "424010985738629",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/89f8c0bbee5b_denoise_ids_0_final.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

H3-Context-IR Success:

{
  "task": {
    "id": "426586401755526",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785702855,
    "updated_at": 1785702884,
    "content": {
      "prompt": "integrated_multimodal_description: ..."
    },
    "duration": 5,
    "usage": {
      "total_tokens": 9090,
      "prompt_tokens": 5664,
      "completion_tokens": 3426
    },
    "ratio": "16:9",
    "task_type": "h3_context_ir",
    "modality": "text"
  }
}

Cancel or delete tasks

Cancel or delete video generation, H3-Context-IR and video regeneration tasks according to the current status of the tasks:

Task Status	Perform the action	Description
`queued` (queuing)	`cancelled`	Cancel the task: the task has not started processing and no fees will be deducted.
`succeeded` (succeeded)	`deleted`	Delete Task Record
`failed` (failed)	`deleted`	Delete Task Record
`running` (in operation)	—	Not actionable, an error will be returned (cancellation is not allowed during processing)
`cancelled` (cancelled)	—	Inoperable, return an error

Request URL

DELETE https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation/{task_id}

Request Header

Parameter Name	Field Type	Required or not	Description
Authorization	string	Yes	`Bearer {YOUR_AK}`

Path Parameters

Parameter Name	Field Type	Required or not	Description
task_id	string	Yes	The ID of the task to be canceled or deleted.

Response Parameters

Parameter Name	Field Type	Description
task_id	string	The ID of the task to be operated on.
action	string	Actual operation performed: `cancelled` (cancel, only for queued status) or `deleted` (delete task records regardless of success or failure).
status	string	Operation result status: `cancelled` (cancelled) or `deleted` (record deleted).

Request Example

curl --location --request DELETE 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation/{task_id}' \
--header 'Authorization: Bearer {YOUR_AK}'

Response Example

{
  "task_id": "424010985738629",
  "action": "cancelled",
  "status": "cancelled"
}