> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/video-api/minimax-h3-fast/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # MiniMax H3 Fast > The explicit Fast alias of minimax-h3, with the same prices, input contract, and speed tier and 4–15 second output up to 2K. `POST https://api.beatapi.io/v1/videos/tasks` The explicit Fast alias of minimax-h3, with the same prices, input contract, and speed tier and 4–15 second output up to 2K. ### Supported modes | Mode | Required input | Rules | | --------------------- | ------------------------------------------ | -------------------------------------------------- | | Text to video | `model`, `prompt` | Omit all media arrays. | | First frame | `model`, `prompt`, `images` | Provide one image URL. | | First and last frames | `model`, `prompt`, `images` | Provide two image URLs in first-to-last order. | | Multimodal references | `model`, `prompt`, one `reference_*` array | Do not combine `images` with `reference_*` inputs. | **480p and 1080p:** `aspect_ratio` must be `16:9` or `9:16` (`adaptive` renders 16:9), `duration` must be 5–15 seconds, and first and last frames and `reference_videos` are unavailable. For any other ratio, a 4-second video, first and last frames, or reference videos, use `768P` or `2K`, which accept every option. A request outside these limits is rejected with a 400 before a task is created, so nothing is charged. **Async flow:** Create the task, save `data.id`, then [poll the Task](/quick-guide#get-task-status) with `GET /v1/tasks/{task_id}`. On `succeeded`, read `data.output.media`. On `failed`, read `data.error_code` and `data.error_message`, then follow the [error and retry policy](/quick-guide#errors-and-retry-policy). **Using a local file?** [upload a local input](/quick-guide#upload-an-input-file) first and pass the returned `data.url`. ## Authorization `Authorization`   `string`   **required** Send your BeatAPI API key as a Bearer token. Create one on the [Dashboard](https://beatapi.io/dashboard). ``` Authorization: Bearer ``` Keep permanent API keys on trusted servers. `Content-Type: application/json` is required for the request body. `Idempotency-Key` is optional when the endpoint exposes it and is recommended for safe retries with the exact same body. ## Request body `model`   `string`   **required** Must be `minimax-h3-fast`. This is the explicit Fast alias of `minimax-h3`. **Value:** `minimax-h3-fast` --- `prompt`   `string`   **required** Video generation instructions. **Length:** 1 to 5000 characters --- `images`   `string[]`   **optional** One first-frame image or first- and last-frame images as public HTTPS URLs. First and last frames need 768P or 2K. **Count:** 1 to 2 items --- `reference_images`   `string[]`   **optional** Public HTTPS image references for multimodal reference generation. **Count:** 1 to 9 items --- `reference_videos`   `string[]`   **optional** Public HTTPS video references for multimodal reference generation. Available at 768P and 2K only. **Count:** 1 to 3 items --- `reference_audios`   `string[]`   **optional** Public HTTPS audio references for multimodal reference generation. Audio also requires at least one reference image or video. **Count:** 1 to 3 items --- `duration`   `integer`   **optional** Requested output duration in seconds. 480p and 1080p start at 5 seconds. **Default:** `5` \ **Range:** 4 to 15 --- `aspect_ratio`   `enum`   **optional** Text mode defaults to 16:9 and does not accept adaptive. Frame mode always uses adaptive at 768P and 2K. Reference mode defaults to adaptive and also accepts a concrete ratio. 480p and 1080p accept only 16:9 and 9:16 and render adaptive as 16:9. **Available options:** `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` --- `resolution`   `enum`   **optional** Output resolution tier. 480p and 1080p accept 16:9 or 9:16 only, 5 seconds or longer, without first and last frames or reference videos; 768P and 2K accept every option. 1080p is exclusive to this gateway — nobody else sells H3 at that tier. Price scales with it. **Available options:** `480p`, `768P`, `1080p`, `2K` \ **Default:** `"768P"` ## Request examples ### Text to video ```bash curl --request POST \ --url https://api.beatapi.io/v1/videos/tasks \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "minimax-h3-fast", "prompt": "A slow cinematic push through a misty mountain village at dawn.", "duration": 5, "aspect_ratio": "16:9", "resolution": "768P" }' ``` ### First frame ```bash curl --request POST \ --url https://api.beatapi.io/v1/videos/tasks \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "minimax-h3-fast", "prompt": "The performer turns toward the camera as neon light sweeps across the scene.", "images": [ "https://media.beatapi.io/samples/neon-singer.png" ], "duration": 5, "resolution": "768P" }' ``` ### First and last frames ```bash curl --request POST \ --url https://api.beatapi.io/v1/videos/tasks \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "minimax-h3-fast", "prompt": "Move smoothly from the opening portrait to the final product reveal.", "images": [ "https://media.beatapi.io/samples/neon-singer.png", "https://media.beatapi.io/samples/smart-bottle.png" ], "duration": 5, "resolution": "768P" }' ``` ### Multimodal references ```bash curl --request POST \ --url https://api.beatapi.io/v1/videos/tasks \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "minimax-h3-fast", "prompt": "Create a cinematic performance using the supplied visual and audio references.", "reference_images": [ "https://media.beatapi.io/samples/neon-singer.png" ], "reference_audios": [ "https://media.beatapi.io/samples/neon-singer-preview.mp3" ], "duration": 5, "aspect_ratio": "16:9", "resolution": "768P" }' ``` ## Response A successful request returns HTTP `201`. ```json { "data": { "id": "task_8K2qA", "object": "task", "task_kind": "video", "capability_id": "minimax-h3-fast", "capability_version": null, "media_type": "video", "model": "minimax-h3-fast", "status": "queued", "stage": "queued", "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 0.2, "credits_charged": 0.2, "billable_duration_seconds": 5, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_abc123", "error_code": null, "error_message": null } } ``` ## Errors | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Malformed JSON or a field, value or combination this endpoint does not accept (`bad_request`; the message names the field), or input refused by moderation (`content_policy_violation`). Not retryable unchanged. | | `401` | No API key (`missing_api_key`), or a key that is wrong, expired, disabled or exhausted (`invalid_api_key`; the message says which). Send it as `Authorization: Bearer `; the key works with or without the `sk-` prefix. Not retryable. | | `402` | Insufficient balance (`insufficient_credits`). The account balance is zero or below the price of this request. Top up, then send it again; not retryable before that. | | `403` | The key or account is not permitted to make this call (`forbidden`), for example a model that is not available on free credit (a top-up unlocks it), a request from outside the key's IP allowlist, or a model outside the key's group. Not retryable. | | `409` | The `Idempotency-Key` was already used with a different request body, or the first request with it is still being processed (`idempotency_conflict`). Not retryable unchanged. | | `429` | Too many requests (`rate_limit_exceeded`, including the free-model limits) or too many tasks processing at once (`user_concurrency_exceeded`). Retryable after `Retry-After` seconds (also `error.retry_after_seconds`). | | `500` | Unexpected internal error (`internal_error`). Retryable; keep `request_id` for support if it persists. | | `503` | The request could not be completed (`processing_unavailable`, `processing_timeout`, `processing_failed` or `result_transfer_failed`). Nothing was charged. Retryable with backoff; `Retry-After` is sent when the wait is known. BeatAPI does not answer 502 or 504. | > The explicit Fast alias of minimax-h3, with the same prices, input contract, and speed tier and 4–15 second output up to 2K.