MiniMax H3 API in Python: submit, poll and download a video job

To call MiniMax H3 from Python, POST to https://api.sume.com/v1/videos with model: "minimax-h3", poll the returned polling_url until status is completed, then download unsigned_urls[0]. Generation is asynchronous, so the script below submits once and polls every 15 seconds.

The flow and fields are from the Sume Video generation docs, read 2026-09-29. It needs pip install httpx and SUME_API_KEY in the environment.

What does the script look like?

It reuses one Idempotency-Key so that a retried submit does not create a second job, and stops on failed or cancelled.

import asyncio
import os
import httpx

API = "https://api.sume.com/v1/videos"
HEADERS = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}

async def main():
    body = {
        "model": "minimax-h3",
        "prompt": "A paper boat drifts down a rainy gutter, close-up, soft rain sound",
        "resolution": "768p",
        "aspect_ratio": "16:9",
        "duration": 5,
    }
    async with httpx.AsyncClient(timeout=60, follow_redirects=True) as client:
        r = await client.post(API, json=body, headers={**HEADERS, "Idempotency-Key": "h3-py-001"})
        r.raise_for_status()
        url = r.json()["polling_url"]
        while True:
            await asyncio.sleep(15)
            job = (await client.get(url, headers=HEADERS)).json()
            if job["status"] == "completed":
                clip = await client.get(job["unsigned_urls"][0], headers=HEADERS)
                open("h3.mp4", "wb").write(clip.content)
                return
            if job["status"] in ("failed", "cancelled"):
                raise RuntimeError(job.get("error", job["status"]))

asyncio.run(main())

What can go wrong?

How long should I poll?

Sume's own docs example polls every 30 seconds. No generation time is published for H3, so pick a poll interval and an overall timeout from your own test runs.

Can I get a webhook instead of polling?

Yes: the request takes callback_url, which must be HTTPS, and Sume notifies it when the job completes. If you verify the webhook, refuse to run with an empty secret. Keep the polling loop as a fallback.