MiniMax H3 Video Generation, Regeneration and H3-Context-IR API

MiniMax H3

curl --request POST \
  --url https://api.novita.ai/v3/minimax-en/v2/video_generation

const options = {method: 'POST'};

fetch('https://api.novita.ai/v3/minimax-en/v2/video_generation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novita.ai/v3/minimax-en/v2/video_generation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.novita.ai/v3/minimax-en/v2/video_generation"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.novita.ai/v3/minimax-en/v2/video_generation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

minimax-en

video_generation

MiniMax H3

curl --request POST \
  --url https://api.novita.ai/v3/minimax-en/v2/video_generation

const options = {method: 'POST'};

fetch('https://api.novita.ai/v3/minimax-en/v2/video_generation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novita.ai/v3/minimax-en/v2/video_generation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.novita.ai/v3/minimax-en/v2/video_generation"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.novita.ai/v3/minimax-en/v2/video_generation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

The parameters and usage align with the official documentation. For detailed parameters, refer directly to the official documentation.

1. Overview

This document describes how to call the MiniMax H3 (overseas edition) native video generation protocol, including request parameters, task queries, and billing rules. MiniMax H3 is an asynchronous video generation endpoint: after a task is submitted, a task ID is returned, and the client obtains the task status through the query endpoint. Once the task succeeds, content.url in the response is the address of the generated result. The parameters and usage align with the official documentation. For detailed parameters, refer directly to the official documentation.

1.1 Endpoints

The overseas edition of MiniMax H3 includes three capabilities. Each has its own creation endpoint, and they share a single query endpoint:

Capability	Create task
Video generation	`POST /v3/minimax-en/v2/video_generation`
Video regeneration	`POST /v3/minimax-en/v2/video_regeneration`
H3-Context-IR	`POST /v3/minimax-en/v2/h3_context_ir`

All three capabilities share the same query endpoint:

GET https://{api_domain}/v3/minimax-en/v2/query/video_generation/{task_id}

Here {api_domain} is the API domain provided to you by the platform, and {task_id} is the task ID returned by the creation endpoint. task.task_type in the query response distinguishes the capability (generation, regeneration, or h3_context_ir).

1.2 Authentication

All requests must carry the platform API Key; POST requests that create tasks must also specify the JSON content type:

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

1.3 Supported models

The model in the request body determines which model is used. Available values are as follows:

Model	Supported resolutions	Input billing
MiniMax-H3	768P, 2K	The first 5 input images are free, and any excess is billed per image; reference video input is billed per second
MiniMax-H3-Max	480P, 768P	The first 2 input images are free, and any excess is billed per image; reference video input is billed per second

The two models share the same endpoint addresses, authentication method, request structure, and query structure. They differ only in the model value, the supported resolutions, and the number of free input images.

1.4 Billing

MiniMax H3 is billed by actual generation usage, and no fee is deducted in advance when a task is submitted:

Usage	Billing unit
Input images	The first 5 images of MiniMax-H3 and the first 2 images of MiniMax-H3-Max are free; the excess is billed per image
Reference video input	Seconds, tiered by output resolution
Generated video output	Seconds, tiered by output resolution

MiniMax-H3 uses different price tiers for 768P / 2K, and MiniMax-H3-Max uses different price tiers for 480P / 768P. The exact unit price depends on the overseas-edition entry on the pricing page of your platform. Failed or cancelled tasks do not incur a successful-generation fee.

1.5 Billing and usage field mapping

After each successful generation, the response’s usage returns the usage of this request. The fee depends only on the seconds / image count in it, priced in tiers by video resolution (768P / 2K for H3, 480P / 768P for H3-Max); token-related fields do not participate in billing. The table below uses MiniMax-H3 as an example and explains each field; the rules for MiniMax-H3-Max are the same, except that the number of free input images is 2. The fields are explained as follows:

`usage` field	Meaning	Billed	Billing rule
`output_seconds`	Output duration of the generated video (seconds)	✅ Billed	Resolution unit price × `output_seconds`
`input_seconds`	Input video duration (seconds)	✅ Billed (not charged when 0)	Resolution unit price × `input_seconds`
`input_image_count`	Number of input images	✅ Excess billed	First 5 free for H3: (`input_image_count` − 5) × image unit price; first 2 free for H3-Max: (`input_image_count` − 2) × image unit price
`total_seconds`	= `input_seconds` + `output_seconds`	❌ Not billed	For aggregate verification only
`total_tokens`	Token statistics returned by the upstream	❌ Not billed	For reference only; not used for billing
`prompt_tokens`	Same as above	❌ Not billed	For reference only
`completion_tokens`	Same as above	❌ Not billed	For reference only

Billing formula: fee per item = resolution unit price × usage; fee for this request = sum of all billed items. The video resolution can be viewed in the task.resolution field of the query response. Settlement is done once after the task succeeds; failed or cancelled tasks are not billed.

2. Create a video generation task

2.1 Request example: text-to-video

Text-to-video requires a text prompt and a non-adaptive aspect ratio:

curl -X POST 'https://{api_domain}/v3/minimax-en/v2/video_generation' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A cinematic product video in a clean studio"
      }
    ],
    "resolution": "768P",
    "duration": 4,
    "ratio": "16:9"
  }'

