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 768P-to-2K regeneration.

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 `type` (`text` / `image_url` / `video_url` / `audio_url`), and its purpose can be labeled via `role`.
resolution	string	Yes	-	Video resolution. Current available values: `MiniMax-H3`: `768P`, `2K` `MiniMax-H3-Max`: `480P`, `768P` (default: `768P`, `2K` not supported)
duration	integer	Yes	-	Video generation duration (in seconds), mandatory, integer. Available values `MiniMax-H3`: `4`~`15` `MiniMax-H3-Max`: `5` – `15` (4 seconds not supported)
ratio	string	Conditions	`adaptive`	Specify the aspect ratio for video generation; the default value is `Self-Adaptation` (automatic mode, where the most suitable aspect ratio is automatically selected based on the input, and the actual ratio can be obtained from the `ratio` field of the query interface). Supported values: `Self-Adaptation`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.
callback_url	string	No	-	The callback notification address for task status changes. Once configured, 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). After successful verification, 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 is `false`.

Description of the content field:

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

Supported input combinations (corresponding to different generation scenarios):
- Text-to-video: a single text element only.
- Image-to-video (first frame): text + 1 image_url (role=first_frame or left unset).
- Image-to-video (last frame): text + 1 image_url (role=last_frame).
- Image-to-video (first and last frames): text + 2 image_url entries (with roles first_frame and last_frame respectively).
- Multimodal reference-to-video: text + reference image (role=reference_image) + reference video (role=reference_video) + reference audio (role=reference_audio) in combination; audio alone cannot be used as the sole input — at least 1 reference video or image must be included.

> Image-to-video and multimodal reference-to-video are mutually exclusive: if any of reference_image / reference_video / reference_audio appears as a role in content, first_frame / last_frame must not appear (and vice versa); the two cannot be mixed.

Input media restrictions (total request body size ≤ 64 MB; for large files, use a public URL instead of Base64) — see the sub-tables 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 video generation (r2va, content includes reference_image/ reference_video/ reference_audio): ratiois optional, defaulting to adaptive; any of the specific ratios 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 video to be generated 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	-	The image object when `type= image_url` (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 refers to the video object (reference video, only for multimodal reference scenarios; refer to the content description above for format, size and 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);`data: video/mp4;base64,<Base64>`data URI. Note that the total size of the request body must be ≤ 64 MB; Base64 encoding increases the size by approximately 33%, so use a public URL or mm_file:// for large videos.
audio_url	object	Conditions	-	When `type= audio_url`, this refers to 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	-	Content position or purpose, required conditionally: - `first_frame`: First frame image (for image-to-video; when only one image is provided and role is left unfilled, 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 pair with first_frame). - `reference_image`: Reference image (for multimodal reference-based video generation). - `reference_video`: Reference video (for multimodal reference-based video generation). - `reference_audio`: Reference audio (for multimodal reference 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": "Epic space opera theatrical trailer: A female captain stands alone before a massive observation window as the last fleet assembles and warps away; a blinding flash, the bridge shakes, and she is left behind."
    }
  ],
  "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 the H3-Context-IR task

H3-Context-IR deeply understands multimodal contexts such as text, images, audio and videos, analyzes the relationships between creatives as well as between creatives and the target generation output, and conducts complex logical reasoning. The system converts the understanding results into structured expressions, enriching semantic details while preserving the user's original intent as much 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`item (prompt is required); a parameter error will be returned if this is missing. The supported input combinations, mutual exclusion rules and media restrictions are consistent with those specified in "3.1 Create Video Generation Task".
duration	integer	Yes	-	Target video duration (in seconds), required, integer. Available 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 contains only `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`/ `last_frame`images): The aspect ratio is determined by the input image;`ratio`is always `adaptive`. Passing other valid values will not trigger an error, but they will be ignored and processed as `adaptive`. Multimodal reference generation video (r2va, content includes `reference_image`/ `reference_video`/ `reference_audio`): `ratio`is optional, defaulting to `adaptive`; any of the specific ratios mentioned above can also be explicitly specified.
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. 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 query 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": "A boy playing basketball by the sea"
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}'

Response Example

{
  "task_id": "426586401755526"
}

Create a video regeneration task

Convert the source video that meets the MiniMax-H3 768P output specifications into a 2K video. Two input modes are supported, and either source_task_idor content (including base_video) must be provided exclusively (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. No need to pass contentanymore.
Regeneration based on source video (base_video): Provide exactly one source video entry with contentwhere 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 will return task_idafter successful creation; you can query the task to polling the task status;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 their outputs. 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). This parameter and `content` are mutually exclusive and exactly one must be provided.
content	array	conditions	-	Array of input content for video regeneration (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 as-is. 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 entry, `type= video_url`and `role= base_video`; there must be exactly one such entry. `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: Total request body size ≤ 64 MB. For large files, please use a public URL instead of Base64.Refer to the restrictions on the format, single file size, etc. of images/videos/audio, which are the same as those in "3.1 Create Video Generation Task". Either `source_task_id` must be provided, and only one of them can 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`for creating a video generation task.
aigc_watermark	boolean	No	-	Whether to add an AIGC watermark to the generated video, optional, defaults to `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 Frame Count	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 a maximum of 7000 characters.
image_url	object	conditions	-	The image object when `type= image_url` (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 refers to the video object (reference video, only for multimodal reference scenarios; refer to the content description above for format, size and 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);`data: video/mp4;base64,<Base64>`data URI. Note that the total size of the request body must be ≤ 64 MB; Base64 encoding increases the size by approximately 33%, so use a public URL or mm_file:// for large videos.
audio_url	object	conditions	-	When `type= audio_url`, this refers to 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; when only one image is provided and no role is filled, it is processed as first_frame by default). - `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": "Epic space opera theatrical trailer: A female captain stands alone before a massive observation window as the last fleet assembles and warps away; a blinding flash, the bridge shakes, and she is left behind."
    },
    {
      "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 the status and results of a single video generation, H3-Context-IR, or video regeneration task within the last 7 days by task_id. 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 in 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 message.
task.created_at	integer	The Unix timestamp (in seconds) indicating the time when the task was created.
task.updated_at	integer	Unix timestamp (in seconds) indicating the time when the task status was 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-query to obtain it after expiration.
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 billing usage for this request. The video task returns a field measured in seconds; the H3-Context-IR task returns a token usage field.
task.usage.total_seconds	integer	Total billable seconds for this session = Input seconds + Output seconds.
task.usage.input_seconds	integer	Enter the billing seconds of the reference video (including the time count of 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.input_audio_seconds	integer	Enter the number of seconds of the reference audio (sum each segment and round to the nearest integer); no value will be returned if there is no reference audio.
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 output; may return an empty string when it is not applicable to the current task type.
task.task_type	string	Task types: - `generation`: Video generation - `h3_context_ir`: H3-Context-IR (`/v2/h3_context_ir`) - `regeneration`: Video regeneration (`/v2/video_regeneration`)
task.modality	string	Output modality. 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 fee will be deducted
`succeeded` (succeeded)	`deleted`	Delete task records
`failed` (failed)	`deleted`	Delete task records
`running` (in operation)	—	Not actionable, an error will be returned (cancellation is not allowed during processing)
`cancelled` (cancelled)	—	Not operable, 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` (only for tasks in queued status) or `deleted` (to delete task records regardless of success or failure status).
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"
}