Skip to main content

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_URL when 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 Authorization header, 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_url is 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)

Source distribution for allens-h3 1.0.0
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)

Table of built distributions (wheels) for allens-h3 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page