# MiniMax-H3-Max multimodal video generation

> Video Generation

Submits an asynchronous video generation task. `input.content` must contain exactly one non-empty text item. The model selects the generation mode from the other media items and their `role` values.

Supported input combinations:
- Text-to-video: one `text` item only.
- Image-to-video: `text` plus one first-frame or last-frame image, or one first-frame and one last-frame image.

The total request body must not exceed 64 MB. All media must be supplied as publicly accessible HTTP/HTTPS URLs; Base64 is not supported.

## Endpoint

`POST https://api.modelverse.cn/v1/tasks/submit`

## Request Body

## Responses

- **200** — Task submitted successfully.
- **400** — Invalid request parameters or input combination.
- **default** — Error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "MiniMax-H3-Max Multimodal Video Generation API",
    "version": "1.0.0",
    "description": "This document describes the ModelVerse API for `MiniMax-H3-Max`, including text-to-video, image-to-video (first frame, last frame, or first and last frames), task status queries, and video results. Intermediate frames and multimodal references (reference images / reference videos / reference audio) are not supported. The endpoints are `POST /v1/tasks/submit` and `GET /v1/tasks/status`.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint used by this model document."
    }
  ],
  "tags": [
    {
      "name": "MiniMax-H3-Max",
      "description": "Asynchronous multimodal video generation with MiniMax-H3-Max."
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "MiniMax-H3-Max"
        ],
        "operationId": "submitMiniMaxH3MaxTask",
        "summary": "MiniMax-H3-Max multimodal video generation",
        "description": "Submits an asynchronous video generation task. `input.content` must contain exactly one non-empty text item. The model selects the generation mode from the other media items and their `role` values.\n\nSupported input combinations:\n- Text-to-video: one `text` item only.\n- Image-to-video: `text` plus one first-frame or last-frame image, or one first-frame and one last-frame image.\n\nThe total request body must not exceed 64 MB. All media must be supplied as publicly accessible HTTP/HTTPS URLs; Base64 is not supported.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MiniMaxH3MaxSubmitRequest"
              },
              "examples": {
                "textToVideo": {
                  "summary": "Text-to-video",
                  "value": {
                    "model": "MiniMax-H3-Max",
                    "input": {
                      "content": [
                        {
                          "type": "text",
                          "text": "An epic space-opera theatrical trailer. A female captain stands alone before a vast observation window as the last fleet assembles and jumps away. A blinding flash rocks the bridge, leaving her behind."
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "768P",
                      "duration": 5,
                      "ratio": "16:9",
                      "aigc_watermark": false
                    }
                  }
                },
                "firstFrame": {
                  "summary": "First-frame image-to-video",
                  "value": {
                    "model": "MiniMax-H3-Max",
                    "input": {
                      "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"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "768P",
                      "duration": 7,
                      "ratio": "adaptive",
                      "aigc_watermark": false
                    }
                  }
                },
                "firstAndLastFrame": {
                  "summary": "First-and-last-frame image-to-video",
                  "value": {
                    "model": "MiniMax-H3-Max",
                    "input": {
                      "content": [
                        {
                          "type": "text",
                          "text": "Create a smooth transition between these two ink-wash paintings."
                        },
                        {
                          "type": "image_url",
                          "image_url": {
                            "url": "https://jiangtest.cn-bj.ufileos.com/c97801b16e654a31b73c6abc4de292a0.png"
                          },
                          "role": "first_frame"
                        },
                        {
                          "type": "image_url",
                          "image_url": {
                            "url": "https://jiangtest.cn-bj.ufileos.com/dd6986fe7d31443aa43551e8b222c94b.png"
                          },
                          "role": "last_frame"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "768P",
                      "duration": 10,
                      "ratio": "adaptive",
                      "aigc_watermark": false
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3MaxSubmitResponse"
                },
                "examples": {
                  "submitted": {
                    "summary": "Submitted task",
                    "value": {
                      "output": {
                        "task_id": "h3-424010985738629"
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters or input combination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3MaxErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/MiniMaxH3MaxParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3MaxErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/MiniMaxH3MaxParamError"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "MiniMax-H3-Max"
        ],
        "operationId": "getMiniMaxH3MaxTaskStatus",
        "summary": "MiniMax-H3-Max video task status",
        "description": "Returns the asynchronous task status. On success, `output.urls` contains the generated video URL and `usage` contains duration, input-media, and aspect-ratio usage data.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "Asynchronous task identifier returned by `/v1/tasks/submit`, including the `h3-` prefix.",
            "schema": {
              "type": "string"
            },
            "example": "h3-424010985738629"
          }
        ],
        "responses": {
          "200": {
            "description": "Task status response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3MaxStatusResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful task",
                    "value": {
                      "output": {
                        "task_id": "h3-424010985738629",
                        "task_status": "Success",
                        "urls": [
                          "https://your-cdn.example.com/h3-generated-2k-output.mp4"
                        ],
                        "submit_time": 1785125529,
                        "finish_time": 1785125946
                      },
                      "usage": {
                        "prompt_tokens": 0,
                        "completion_tokens": 0,
                        "total_tokens": 0,
                        "duration": 5,
                        "output_video_duration": 5,
                        "video_count": 1,
                        "ratio": "16:9"
                      },
                      "request_id": ""
                    }
                  },
                  "failure": {
                    "summary": "Failed task",
                    "value": {
                      "output": {
                        "task_id": "h3-424010985738629",
                        "task_status": "Failure",
                        "submit_time": 1785125529,
                        "finish_time": 1785125540,
                        "error_message": "task failed"
                      },
                      "usage": {
                        "prompt_tokens": 0,
                        "completion_tokens": 0,
                        "total_tokens": 0,
                        "duration": 5
                      },
                      "request_id": ""
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid task identifier or request parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3MaxErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/MiniMaxH3MaxParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3MaxErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Send `Authorization: Bearer {your_api_key}` in the request headers."
      }
    },
    "schemas": {
      "MiniMaxH3MaxSubmitRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input",
          "parameters"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "MiniMax-H3-Max",
            "description": "Model name. This schema is pinned to `MiniMax-H3-Max`."
          },
          "input": {
            "$ref": "#/components/schemas/MiniMaxH3MaxInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/MiniMaxH3MaxParameters"
          }
        }
      },
      "MiniMaxH3MaxInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "content"
        ],
        "properties": {
          "content": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "description": "Multimodal input array. It must contain exactly one non-empty `text` item.\n\nImage roles are `first_frame`, `last_frame`. A single image without a role is treated as the first frame. At most one first frame and one last frame are accepted, and up to nine reference images are accepted.\n",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/MiniMaxH3MaxTextContent"
                },
                {
                  "$ref": "#/components/schemas/MiniMaxH3MaxImageContent"
                }
              ]
            }
          }
        }
      },
      "MiniMaxH3MaxTextContent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "text"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "text"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "description": "Non-empty text prompt that directs video generation."
          }
        }
      },
      "MiniMaxH3MaxImageContent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "image_url"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "image_url"
          },
          "image_url": {
            "$ref": "#/components/schemas/MiniMaxH3MaxURLObject"
          },
          "role": {
            "type": "string",
            "description": "An omitted role is treated as `first_frame`.",
            "enum": [
              "first_frame",
              "last_frame",
              "reference_image"
            ]
          }
        },
        "description": "Images must use public HTTP/HTTPS URLs; Base64 is not supported. Supported formats are JPG, JPEG, PNG, WEBP, HEIC, and HEIF. Each file must be at most 30 MB, both dimensions must be 256–5760 px, and the width-to-height ratio must be 0.4–2.5.\n"
      },
      "MiniMaxH3MaxURLObject": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://",
            "description": "Public HTTP/HTTPS URL accessible to MiniMax. Base64 and data URLs are not supported."
          }
        }
      },
      "MiniMaxH3MaxParameters": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resolution",
          "duration"
        ],
        "properties": {
          "resolution": {
            "type": "string",
            "description": "Output video resolution.",
            "enum": [
              "768P",
              "480P"
            ]
          },
          "duration": {
            "type": "integer",
            "minimum": 4,
            "maximum": 15,
            "description": "Output video duration in seconds. Must be an integer from 4 through 15."
          },
          "ratio": {
            "type": "string",
            "default": "adaptive",
            "enum": [
              "adaptive",
              "21:9",
              "16:9",
              "4:3",
              "1:1",
              "3:4",
              "9:16"
            ],
            "description": "Output aspect ratio.\n- Text-to-video: required and cannot be `adaptive`.\n- Image-to-video: determined by the input image and processed as `adaptive`; pass `adaptive` for clarity.\n",
            "aigc_watermark": {
              "type": "boolean",
              "default": false,
              "description": "Whether to add an AIGC identification watermark to the generated video. Disabled by default."
            }
          }
        }
      },
      "MiniMaxH3MaxSubmitResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "task_id"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "Unique asynchronous task identifier. ModelVerse prefixes MiniMax-H3-Max task IDs with `h3-`."
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "MiniMaxH3MaxStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "$ref": "#/components/schemas/MiniMaxH3MaxStatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/MiniMaxH3MaxUsage"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "MiniMaxH3MaxStatusOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Unique asynchronous task identifier."
          },
          "task_status": {
            "$ref": "#/components/schemas/MiniMaxH3MaxTaskStatus"
          },
          "urls": {
            "type": "array",
            "description": "Generated video URLs returned when the task succeeds.",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "submit_time": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in seconds when the task was submitted."
          },
          "finish_time": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in seconds when the task completed."
          },
          "error_message": {
            "type": "string",
            "description": "Error message returned when the task fails."
          }
        }
      },
      "MiniMaxH3MaxTaskStatus": {
        "type": "string",
        "description": "Asynchronous task status.",
        "enum": [
          "Pending",
          "Running",
          "Success",
          "Failure"
        ]
      },
      "MiniMaxH3MaxUsage": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "total_tokens": {
            "type": "integer"
          },
          "duration": {
            "type": "integer",
            "description": "Requested output video duration in seconds."
          },
          "input_video_duration": {
            "type": "number",
            "description": "Reference video input duration in seconds."
          },
          "output_video_duration": {
            "type": "number",
            "description": "Output video duration in seconds."
          },
          "video_count": {
            "type": "integer",
            "description": "Number of output videos."
          },
          "ratio": {
            "type": "string",
            "description": "Actual output video aspect ratio."
          }
        }
      },
      "MiniMaxH3MaxErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/MiniMaxH3MaxErrorObject"
          }
        }
      },
      "MiniMaxH3MaxErrorObject": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "message",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message."
          },
          "type": {
            "type": "string",
            "description": "Error type."
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Error code."
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "Related request parameter, if any."
          }
        }
      }
    },
    "examples": {
      "MiniMaxH3MaxParamError": {
        "summary": "Parameter error",
        "value": {
          "error": {
            "message": "input.content must contain exactly one non-empty text item",
            "type": "invalid_request_error",
            "code": "param_error",
            "param": "input.content"
          }
        }
      }
    }
  }
}
```