跳到导航
视频 API

MiniMax H3 Normal

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

MiniMax H3 低速半价档，支持 3–15 秒、480p / 768p / 1080p 视频，原生带音频。

支持的生成方式

生成方式必填参数使用规则
文生视频model, prompt不要传入任何媒体数组。
首帧驱动model, prompt, images传入一个图片 URL。
首尾帧驱动model, prompt, images按首帧到尾帧的顺序传入两个图片 URL。
多模态参考model, prompt, reference_images and/or reference_videosimages 不能与任何 reference_* 输入同时使用。

**Normal 与 Fast：**相同分辨率与时长下，Normal 的价格为 Fast 的一半，但等待更久：480p 为 0.0175 美元/秒，768p 为 0.02 美元/秒，1080p 为 0.025 美元/秒。原 minimax-h3 保持 Fast，minimax-h3-fast 是显式别名。Normal 支持最多两张首尾帧，或最多四张参考图与一个参考视频，两组输入互斥。无音频输入，不支持 adaptive、2K 或 4K；输出原生带音频，不能关闭。可选 seed 必须是 0–9007199254740991 的整数。Fast/Normal 是速度档，此契约不提供 quality 字段。

异步任务流程

创建任务后保存 data.id，每 5–10 秒调用 GET /v1/tasks/{task_id} 查询状态。status 为 succeeded 时读取 data.output.media，为 failed 时读取 data.error_code 和 data.error_message，随后按错误与重试策略处理。

使用本地文件

请先上传本地输入，再将返回的 data.url 填入请求。

鉴权

Authorization   string   必填

在 Authorization 请求头中以 Bearer 令牌发送服务端 API 密钥，可在控制台创建。

Authorization: Bearer <BEATAPI_API_KEY>

永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 Content-Type: application/json。建议为每个逻辑创建请求设置唯一的 Idempotency-Key，只有完全相同的请求体才能安全复用原键。

请求体

字段名、类型和枚举值保留英文原样，用途和限制用中文说明。

model   string   必填

稳定的公开模型 ID，必须使用当前页面列出的值。

取值与默认值: 固定值 minimax-h3-normal

prompt   string   必填

描述生成、编辑或分析目标的提示词。

取值与默认值: 长度 1–5000 字符

images   string[]   选填

按当前模型或工作流要求排序的公网 HTTPS 图片 URL 列表。

取值与默认值: 1–2 项

reference_images   string[]   选填

多模态或参考图生成使用的公网 HTTPS 图片 URL 列表。

取值与默认值: 1–4 项

reference_videos   string[]   选填

多模态或动作迁移使用的公网 HTTPS 视频 URL 列表。

取值与默认值: 1–1 项

duration   integer   选填

请求的输出时长，单位为秒。

取值与默认值: 默认值 5；取值范围 3–15

aspect_ratio   enum<string>   选填

输出素材的宽高比。

取值与默认值: 可选值 16:9、9:16、1:1、4:3、3:4、21:9；默认值 16:9

resolution   enum<string>   选填

输出素材的分辨率或质量档位。

取值与默认值: 可选值 480p、768p、1080p；默认值 768p

seed   integer   选填

可复现生成结果的随机种子。按页面规则使用 -1 时会随机生成。

取值与默认值: 取值范围 0–9007199254740991

请求示例

文生视频

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-normal",
  "prompt": "A slow cinematic push through a misty mountain village at dawn.",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "768p"
}'

首帧驱动

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-normal",
  "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"
}'

首尾帧驱动

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-normal",
  "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"
}'

多模态参考

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-normal",
  "prompt": "Create a cinematic performance using the supplied visual reference.",
  "reference_images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "768p"
}'

响应

成功请求返回 HTTP 201，响应体如下。

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "video",
    "capability_id": "minimax-h3-normal",
    "capability_version": null,
    "media_type": "video",
    "model": "minimax-h3-normal",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.1,
      "credits_charged": 0.1,
      "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 读取托管结果。

错误

状态码含义与处理方式
400JSON 格式错误，或字段、取值、参数组合不被接受（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（可重试）。