MiniMax H3 API with Python: create, poll, and download

A minimal server-side Python workflow

The vgenv MiniMax H3 API uses standard HTTP and JSON, so Python does not require a vendor SDK. A production integration has three steps: create a Video with POST /v2/videos, poll GET /v2/videos/{id}, and store the successful output before the signed URL expires.

Keep VGENV_API_KEY in a server-side environment variable. Do not expose it in notebooks shared publicly, browser code, mobile applications, or source control.

export VGENV_API_KEY="vgenv_live_..."
python3 quickstart.py

Create an idempotent MiniMax H3 video

This example uses only Python's standard library. A unique Idempotency-Key makes a network retry safe: sending the same logical request with the same key returns the original Video instead of creating a second billed job.

import json, os, urllib.request, uuid

base = "https://api.vgenv.com/v2"
payload = json.dumps({
    "model": "minimax/h3",
    "tier": "fast",
    "prompt": "A cinematic paper city waking at sunrise",
    "duration": 5,
    "resolution": "480p",
    "aspect_ratio": "9:16",
}).encode()

request = urllib.request.Request(
    f"{base}/videos",
    data=payload,
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['VGENV_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": f"python-{uuid.uuid4()}",
    },
)
with urllib.request.urlopen(request, timeout=30) as response:
    video = json.load(response)
print(video["id"], video["price"])

Poll until a terminal state

Treat queued and running as non-terminal. Stop when the status becomes succeeded, failed, or cancelled. An eight-to-ten-second interval is a sensible starting point, and a 429 response should honor Retry-After instead of immediately retrying.

import time

terminal = {"succeeded", "failed", "cancelled"}
while video["status"] not in terminal:
    time.sleep(8)
    request = urllib.request.Request(
        f"{base}/videos/{video['id']}",
        headers={"Authorization": f"Bearer {os.environ['VGENV_API_KEY']}"},
    )
    with urllib.request.urlopen(request, timeout=30) as response:
        video = json.load(response)
    print(video["status"], video["progress"])

if video["status"] == "succeeded":
    print(video["output"]["url"])
else:
    raise RuntimeError(video.get("error", video["status"]))

Production safeguards

Wrap HTTP failures in an application-specific exception that preserves the status code and Retry-After value. Add an overall deadline so a worker cannot poll forever, and record the Video ID before entering the polling loop so another process can resume the task after a restart.

• Use a secret manager for the API key.
• Persist Video ID, status, quote, and output expiry.
• Retry GET requests with backoff; do not blindly retry creation with a new idempotency key.
• Copy completed output to storage you control before the signed URL expires.