Allen's MiniMax H3 Python SDK
Text-to-video with synchronised audio, generated on a private RTX 3090.
You do not need to know anything about HTTP endpoints, job polling, ComfyUI or workflow graphs — submit a prompt, get an MP4.
from allens_h3 import H3Client
client = H3Client()
video = client.generate(prompt="A cinematic AI business school commercial",
duration=5)
video.download("video.mp4")
Install
pip install allens-h3
From a local wheel:
pip install dist/allens_h3-1.0.0-py3-none-any.whl
Requires Python 3.9+. The only runtime dependency is httpx.
Configure
Two values are needed. Neither is ever hard-coded in the SDK, because the endpoint hostname can change.
| Variable | Meaning |
|---|---|
ALLENS_H3_BASE_URL |
HTTPS endpoint, e.g. https://xxxx.trycloudflare.com |
ALLENS_H3_API_KEY |
your credential |
# macOS / Linux
export ALLENS_H3_BASE_URL="https://xxxx.trycloudflare.com"
export ALLENS_H3_API_KEY="..."
# Windows PowerShell
$env:ALLENS_H3_BASE_URL = "https://xxxx.trycloudflare.com"
$env:ALLENS_H3_API_KEY = "..."
Or pass them explicitly:
client = H3Client(api_key="...", base_url="https://xxxx.trycloudflare.com")
Explicit arguments win; otherwise the environment is used.
The endpoint currently runs through a Cloudflare Quick Tunnel, whose hostname changes whenever the tunnel restarts. Ask for the current URL, or update
ALLENS_H3_BASE_URLwhen it moves.
Generate
video = client.generate(
prompt="A cinematic nighttime shot of downtown Vancouver after rain",
width=608, # multiple of 32
height=352, # multiple of 32
duration=5, # 1-10 seconds
steps=20, # 4-40
seed=None, # omit for the server default
timeout=1800,
)
print(video.job_id)
video.download("output.mp4")
data = video.content() # or get the bytes directly
generate() submits the job, polls until it finishes, and returns the result.
A 5-second clip takes roughly 4-5 minutes.
With a progress callback:
video = client.generate(
prompt="...",
on_progress=lambda job: print(f"{job.status} {job.percent}%"),
)
Job control
For long jobs you may not want to block:
job = client.create_video(prompt="...", duration=5)
print(job.id, job.status) # queued
job = client.get_job(job.id) # poll whenever you like
print(job.status, job.percent)
job = client.wait(job.id) # block until terminal
client.download(job.id, "out.mp4")
Cancel a queued or running job:
client.cancel(job.id)
List your recent jobs (only ever your own):
for job in client.list_jobs(limit=10):
print(job.id, job.status)
Service and GPU status
health = client.health()
print(health.is_ok, health.comfyui, health.worker)
gpu = client.gpu()
print(gpu.name, gpu.temperature_c, gpu.hotspot_c, gpu.power_w, gpu.is_busy)
Async
import asyncio
from allens_h3 import AsyncH3Client
async def main():
async with AsyncH3Client() as client:
video = await client.generate(prompt="A cinematic commercial",
duration=5)
await video.download("output.mp4")
asyncio.run(main())
The async API mirrors the sync one method for method.
Error handling
Every failure is a typed exception, so you never inspect a status code:
from allens_h3 import (
H3Error, H3AuthenticationError, H3RateLimitError,
H3ValidationError, H3GPUUnavailableError, H3JobFailedError,
H3TimeoutError,
)
try:
video = client.generate(prompt="...")
except H3AuthenticationError:
print("bad or revoked key")
except H3RateLimitError as e:
print(f"slow down; retry after {e.retry_after}s")
except H3ValidationError as e:
print(f"bad parameters: {e}")
except H3GPUUnavailableError:
print("GPU busy or too hot; try later")
except H3JobFailedError as e:
print(f"job {e.job_id} ended as {e.job_status}")
except H3TimeoutError:
print("still running — poll get_job() to keep checking")
except H3Error as e:
print(f"unexpected: {e}")
| Exception | HTTP |
|---|---|
H3ValidationError |
400, 413, 422 |
H3AuthenticationError |
401 |
H3PermissionError |
403 |
H3NotFoundError |
404 |
H3ConflictError |
409 |
H3RateLimitError |
429 |
H3GPUUnavailableError |
502, 503, 504 |
Command line
For colleagues who do not write Python:
allens-h3 health
allens-h3 gpu
allens-h3 generate \
--prompt "A cinematic BBA AI commercial" \
--duration 5 \
--output output.mp4
allens-h3 jobs
allens-h3 status h3_abc123
allens-h3 cancel h3_abc123
allens-h3 download h3_abc123 -o video.mp4
The CLI reads credentials from the environment only — passing a key as a flag would leave it in your shell history.
Limits
Server-enforced, per credential:
| Limit | Default |
|---|---|
| API requests | 20 / minute |
| Generations | 12 / hour |
| Queued jobs | 3 |
| Prompt length | 2000 characters |
| Resolution | 256-1280 × 256-720, multiples of 32 |
| Duration | 1-10 seconds |
| Steps | 4-40 |
Only one job runs on the GPU at a time; the rest queue.
Security
- TLS verification is always on and cannot be disabled.
- The API key travels in the
Authorizationheader, never in a URL. - The key is never written to disk or to any log by this SDK.
- Exception messages are scrubbed of anything credential-shaped.
base_urlis validated; embedded credentials are rejected.- Plain
http://to a remote host is refused. - Failed reads and 502/503/504 are retried with exponential backoff; generation requests are never retried automatically, to avoid producing a duplicate video.
Version
1.0.0 — see CHANGELOG.md.
Metadata
Release files for allens-h3 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| allens_h3-1.0.0.tar.gz | 14.9 kB | Without provenance | Details for allens_h3-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| allens_h3-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for allens_h3-1.0.0-py3-none-any.whl |
Total release size: 34.4 kB
Release files / allens_h3-1.0.0.tar.gz
| Download URL | allens_h3-1.0.0.tar.gz |
|---|---|
| Size | 14.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
574fce4726c79100ed4f1ff443bd536fa8a2c4b978392477180eb264155c5cef
|
|
BLAKE2b-256 checksum How to use checksums |
539ee36bc09a9fcddafa389670ff9e0d6547c1f38a8bb5bb260a7313bacf99b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Release files / allens_h3-1.0.0-py3-none-any.whl
| Download URL | allens_h3-1.0.0-py3-none-any.whl |
|---|---|
| Size | 19.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e0a3ccf3eb16bc341c7289079561da4b02a579be867a85557bdf1823e9f9ca5
|
|
BLAKE2b-256 checksum How to use checksums |
e1dc98d5b621f23ce3ebc57e76d903a421c9869adc94646d230f4a52b42755ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Security for allens-h3 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.