--- title: "Create video generation task" method: POST path: "/v2/video_generation" tags: ["Video V2"] --- # Create video generation task `POST /v2/video_generation` ## Request - Base URL: `https://api.minimax.io` - URL: `https://api.minimax.io/v2/video_generation` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a video generation task. The model generates a video from the multimodal input you provide (text / image / video / audio). This is an asynchronous endpoint: on success it returns a `task_id`, and you should poll the [Query Task](/api-reference/video-generation-v2-query) endpoint for the task status and retrieve the generated video once it succeeds. Currently supported models: `MiniMax-H3`, `MiniMax-H3-Highspeed`, `MiniMax-H3-Lite`, `MiniMax-H3-Max`. ## Headers - `Content-Type` 'application/json', required ## Request body - VideoGenerationV2Req - `model` 'MiniMax-H3' | 'MiniMax-H3-Highspeed' | 'MiniMax-H3-Lite' | 'MiniMax-H3-Max', required: Model name. Currently available: `MiniMax-H3`, `MiniMax-H3-Highspeed`, `MiniMax-H3-Lite`, `MiniMax-H3-Max`. - **`MiniMax-H3`**: **the variant for high-quality video creation.** Supports text-to-video, image-to-video (first / last frame), and reference-to-video; `768P` / `2K` resolution, 4–15s duration. - **`MiniMax-H3-Highspeed`**: **balances generation quality and speed.** Supports text-to-video, image-to-video (first / last frame), and reference-to-video (reference image / video / audio); `480P` / `768P` resolution, **`2K` is not supported**; 4–15s duration. - **`MiniMax-H3-Lite`**: **the lightweight variant.** Supports text-to-video, image-to-video (first / last frame), and reference-to-video (reference image / video / audio); `480P` / `768P` resolution, **`2K` is not supported**; 4–15s duration. - **`MiniMax-H3-Max`**: **the fast generation variant.** Supports text-to-video, image-to-video (first / last frame), and reference-to-video (reference image / video / audio); `480P` / `768P` resolution, **`2K` is not supported**; 5–15s duration. - `content` ContentItem[], required: Array of multimodal input describing the information used to generate the video. Each element is distinguished by `type` (`text` / `image_url` / `video_url` / `audio_url`) and can be labeled with a `role`. **Every request must include one non-empty `text` item (the prompt is required)**; otherwise a parameter error is returned. 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 omitted). - **Image-to-video, last frame**: `text` + 1 `image_url` (`role=last_frame`). - **Image-to-video, first & last frame**: `text` + 2 `image_url` items with `role` set to `first_frame` and `last_frame` respectively. - **Reference-to-video**: `text` + any combination of reference images (`role=reference_image`), reference videos (`role=reference_video`), and reference audio (`role=reference_audio`). > **Image-to-video and reference-to-video are mutually exclusive**: if any `reference_image` / `reference_video` / `reference_audio` role appears in content, then `first_frame` / `last_frame` must not appear (and vice versa); the two cannot be mixed. --- **Input media limits** (total request body ≤ 64 MB; use public URLs for large files, avoid Base64) Image `image_url`: | Item | Limit | | :--- | :--- | | Format | JPG, JPEG, PNG, WEBP, HEIC, HEIF | | Single file size | ≤ 30 MB | | Width/height range | [256, 5760] px | | Aspect ratio (w/h) | [0.4, 2.5] | | Count | first frame ≤ 1, last frame ≤ 1, reference images ≤ 9 | Video `video_url` (reference scenario only): | Item | Limit | | :--- | :--- | | Container / format | MP4 (`.mp4`), MOV (`.mov`) | | Codec | Video H.264/AVC, H.265/HEVC; audio AAC, MP3 | | Single file size | ≤ 50 MB | | Count | ≤ 3 | | Per-clip duration | [2, 15] s; total ≤ 15 s | | Width/height range | [256, 5760] px | | Aspect ratio (w/h) | [0.4, 2.5] | | Frame rate | [23.976, 60] | Audio `audio_url` (reference scenario only): | Item | Limit | | :--- | :--- | | Format | WAV, MP3 | | Single file size | ≤ 15 MB | | Count | ≤ 3 | | Per-clip duration | [2, 15] s; total ≤ 15 s | - `type` 'text' | 'image_url' | 'video_url' | 'audio_url', required: Type of the input content. - `text` string: Text prompt, **required**: every scenario must include one non-empty `text` describing the desired video. Length is counted by characters, with a maximum of 7000 characters per `text`. - `image_url` object: Image object when `type=image_url` (see the content description above for format / size / dimension / count limits). - `url` string, required: Image location. Supported: a public URL; `mm_file://{file_id}` (reference an existing platform file, e.g. an uploaded file or a previous output's file_id); a `data:image/;base64,` data URI (`` lowercase). - `video_url` object: Video object when `type=video_url` (reference video, reference scenario only; see the content description above for format / size / duration limits). - `url` string, required: Video location. Supported: a public URL; `mm_file://{file_id}` (reference an existing platform file's file_id); a `data:video/mp4;base64,` data URI. Note the total request body must be ≤ 64 MB and Base64 inflates size by about 33%, so use a public URL or mm_file:// for large videos. - `audio_url` object: Audio object when `type=audio_url` (reference audio, reference scenario only; see the content description above for format / size / duration limits). - `url` string, required: Audio location. Supported: a public URL; `mm_file://{file_id}` (reference an existing platform file's file_id); a `data:audio/;base64,` data URI (`` lowercase). - `role` 'first_frame' | 'last_frame' | 'reference_image' | 'reference_video' | 'reference_audio': Position or purpose of the content, conditionally required: - `first_frame`: first-frame image (image-to-video; when there is a single image and no role is set, it defaults to first_frame). - `last_frame`: last-frame image (image-to-video first & last frame, must be paired with first_frame). - `reference_image`: reference image (reference-to-video). - `reference_video`: reference video (reference-to-video). - `reference_audio`: reference audio (reference-to-video). - `resolution` '480P' | '768P' | '2K', required: Video resolution. Availability differs by model: - **`MiniMax-H3`**: `768P`, `2K` - **`MiniMax-H3-Highspeed`**: `480P`, `768P` (`2K` is not supported) - **`MiniMax-H3-Lite`**: `480P`, `768P` (`2K` is not supported) - **`MiniMax-H3-Max`**: `480P`, `768P` (`2K` is not supported) - `duration` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15, required: Duration of the generated video in seconds. Required, integer. Available values differ by model: - **`MiniMax-H3`**: `4`–`15` - **`MiniMax-H3-Highspeed`**: `4`–`15` - **`MiniMax-H3-Lite`**: `4`–`15` - **`MiniMax-H3-Max`**: `5`–`15` (4 seconds is not supported) - `ratio` 'adaptive' | '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16': Aspect ratio of the generated video. Defaults to `adaptive` (the most suitable ratio is chosen automatically based on the input; the actual ratio can be read from the `ratio` field of the query endpoint). Available values: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. **Text-to-video (t2va, content contains only `text`)**: `ratio` is required and cannot be `adaptive`; available values `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. **Image-to-video (i2va, content contains a `first_frame` / `last_frame` image)**: the aspect ratio is determined by the input image and `ratio` is always `adaptive`; passing another valid value does not error but is ignored and treated as `adaptive`. **Reference-to-video (r2va, content contains `reference_image` / `reference_video` / `reference_audio`)**: `ratio` is optional and defaults to `adaptive`; you may also explicitly specify any of the concrete ratios above. `MiniMax-H3-Lite` does not support `adaptive` yet; specify a concrete ratio. - `extra` object: Additional generation options for `MiniMax-H3-Max`. Currently only `prompt_expansion_mode` is supported. If `extra` or this property is omitted, `balanced` is used. Do not pass `balance`, an empty string, a Boolean value, or other undeclared fields. - `prompt_expansion_mode` 'disabled' | 'balanced' | 'quality': Prompt expansion mode. `disabled` disables prompt expansion; `balanced` uses balanced expansion and is the default; `quality` prioritizes expansion quality. - `callback_url` string: Callback URL for task status changes. Once configured, the MiniMax server first sends a verification request containing a `challenge` field (you must return the `challenge` unchanged within 3 seconds to complete verification); after verification succeeds, it POSTs an update to this URL whenever the task status changes. The push body has the same structure as the response of the [Query Task](/api-reference/video-generation-v2-query) endpoint. Callback `status` values: `queued`, `running`, `succeeded`, `failed`, `cancelled`. ## Response `200` The create endpoint returns a `task_id`. Use this `task_id` with the [Query Task](/api-reference/video-generation-v2-query) endpoint to retrieve the task status and result. **Successful Query Task response example** ```json { "task": { "id": "424010985738629", "model": "MiniMax-H3", "status": "succeeded", "created_at": 1785125529, "updated_at": 1785125946, "content": { "url": "https://your-cdn.example.com/h3-generated-2k-output.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" } } ``` - VideoGenerationV2Resp - `task_id` string: ID of the task, used to query the task status and result later. ## Other responses - `400`: Invalid parameters - `401`: Authentication failed - `402`: Insufficient balance/quota - `422`: Input contains sensitive content - `429`: Rate limit triggered - `500`: Server error --- [API](https://skmtc.dev/minimax/apis/minimax-api.md) - [All operations](https://skmtc.dev/minimax/apis/minimax-api/llms.txt) - [OpenAPI document](https://skmtc.dev/minimax/apis/minimax-api/revisions/81353c47e0e6?raw)