MiniMax Video – H3 Official API

MiniMax Official Video

Use the scripts/minimax_video.py of this skill to connect directly to the MiniMax official V2 API. The default domestic endpoint is https://api.minimax.cn; the international endpoint is https://api.minimax.io. The default model is MiniMax-H3. Generally, new MiniMax tasks use this skill; Naduotong tasks must be queried from the original client, and task IDs are not migrated across services.

Configuration

• Locate the script from the actual skill installation directory. Prefer ~/.config/minimax/venv/bin/python; plain text, HTTPS, or mm_file:// input only requires Python 3.9+. Local asset validation and optional R2 delivery require the dependencies in scripts/requirements.txt.
• Credentials are read from MINIMAX_API_KEY (environment variable takes priority), otherwise parsed from ~/.config/minimax/env. Do not read chat credentials from other applications; do not write keys into the skill, command line, or task records. See Configuration & Recovery for domestic/international endpoints and tool environment.
• If the key is missing, run scripts/configure.py --region cn --gui to configure via hidden input on macOS; on other systems, read it in the user's terminal with hidden input. Do not ask users to paste the key into chat. Users with an existing environment variable can use --from-env; to rotate, use --replace-key.
• doctor --check-api only reads the recent task list to verify authentication and the V2 query endpoint; it does not prove balance, generation rights for specific models, or final video quality. Installation, configuration, or API research does not authorize paid generation.

Parameters & Inputs

When selecting a model, non-default parameters, or multimodal materials, first read Official API & Capabilities; do not re-use Naduotong model IDs, 720p/960p tiers, or 4–12 second limits.

• Default samples are H3, 4 seconds, 768P; plain text defaults to 16:9; first/last frame aspect ratio is determined by the input image. The four H3 models have different resolution, duration, and reference ratio limits; validate per model on the client side.
• --first-frame and --last-frame each accept at most one image; for multimodal references, use repeatable --ref-image, --ref-video, --ref-audio. First/last frames cannot be mixed with multimodal references. Maintain material order and explicitly identify roles in the prompt (e.g., "Reference Image 1", "Reference Video 1").
• Materials support local files, HTTPS URLs, or mm_file:// handles of the current official account. For local input, first save an immutable copy and validate format, dimensions, duration, etc.; remote media specifications are validated by the official API—do not claim to have reviewed them locally.
• For small local materials, the default is --delivery inline, which passes them as data URIs in the generation request, requiring no third-party hosting. The Base64‑expanded total request size must not exceed 64 MB. For local MOV or larger materials, explicitly use --delivery r2 and then run host. Do not automatically upload, transcode, or modify the user's original files to bypass limits.
• R2 mode uses only a configured private bucket, deduplicates objects by hash, and verifies anonymous downloads. Before uploading, comply with the target project's material and privacy conventions; host only materials authorized for the current task. If configuration or hosting fails, report the error; do not automatically switch to another image host.

Generation & Follow-up

Complete one candidate per user request to generate a video; batches and additional attempts follow the same convention. Use a new task directory for each candidate, preferring tmp/artwork/generations/<run-id>/<asset-id>/<attempt-id>/ (which should be gitignored); if no project exists, use a workspace temp directory or a user-specified location, and do not overwrite old tasks.

1. Run doctor --check-api to check configuration. Write action, camera, character/prop constraints, and sound requirements into a UTF-8 prompt file; use prepare to freeze the prompt, official parameters, service region, and input copies. This step is offline and does not generate video.
2. Run host only if --delivery r2 and local materials are present. This uploads materials to the private R2 bucket and lets MiniMax use signed URLs; inline materials are sent directly to MiniMax.
3. Run submit once. The client exclusively saves the submission record and request hash before the paid POST request; the official documentation does not promise idempotency keys—do not treat local request UUIDs as server-side deduplication guarantees.
4. Query status using independent status calls; states are queued / running / succeeded / failed / cancelled. Use host-interruptible waits and maintain progress communication; do not poll for minutes in a long shell command.
5. On success, download with download, validate the MP4, and save the hash. On download failure, only retry status / download; expired media URLs can be refreshed by re-querying. The official API only provides task queries for the last 7 days—save results promptly.
6. To resume across conversations, first run inspect --job, then status / download. Any existing submission.json blocks resubmission. Timeouts, disconnections, 5xx errors, or missing IDs are ambiguous results—preserve evidence; you may use read-only tasks for cross-checking, but similar model and timing do not prove the same task. Do not automatically create additional paid candidates on failure or ambiguity.

Command examples (variables represent actual absolute paths; JOB must not already exist):

"$PY" "$CLIENT" doctor --check-api
"$PY" "$CLIENT" prepare --job "$JOB" --prompt-file "$PROMPT_FILE" --first-frame "$FIRST_FRAME" --duration 4 --resolution 768P
"$PY" "$CLIENT" submit --job "$JOB"
"$PY" "$CLIENT" status --job "$JOB"
"$PY" "$CLIENT" download --job "$JOB"

For plain text, omit --first-frame and optionally provide --ratio; for first/last frame, add --last-frame. For multimodal references, use the corresponding --ref-* parameters. In R2 mode, add --delivery r2 during prepare and run host --job "$JOB" before submit. For complete options, read the script's --help.

Delivery

Deliver a playable local video.mp4 and the task directory, showing the video with an absolute path. Describe the actual model, duration, resolution, aspect ratio, and audio performance, as well as whether you reviewed the raw-speed video, first/last frames, and character consistency; an HTTP success does not constitute visual acceptance.

Task records contain the prompt, Base64 materials, signed URLs, and real task IDs; they are readable only by the current user. Do not paste entire records into chat or commit them to Git. The console shows the task fingerprint; official API Bearer tokens are sent only to authorized official API hosts, and all final videos and their redirects are downloaded anonymously over HTTPS.