# MiniMax-H3 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.
- Multimodal reference-to-video: `text` plus a combination of reference images, reference videos, and reference audio. Reference audio cannot be used alone; at least one reference image or reference video is required.

Image-to-video and multimodal reference-to-video inputs are mutually exclusive. 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 Multimodal Video Generation API",
    "version": "1.0.0",
    "description": "This document describes the ModelVerse API for `MiniMax-H3`, including text-to-video, image-to-video (first frame, last frame, or first and last frames), multimodal reference-to-video, task status queries, and video results.\nThe 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",
      "description": "Asynchronous multimodal video generation with MiniMax-H3."
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "MiniMax-H3"
        ],
        "operationId": "submitMiniMaxH3Task",
        "summary": "MiniMax-H3 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- Multimodal reference-to-video: `text` plus a combination of reference images, reference videos, and reference audio. Reference audio cannot be used alone; at least one reference image or reference video is required.\n\nImage-to-video and multimodal reference-to-video inputs are mutually exclusive. The 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/MiniMaxH3SubmitRequest"
              },
              "examples": {
                "textToVideo": {
                  "summary": "Text-to-video",
                  "value": {
                    "model": "MiniMax-H3",
                    "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": "2K",
                      "duration": 5,
                      "ratio": "16:9",
                      "aigc_watermark": false
                    }
                  }
                },
                "firstFrame": {
                  "summary": "First-frame image-to-video",
                  "value": {
                    "model": "MiniMax-H3",
                    "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",
                    "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": "2K",
                      "duration": 10,
                      "ratio": "adaptive",
                      "aigc_watermark": false
                    }
                  }
                },
                "referenceVideoAndAudio": {
                  "summary": "Reference video and audio",
                  "value": {
                    "model": "MiniMax-H3",
                    "input": {
                      "content": [
                        {
                          "type": "text",
                          "text": "The character says: Follow the wind, live free. Leave worries behind, enjoy the moment. Use the timbre of reference audio 1."
                        },
                        {
                          "type": "video_url",
                          "video_url": {
                            "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/297573323635_00_%E8%A7%86%E9%A2%911_YnyRbxEwio_video_20260525_163755_1927e9d3.mp4"
                          },
                          "role": "reference_video"
                        },
                        {
                          "type": "audio_url",
                          "audio_url": {
                            "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/f463d523c5ce_01_%E9%9F%B3%E9%A2%911_RSLcbpzJPo_6%E6%9C%885%E6%97%A5(1).mp3"
                          },
                          "role": "reference_audio"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "2K",
                      "duration": 10,
                      "ratio": "16:9",
                      "aigc_watermark": false
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3SubmitResponse"
                },
                "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/MiniMaxH3ErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/MiniMaxH3ParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/MiniMaxH3ParamError"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "MiniMax-H3"
        ],
        "operationId": "getMiniMaxH3TaskStatus",
        "summary": "MiniMax-H3 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/MiniMaxH3StatusResponse"
                },
                "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/MiniMaxH3ErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/MiniMaxH3ParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Send `Authorization: Bearer {your_api_key}` in the request headers."
      }
    },
    "schemas": {
      "MiniMaxH3SubmitRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input",
          "parameters"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "MiniMax-H3",
            "description": "Model name. This schema is pinned to `MiniMax-H3`."
          },
          "input": {
            "$ref": "#/components/schemas/MiniMaxH3Input"
          },
          "parameters": {
            "$ref": "#/components/schemas/MiniMaxH3Parameters"
          }
        }
      },
      "MiniMaxH3Input": {
        "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`, and `reference_image`. 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.\nVideos must use `reference_video` and are limited to three. Audio items must use `reference_audio` and are limited to three. Reference audio cannot be used alone; at least one reference image or reference video is also required.\n",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/MiniMaxH3TextContent"
                },
                {
                  "$ref": "#/components/schemas/MiniMaxH3ImageContent"
                },
                {
                  "$ref": "#/components/schemas/MiniMaxH3VideoContent"
                },
                {
                  "$ref": "#/components/schemas/MiniMaxH3AudioContent"
                }
              ]
            }
          }
        }
      },
      "MiniMaxH3TextContent": {
        "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."
          }
        }
      },
      "MiniMaxH3ImageContent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "image_url"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "image_url"
          },
          "image_url": {
            "$ref": "#/components/schemas/MiniMaxH3URLObject"
          },
          "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"
      },
      "MiniMaxH3VideoContent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "video_url",
          "role"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "video_url"
          },
          "video_url": {
            "$ref": "#/components/schemas/MiniMaxH3URLObject"
          },
          "role": {
            "type": "string",
            "const": "reference_video"
          }
        },
        "description": "Used only for multimodal reference-to-video. The public URL must point to MP4 or MOV. Supported video codecs are H.264/AVC and H.265/HEVC; supported audio codecs are AAC and MP3. Each file must be at most 50 MB and 2–15 seconds long, with no more than 15 seconds total. Both dimensions must be 256–5760 px, the aspect ratio must be 0.4–2.5, and the frame rate must be 23.976–60 fps.\n"
      },
      "MiniMaxH3AudioContent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "audio_url",
          "role"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "audio_url"
          },
          "audio_url": {
            "$ref": "#/components/schemas/MiniMaxH3URLObject"
          },
          "role": {
            "type": "string",
            "const": "reference_audio"
          }
        },
        "description": "Used only for multimodal reference-to-video. The public URL must point to WAV or MP3. Each file must be at most 15 MB and 2–15 seconds long, with no more than 15 seconds total. Reference audio cannot be used alone.\n"
      },
      "MiniMaxH3URLObject": {
        "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."
          }
        }
      },
      "MiniMaxH3Parameters": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resolution",
          "duration"
        ],
        "properties": {
          "resolution": {
            "type": "string",
            "description": "Output video resolution.",
            "enum": [
              "768P",
              "2K"
            ]
          },
          "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- Multimodal reference-to-video: optional, defaults to `adaptive`, and may also use a specific ratio.\n"
          },
          "aigc_watermark": {
            "type": "boolean",
            "default": false,
            "description": "Whether to add an AIGC identification watermark to the generated video. Disabled by default."
          }
        }
      },
      "MiniMaxH3SubmitResponse": {
        "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 task IDs with `h3-`."
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "MiniMaxH3StatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "$ref": "#/components/schemas/MiniMaxH3StatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/MiniMaxH3Usage"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "MiniMaxH3StatusOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Unique asynchronous task identifier."
          },
          "task_status": {
            "$ref": "#/components/schemas/MiniMaxH3TaskStatus"
          },
          "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."
          }
        }
      },
      "MiniMaxH3TaskStatus": {
        "type": "string",
        "description": "Asynchronous task status.",
        "enum": [
          "Pending",
          "Running",
          "Success",
          "Failure"
        ]
      },
      "MiniMaxH3Usage": {
        "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."
          }
        }
      },
      "MiniMaxH3ErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/MiniMaxH3ErrorObject"
          }
        }
      },
      "MiniMaxH3ErrorObject": {
        "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": {
      "MiniMaxH3ParamError": {
        "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"
          }
        }
      }
    }
  }
}
```