> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/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 > minimax-h3 的显式 Fast 别名：相同价格、输入契约与速度档，生成 4–15 秒视频，最高 2K 输出。 `POST https://api.beatapi.io/v1/videos/tasks` minimax-h3 的显式 Fast 别名：相同价格、输入契约与速度档，生成 4–15 秒视频，最高 2K 输出。 ### 支持的生成方式 | 生成方式 | 必填参数 | 使用规则 | | ----- | -------------------------------------- | ------------------------------------ | | 文生视频 | `model`, `prompt` | 不要传入任何媒体数组。 | | 首帧驱动 | `model`, `prompt`, `images` | 传入一个图片 URL。 | | 首尾帧驱动 | `model`, `prompt`, `images` | 按首帧到尾帧的顺序传入两个图片 URL。 | | 多模态参考 | `model`, `prompt`, 一个 `reference_*` 数组 | `images` 不能与任何 `reference_*` 输入同时使用。 | **480p 与 1080p：**`aspect_ratio` 只能是 `16:9` 或 `9:16`（`adaptive` 按 16:9 出片），`duration` 为 5–15 秒，不支持首尾帧和 `reference_videos`。需要其他宽高比、4 秒时长、首尾帧或参考视频时，请使用 `768P` 或 `2K`，这两档支持全部选项。超出限制的请求会在创建任务前直接返回 400，不会扣费。 **异步任务流程** 创建任务后保存 `data.id`，每 5–10 秒调用 `GET /v1/tasks/{task_id}` 查询状态。`status` 为 `succeeded` 时读取 `data.output.media`，为 `failed` 时读取 `data.error_code` 和 `data.error_message`，随后按[错误与重试策略](/quick-guide#errors-and-retry-policy)处理。 **使用本地文件** 请先[上传本地输入](/quick-guide#upload-an-input-file)，再将返回的 `data.url` 填入请求。 ## 鉴权 `Authorization`   `string`   **必填** 在 `Authorization` 请求头中以 Bearer 令牌发送服务端 API 密钥，可在[控制台](https://beatapi.io/dashboard)创建。 ``` Authorization: Bearer ``` 永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 `Content-Type: application/json`。建议为每个逻辑创建请求设置唯一的 `Idempotency-Key`，只有完全相同的请求体才能安全复用原键。 ## 请求体 字段名、类型和枚举值保留英文原样，用途和限制用中文说明。 `model`   `string`   **必填** 稳定的公开模型 ID，必须使用当前页面列出的值。 **取值与默认值:** 固定值 `minimax-h3-fast` --- `prompt`   `string`   **必填** 描述生成、编辑或分析目标的提示词。 **取值与默认值:** 长度 1–5000 字符 --- `images`   `string[]`   **选填** 按当前模型或工作流要求排序的公网 HTTPS 图片 URL 列表。 **取值与默认值:** 1–2 项 --- `reference_images`   `string[]`   **选填** 多模态或参考图生成使用的公网 HTTPS 图片 URL 列表。 **取值与默认值:** 1–9 项 --- `reference_videos`   `string[]`   **选填** 多模态或动作迁移使用的公网 HTTPS 视频 URL 列表。 **取值与默认值:** 1–3 项 --- `reference_audios`   `string[]`   **选填** 多模态生成使用的公网 HTTPS 参考音频 URL 列表。 **取值与默认值:** 1–3 项 --- `duration`   `integer`   **选填** 请求的输出时长，单位为秒。 **取值与默认值:** 默认值 `5`；取值范围 4–15 --- `aspect_ratio`   `enum`   **选填** 输出素材的宽高比。 **取值与默认值:** 可选值 `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` --- `resolution`   `enum`   **选填** 输出素材的分辨率或质量档位。 **取值与默认值:** 可选值 `480p`、`768P`、`1080p`、`2K`；默认值 `768P` ## 请求示例 ### 文生视频 ```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" }' ``` ### 首帧驱动 ```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" }' ``` ### 首尾帧驱动 ```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" }' ``` ### 多模态参考 ```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" }' ``` ## 响应 成功请求返回 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 } } ``` ## 下一步 保存接受响应中的 `data.id`，每 5–10 秒轮询 `GET /v1/tasks/{task_id}`。任务成功后从 `data.output.media` 读取托管结果。 ## 错误 | 状态码 | 含义与处理方式 | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | JSON 格式错误，或字段、取值、参数组合不被接受（`bad_request`，错误信息会点名字段）；输入未通过内容审核时为 `content_policy_violation`。修正后再请求，原样重试仍会失败。 | | `401` | 未提供 API 密钥（`missing_api_key`），或密钥错误、已过期、已停用或额度已用尽（`invalid_api_key`，错误信息会说明是哪一种）。不要原样重试。 | | `402` | 余额不足（`insufficient_credits`）：账户余额为零或低于本次请求的价格。充值后再请求。 | | `403` | 密钥或账户无权执行该调用（`forbidden`），例如免费额度不能使用该模型（充值即可解锁）、请求来源不在密钥的 IP 白名单内，或模型不在密钥的分组里。不要原样重试。 | | `409` | 幂等键已用于其他请求体，或使用该键的首个请求仍在处理中（`idempotency_conflict`）。只对完全相同的请求复用原键。 | | `429` | 请求过于频繁（`rate_limit_exceeded`，含免费模型限额）或同时处理中的任务过多（`user_concurrency_exceeded`）。按 `Retry-After`（也在 `error.retry_after_seconds`）等待后重试。 | | `500` | 内部异常（`internal_error`），可以重试；持续出现时请保留 `request_id` 联系支持。 | | `503` | 请求未能完成（`processing_unavailable`、`processing_timeout`、`processing_failed` 或 `result_transfer_failed`），未扣费，可退避重试；已知等待时间时会返回 `Retry-After`。实时接口未启用时为 `realtime_disabled`（不可重试），容量不足时为 `realtime_capacity_unavailable`（可重试）。 |