2.2 Request example: first-frame-to-video

curl -X POST 'https://{api_domain}/v3/minimax-en/v2/video_generation' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "Animate the subject naturally and keep the composition stable"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://your-cdn.example.com/first-frame.png"
        },
        "role": "first_frame"
      }
    ],
    "resolution": "768P",
    "duration": 4,
    "ratio": "adaptive"
  }'

You can also pass a single image without a role, in which case it is treated as the first frame.

2.3 Request example: reference-material-to-video

Reference images, videos, and audio use their corresponding roles:

curl -X POST 'https://{api_domain}/v3/minimax-en/v2/video_generation' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "Create a product demonstration while preserving the reference style"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://your-cdn.example.com/product.png"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://your-cdn.example.com/reference.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "https://your-cdn.example.com/reference.mp3"
        },
        "role": "reference_audio"
      }
    ],
    "resolution": "2K",
    "duration": 6,
    "ratio": "16:9"
  }'

2.4 Request fields

Field	Type	Required	Description
`model`	string	Yes	`MiniMax-H3` or `MiniMax-H3-Max`
`content`	array	Yes	Multimodal input list; every request must contain one non-empty `text` item
`content[].type`	string	Yes	`text`, `image_url`, `video_url`, or `audio_url`
`content[].text`	string	Required for text items	Non-empty prompt; each text item supports up to 7000 characters
`content[].image_url.url`	string	Required for image items	Public URL, `mm_file://{file_id}`, or an image Base64 data URI
`content[].video_url.url`	string	Required for video items	Public URL, `mm_file://{file_id}`, or an MP4 Base64 data URI
`content[].audio_url.url`	string	Required for audio items	Public URL, `mm_file://{file_id}`, or an audio Base64 data URI
`content[].role`	string	Required by scenario	`first_frame`, `last_frame`, `reference_image`, `reference_video`, or `reference_audio`; a single image without a `role` is treated as the first frame
`resolution`	string	Yes	Minimax-H3: `768P` or `2K`; Minimax-H3-Max: `480P` or `768P`
`duration`	integer	Yes	Minimax-H3: an integer from 4 to 15 seconds; Minimax-H3-Max: an integer from 5 to 15 seconds
`ratio`	string	Required for text-to-video	`adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, or `9:16`; `adaptive` is not available for text-to-video, and image-to-video is always handled as `adaptive`
`callback_url`	string	No	Task status callback address; on first configuration, the `challenge` in the verification request must be returned unchanged within 3 seconds

2.5 Content combination rules

Rule	Restriction
Text	Every request must contain one non-empty text prompt; each text item supports up to 7000 characters
First frame / last frame	At most 1 first frame and at most 1 last frame; first frame only, last frame only, and first + last frame combinations are supported
Reference images	At most 9, using `role=reference_image`
Reference videos	At most 3, using `role=reference_video`; each segment is 2 to 15 seconds, and the total duration must not exceed 15 seconds
Reference audio	At most 3, using `role=reference_audio`; each segment is 2 to 15 seconds, and the total duration must not exceed 15 seconds; it can be the only type of reference material submitted together with text
Material mode	The first-frame/last-frame mode cannot be mixed with the `reference_image`, `reference_video`, or `reference_audio` modes
Text-to-video aspect ratio	`ratio` must be provided and cannot be `adaptive`
Image-to-video aspect ratio	Determined by the input image and always handled as `adaptive`; other valid values passed in are ignored
Reference-material-to-video aspect ratio	`ratio` may be omitted, defaulting to `adaptive`; a specific aspect ratio may also be specified
Callback	`callback_url` is supported; status values are `queued`, `running`, `succeeded`, `failed`, `cancelled`

2.6 Input material limits

The total size of a single request body must not exceed 64 MB. Base64 increases the data size by about 33%, so larger materials should preferentially use a public URL or mm_file://{file_id}.

Material	Format	Per-file limit	Quantity, duration, and dimension limits
Image	JPG, JPEG, PNG, WEBP, HEIC, HEIF	No more than 30 MB	Width and height both 256 to 5760 px; aspect ratio 0.4 to 2.5; at most 1 first frame, at most 1 last frame, and at most 9 reference images
Reference video	MP4, MOV; video codec H.264/AVC or H.265/HEVC; audio codec AAC or MP3	No more than 50 MB	At most 3; each segment 2 to 15 seconds, total duration no more than 15 seconds; width and height both 256 to 5760 px; aspect ratio 0.4 to 2.5; frame rate 23.976 to 60 fps
Reference audio	WAV, MP3	No more than 15 MB	At most 3; each segment 2 to 15 seconds, total duration no more than 15 seconds

2.7 Create response

A successful creation returns a task ID:

{
  "task_id": "427916141998479"
}

Please save this ID and use it to call the query endpoint. The task ID is the only identifier for subsequently querying the task status and obtaining the result.

3. Query task

3.1 Query example

curl -X GET 'https://{api_domain}/v3/minimax-en/v2/query/video_generation/427916141998479' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

The query endpoint can only query tasks created within the last 7 days (UTC time window [T-7d, T)); a task_id outside this window returns invalid task_id.

3.2 In-progress response

When the task is queued or running, wait and continue querying:

{
  "task": {
    "id": "427916141998479",
    "status": "running",
    "task_type": "generation",
    "model": "MiniMax-H3",
    "resolution": "768P"
  }
}

A polling interval of 10 to 30 seconds is recommended, and it can be adjusted according to your business scenario. Do not call the query endpoint at a high frequency.

3.3 Success response

{
  "task": {
    "id": "427916141998479",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://your-result-cdn.example.com/video.mp4"
    },
    "resolution": "768P",
    "duration": 4,
    "usage": {
      "total_seconds": 4,
      "input_seconds": 0,
      "output_seconds": 4,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

content.url is the address of the generated result. This download URL has an expiration time, so download it or save it to your own storage promptly; after it expires, query the task again to obtain a new URL.

3.4 Failure and cancellation responses

{
  "task": {
    "id": "427916141998479",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "created_at": 1785125529,
    "updated_at": 1785125700,
    "resolution": "768P",
    "duration": 4,
    "usage": {},
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

status may be:

Status	Description
`queued`	Created, waiting to be processed
`running`	Generating
`succeeded`	Generation succeeded; `content.url` can be read
`failed`	Generation failed; error details are in `error.code` and `error.message`
`cancelled`	The task was cancelled

3.5 Query response fields

The fields of the task object are as follows. Some fields may not be returned depending on the status; the output of a successful task is in content, and the error of a failed task is in error.

Field	Type	Description
`task.id`	string	Task ID
`task.model`	string	Model used by the task, such as `MiniMax-H3`
`task.status`	string	`queued`, `running`, `succeeded`, `failed`, or `cancelled`
`task.error.code`	string	Business error code for an asynchronous task failure; returned only on failure
`task.error.message`	string	Error message for an asynchronous task failure; returned only on failure
`task.created_at`	integer	Task creation time, Unix timestamp in seconds
`task.updated_at`	integer	Last update time of the task status, Unix timestamp in seconds
`task.content.url`	string	Time-limited download URL of the video output; returned after a video task succeeds
`task.content.prompt`	string	Structured enhanced prompt of H3-Context-IR; returned only after the corresponding task succeeds
`task.resolution`	string	Output resolution
`task.duration`	integer	Output duration, in seconds
`task.usage`	object	Usage information; contains metering fields on success, and may be an empty object in a failure response
`task.ratio`	string	Actual output aspect ratio; may be an empty string when not applicable
`task.task_type`	string	`generation`, `h3_context_ir`, or `regeneration`
`task.modality`	string	Output modality: `video` for video tasks, `text` for H3-Context-IR

The usage fields of video tasks are as follows; some fields may not be returned when there is no corresponding input.

Field	Type	Description
`usage.total_seconds`	integer	Total metered seconds, i.e., input seconds plus output seconds
`usage.input_seconds`	integer	Reference video input seconds
`usage.output_seconds`	integer	Output video seconds
`usage.input_image_count`	integer	Total number of input images, including the first frame, last frame, and reference images
`usage.input_audio_seconds`	integer	Reference audio input seconds; not returned when there is no reference audio
`usage.total_tokens`	integer	Total tokens, i.e., `prompt_tokens` + `completion_tokens`
`usage.prompt_tokens`	integer	Input tokens after conversion
`usage.completion_tokens`	integer	Output tokens after conversion

4. Video regeneration

Video regeneration regenerates a source video that already meets the MiniMax-H3 768P specification into 2K. It uses a dedicated creation endpoint, model is still MiniMax-H3, resolution is fixed to 2K, and it shares the query endpoint in section 3; task.task_type is regeneration in the query response.

4.1 Request examples

The two input methods are mutually exclusive: you cannot provide both, and you cannot provide neither:

By source task ID: pass source_task_id, i.e., the ID of a previously successful /v2/video_generation task (it must belong to the same account, have status succeeded, and still be within the 7-day query window).
By source video: pass content, which must contain exactly one source video item with type=video_url and role=base_video, and re-submit the other inputs used to generate that 768P video.

By source task ID:

curl -X POST 'https://{api_domain}/v3/minimax-en/v2/video_regeneration' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "source_task_id": "424010985738629",
    "resolution": "2K"
  }'

By source video:

curl -X POST 'https://{api_domain}/v3/minimax-en/v2/video_regeneration' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "video_url",
        "video_url": { "url": "https://your-cdn.example.com/source-768p.mp4" },
        "role": "base_video"
      },
      {
        "type": "text",
        "text": "The final prompt actually sent to the model"
      }
    ],
    "resolution": "2K"
  }'

The text in content must be the prompt that was actually ultimately sent to the model, and must not be the original prompt before H3-Context-IR processing.

4.2 Request fields

Field	Type	Required	Description
`model`	string	Yes	Fixed to `MiniMax-H3`
`resolution`	string	Yes	Fixed to `2K`
`source_task_id`	string	One of `source_task_id` or `content`	ID of a previously successful video generation task; it must belong to the same account, have status `succeeded`, and still be within the 7-day query window
`content`	array	One of `source_task_id` or `content`	List of input items; it must contain exactly one `video_url` item with `role=base_video`, and the original inputs must be re-submitted
`aigc_watermark`	boolean	No	Whether to add an AIGC watermark, defaults to `false`

callback_url is not supported. The source video (768P output) must contain an audio track, have a frame rate of 24 fps, width and height both multiples of 32, an area between 768×768 and 768×1344, and a total frame count of 107 to 362 frames (about 4 to 15 seconds). A single request body must not exceed 64 MB; for larger materials, use a public URL or mm_file://{file_id}. A successful creation returns a task ID. Then poll and query according to section 3; after the task succeeds, obtain the 2K video from task.content.url.

4.3 Billing

Video regeneration is billed by the duration of the final generated 2K video and includes both the output and input parts, both charged at that duration:

Usage	Billing unit
Output 2K video	Seconds
Input source video	Seconds
Input images	The first 5 images are free, and any excess is billed per image

Regeneration keeps the source video duration unchanged, and the upstream returns only that duration in output_seconds (input_seconds is 0), so the input source video item is billed by output_seconds. Settlement is done once after the task succeeds; failed or cancelled tasks are not billed. The exact unit price depends on the pricing page of your platform.

5. H3-Context-IR

H3-Context-IR rewrites the original prompt and multimodal inputs into a structured enhanced prompt for subsequent video generation, and does not produce a video. It uses a dedicated creation endpoint, model is MiniMax-H3, and it shares the query endpoint in section 3; in the query response, task.task_type is h3_context_ir and task.modality is text, and the enhanced prompt is in task.content.prompt.

5.1 Request example

curl -X POST 'https://{api_domain}/v3/minimax-en/v2/h3_context_ir' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A cinematic product video in a clean studio"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://your-cdn.example.com/product.png" },
        "role": "reference_image"
      }
    ],
    "duration": 6
  }'

5.2 Request fields

Field	Type	Required	Description
`model`	string	Yes	Fixed to `MiniMax-H3`
`content`	array	Yes	Multimodal input list; cannot be empty. The item structure is the same as for video generation (`text`, `image_url`, `video_url`, `audio_url`, optionally with `role`)
`duration`	integer	No	Target video duration, an integer from 4 to 15 seconds

callback_url is not supported.

5.3 Response

A successful creation returns a task ID. Then poll and query according to section 3. When the task succeeds, the enhanced prompt is in task.content.prompt:

{
  "task": {
    "id": "424262868365581",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "content": {
      "prompt": "The rewritten structured enhanced prompt"
    },
    "task_type": "h3_context_ir",
    "modality": "text",
    "usage": {
      "prompt_tokens": 120,
      "completion_tokens": 480,
      "total_tokens": 600
    }
  }
}

Use task.content.prompt as the final prompt in a video generation or video regeneration request.

5.4 Billing

H3-Context-IR is billed by tokens, with input and output priced separately, in units of one million tokens:

Usage	Billing unit
Input	Per million `prompt_tokens`
Output	Per million `completion_tokens`

Settlement is done once after the task succeeds; failed or cancelled tasks are not billed. The exact unit price depends on the pricing page of your platform.

6. Python example

The following example uses the standard requests library and does not depend on any specific SDK:

import os
import time

import requests


api_domain = os.environ["API_DOMAIN"]
api_key = os.environ["PLATFORM_API_KEY"]
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

payload = {
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "A calm cinematic landscape"}],
    "resolution": "768P",
    "duration": 4,
    "ratio": "16:9",
}

created = requests.post(
    f"https://{api_domain}/v3/minimax-en/v2/video_generation",
    headers=headers,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["task_id"]

while True:
    result = requests.get(
        f"https://{api_domain}/v3/minimax-en/v2/query/video_generation/{task_id}",
        headers=headers,
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()["task"]
    if task["status"] == "succeeded":
        print(task["content"]["url"])
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task)
    time.sleep(20)

7. Common errors

HTTP	Scenario	Suggested handling
400	The request JSON, model, aspect ratio, duration, or `content` combination is invalid	Fix the request based on `error.message`
401	API Key missing or invalid	Check the `Authorization: Bearer <API_KEY>` request header
402	Insufficient balance or quota (creation endpoint)	Top up or adjust the quota and retry
422	The input contains sensitive content (creation endpoint)	Modify the prompt or input materials and create the task again
429	Request frequency exceeds the limit	Reduce the submission or polling frequency and retry with backoff
500	Server-side error	Retry with exponential backoff; avoid repeatedly submitting the same business task without idempotency control

7.1 HTTP error response structure

When a creation or query endpoint directly returns a non-2xx HTTP status, the response body uses the following structure. Note that error.http_code is a string, and request_id can be used to troubleshoot the request.

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, content must include a non-empty text item (prompt is required) (2013)",
    "http_code": "400"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

The HTTP error body here is different from a queried asynchronous failed task: HTTP error details are in the top-level error.type, error.message, and error.http_code; asynchronous task failure details are in task.error.code and task.error.message. Upstream business errors preserve the original error code and error message as much as possible. For failed or cancelled tasks, do not keep waiting on the same task ID; fix the request and create a new task.

8. Usage recommendations

Persist the task_id after creating a task; do not rely solely on client memory.
Use a polling interval of 10 to 30 seconds for the query endpoint, and set an overall timeout on the client.
After receiving succeeded, download content.url immediately, as the download URL may expire; after it expires, query the task again to obtain a new URL.
Input material URLs must be accessible by the platform and the MiniMax overseas upstream, and must not depend on the customer’s intranet or temporary login sessions.
Use first_frame/last_frame when first and last frames are needed; use reference_image, reference_video, or reference_audio when reference materials are needed, and do not mix the two modes.

Laatst gewijzigd op 21 oktober 2026

⌘I

​1. Overview

​1.1 Endpoints

​1.2 Authentication

​1.3 Supported models

​1.4 Billing

​1.5 Billing and usage field mapping

​2. Create a video generation task

​2.1 Request example: text-to-video

​2.2 Request example: first-frame-to-video

​2.3 Request example: reference-material-to-video

​2.4 Request fields

​2.5 Content combination rules

​2.6 Input material limits

​2.7 Create response

​3. Query task

​3.1 Query example

​3.2 In-progress response

​3.3 Success response

​3.4 Failure and cancellation responses

​3.5 Query response fields

​4. Video regeneration

​4.1 Request examples

​4.2 Request fields

​4.3 Billing

​5. H3-Context-IR

​5.1 Request example

​5.2 Request fields

​5.3 Response

​5.4 Billing

​6. Python example

​7. Common errors

​7.1 HTTP error response structure

​8. Usage recommendations