MiniMax H3 python api: Setup Guide & Async Workflow

MiniMax H3 is a multimodal AI video-generation model that accepts natural-language prompts and supported reference materials. The Python API is designed for applications that need to submit video jobs, monitor rendering progress, and retrieve completed files without keeping a request open for the entire generation process.

The standard workflow is asynchronous. Your application sends a video-generation request, receives a task_id, checks the task status at intervals, and retrieves the output after the task reaches Success. This structure works well for web applications, internal tools, content pipelines, and batch-generation systems.

The official MiniMax H3 workflow supports short-form video generation with configurable duration and resolution. Depending on the selected endpoint and account configuration, available controls may include text prompts, image references, video references, audio instructions, aspect ratio, and output resolution.

Before writing the integration, prepare a Python environment, install the HTTP client, and store the MiniMax API key outside your application code. This approach reduces accidental key exposure in repositories, logs, screenshots, and client-side bundles.

The examples below use Python and the requests package. Install it in the environment used by your application:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install requests

Set the API key as an environment variable before running the script:

export MINIMAX_API_KEY="YOUR_API_KEY"

On Windows PowerShell, use:

$env:MINIMAX_API_KEY="YOUR_API_KEY"

Follow this four-stage process for a basic MiniMax H3 Python API integration. The key design principle is to separate task submission from task monitoring. A production service should be able to restart polling without submitting the same generation again.

A compact Python implementation looks like this:

import os
import time
import requests

API_KEY = os.environ["MINIMAX_API_KEY"]
BASE_URL = "https://api.minimax.io/v1"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "MiniMax-H3",
    "prompt": (
        "A premium perfume bottle rotating on black glass, "
        "dramatic studio lighting, synchronized ambient sound."
    ),
    "duration": 6,
    "resolution": "768P",
}

create_response = requests.post(
    f"{BASE_URL}/video_generation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
create_response.raise_for_status()

task_id = create_response.json()["task_id"]
print("Created task:", task_id)

while True:
    query_response = requests.get(
        f"{BASE_URL}/query/video_generation",
        headers=HEADERS,
        params={"task_id": task_id},
        timeout=30,
    )
    query_response.raise_for_status()

    task = query_response.json()
    status = task.get("status")
    print("Current status:", status)

    if status == "Success":
        file_id = task["file_id"]
        print("Completed file:", file_id)
        break

    if status == "Fail":
        message = task.get("error_message", "Video generation failed")
        raise RuntimeError(message)

    time.sleep(10)

For a completed task, retrieve the file information using the returned ID:

file_id = "FILE_ID_FROM_SUCCESS_RESPONSE"

file_response = requests.get(
    f"{BASE_URL}/files/retrieve",
    headers=HEADERS,
    params={"file_id": file_id},
    timeout=30,
)
file_response.raise_for_status()

file_data = file_response.json()
download_url = file_data.get("file", {}).get("download_url")
if not download_url:
    download_url = file_data.get("download_url")

print("Download URL:", download_url)

The exact response shape may vary by endpoint version. During integration, inspect the JSON response and follow the current MiniMax video generation API documentation.

A simple script can raise an exception when an HTTP request fails, but a production integration needs more structure. Separate client errors from temporary service errors, use bounded retries, and preserve the original task identifier.

Use exponential backoff for temporary failures instead of retrying immediately:

import time

def wait_with_backoff(attempt, base_delay=5, max_delay=60):
    delay = min(base_delay * (2 ** attempt), max_delay)
    time.sleep(delay)

For polling, apply a maximum wait time so a worker does not remain active indefinitely:

started_at = time.time()
max_wait_seconds = 30 * 60

while time.time() - started_at < max_wait_seconds:
    # Query the task here.
    # Break on Success or Fail.
    time.sleep(10)

raise TimeoutError("The MiniMax H3 task exceeded the polling limit.")

Use these practices when moving beyond a local test:

• Keep prompts and payloads reproducible. Store the prompt, model, duration, resolution, and reference-file identifiers.
• Use a background worker. Web requests should create jobs, not wait for the full video render.
• Prevent duplicate submissions. Assign an internal request ID before calling the create endpoint.
• Validate inputs early. Reject missing files, unsupported formats, and conflicting settings before API submission.
• Protect output URLs. Treat returned download links as application data and copy important files into controlled storage.
• Monitor usage. Track successful tasks, failed tasks, retry counts, and total generated seconds.

The safest starting point is a small backend script that creates one short H3 task, polls it with timeouts, retrieves the result, and records every response needed for debugging. Once that path works, add queues, persistent storage, retry policies, and application-level request tracking.