MiniMax H3

Generate 4–15 second videos at 768P or 2K from text, one or two frames, or up to 9 images, 3 videos and 3 audio clips as references, priced per second.

• Asynchronous: the create call returns a task ID; the video arrives when the task succeeds.
• Four ways in: text only, a first frame, a first and last frame, or reference images, videos and audio.
• Two resolutions: 768P (the default) and 2K. 480p and 1080p belong to minimax-h3-normal.
• Billed per second of video at the rate of the chosen resolution. A failed task costs nothing.

Opens this model in the API Explorer. Enter your BeatAPI API key to create a task: the call is real and is billed to your own balance.

Model IDs

Five MiniMax H3 models share this endpoint but not the same inputs. The values below come straight from the gateway contract.

Endpoint and authentication

POST https://api.beatapi.io/v1/videos/tasks

Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.

How a request works

Input modes

Request parameters

The gateway also checks these combinations before creating the task:

• images cannot be combined with reference inputs
• Only 768P and 2K are available; both tiers accept the full H3 input contract

Input media limits

The gateway reads every input before the task is created and refuses one outside these limits with a 400 bad_request that names the input. Nothing is charged.

• The limits apply to images and reference_images (images), reference_videos (videos) and reference_audios (audio).
• Inputs are checked one by one, in the order images, reference_images, reference_videos, reference_audios. For one input the order is length, sides, aspect ratio, frame rate; the total length of all reference videos is checked last. The message names the input by list and position, counting from 0 like the field errors: images[0] is 200x200 pixels; this model takes images 256 to 5760 pixels on each side.
• Lengths are measured with a 0.1-second tolerance. Sizes are checked only when the host reports them.
• A link is refused at create only when its host answers with an HTTP 4xx error or returns an empty file, for example reference_videos[0] could not be downloaded: the URL returned HTTP 404.; other problems with an input surface after submission and fail the task (refunded).
• Have a local file? Upload it with POST /v1/files and pass the returned data.url.

Fields this model does not accept

Sending one of these is refused before anything is charged, instead of being ignored:

• seed, generate_audio, watermark, quality, sound and any other field from other video models → field "seed" is not supported by model minimax-h3 (with the field you sent).
• Any other unknown field → unknown field: <name>.

Request examples

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3",
  "prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "768P"
}'

Text to video

A 5-second 768P landscape clip.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3",
  "prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "768P"
}'

First frame

The video starts from the image and follows its shape.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3",
  "prompt": "The performer turns toward the camera as neon light sweeps across the stage",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "resolution": "768P"
}'

First and last frame

The video moves from the first image to the second, in 2K.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3",
  "prompt": "The camera moves smoothly from the bottle on the table to the singer on a neon stage in one continuous shot",
  "images": [
    "https://media.beatapi.io/samples/smart-bottle.png",
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 6,
  "resolution": "2K"
}'

Image and audio references

A performance that follows a character image and a music clip (the sample clip runs about 12 seconds).

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3",
  "prompt": "The singer from the first reference image performs on stage in time with the reference music, warm spotlights, slow orbiting camera",
  "reference_images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "reference_audios": [
    "https://media.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "768P"
}'

Image and video references

Replace the video link with your own MP4 or MOV of at most 15 seconds, at 23.976 to 60 frames per second.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3",
  "prompt": "A product film: the bottle from the first reference image on a turntable, camera movement like the first reference video",
  "reference_images": [
    "https://media.beatapi.io/samples/smart-bottle.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "duration": 8,
  "resolution": "768P"
}'

Responses

Create a task (201)

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "minimax-h3",
    "capability_version": 1,
    "media_type": "video",
    "model": "minimax-h3",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.2,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.2,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Finished task

GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "minimax-h3",
    "capability_version": 1,
    "media_type": "video",
    "model": "minimax-h3",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.2,
      "credits_settled": 0.2,
      "credits_refunded": 0,
      "credits_charged": 0.2,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Output fields

Failed task

A failed task is still HTTP 200 on GET /v1/tasks/{task_id}: the failure is in the body. The reservation is returned in full, so nothing is charged.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "minimax-h3",
    "capability_version": 1,
    "media_type": "video",
    "model": "minimax-h3",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.2,
      "credits_settled": 0,
      "credits_refunded": 0.2,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Complete example

Create a task, wait for it with the server’s polling hint, and print the result URLs. Set BEATAPI_API_KEY in your environment and install requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "minimax-h3",
  "prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "768P"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Billing

• Billed per second of video: the requested duration times the rate of the chosen resolution, which is about $0.04 per second at 768P and$0.06 per second at 2K.
• The aspect ratio, the number of frames or references, and the length of reference videos do not change the price.
• The price is reserved when the task is created; usage.billable_duration_seconds on the task shows the seconds billed.
• A failed task, including one refused by moderation after submission, is refunded in full.

Current list prices, the same as on Pricing. An account with a negotiated discount pays less; data.usage on the task always shows the amount actually charged.

Common errors

HTTP errors at a glance

Errors before a task exists arrive as a non-2xx response, and nothing is charged. Branch on error.code or error.retryable; message names the problem. The full list and retry policy are on Errors.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}