视频 API

通过稳定的 BeatAPI 模型 ID 创建一个异步视频生成任务。

模型	输入模式	必填字段	主要控制项
`minimax-h3`	原 ID，保持 Fast 契约与价格	`model`, `prompt`	4–15 秒，最高 2K
`minimax-h3-fast`	`minimax-h3` 的显式 Fast 别名	`model`, `prompt`	与原 ID 的输入限制、价格相同
`minimax-h3-normal`	更慢、半价，文字、首尾帧或视觉参考	`model`, `prompt`	5–15 秒；480p/768p/1080p；原生带音频，无音频输入
`grok-imagine-video-1.5`	文本、首帧、最多 7 张参考图	`model`, `prompt`	1–15 秒，480p/720p/1080p；1080p 最多一张图
`seedance-2`	文本、首尾帧、多模态参考	`model`, `prompt`	4–15 秒，最高 4K，可生成音频
`seedance-2-fast`	文本、首尾帧、多模态参考	`model`, `prompt`	4–15 秒，480p/720p，可生成音频
`seedance-2-mini`	文本、首尾帧、多模态参考	`model`, `prompt`	4–15 秒，480p/720p，没有 `generate_audio` 字段
`veo-3.1`	文本、首尾帧、参考图	`model`, `prompt`	没有 `duration` 字段；`quality` 可选 Quality/Fast/Lite；720p/1080p/4K
`seedance-2.5`	文本、首尾帧、更大多模态参考集	`model`, `prompt`	4–30 秒，480p/720p/1080p，音频和 `seed`
`kling-v3`	文本、首尾帧、多镜头、复用元素	`model`, `prompt`	3–15 秒，`std`（720p）或 `pro`（1080p），可选声音
`kling-v4`	文本、按时间顺序排列的画面帧、参考图 / 视频 / 声音、命名元素	`model`、`prompt`	3–30 秒，720p/1080p，始终生成音频
`kling-2.6-motion-control`	一张已上传角色图和一个动作视频	`model`, `images`, `reference_videos`	3–30 秒动作视频，720p/1080p，按秒计费
`kling-3-motion-control`	带方向和背景控制的动作迁移	`model`, `images`, `reference_videos`	3–30 秒动作视频，720p/1080p，按秒计费
`wan-3.0`	文字、首帧图、参考视频与参考音频	`model`、`prompt`	2–30 秒，720p/1080p
`wan-3.0-prime`	与 Wan 3.0 相同的输入，走更快的队列	`model`、`prompt`	2–30 秒，720p/1080p，价格与 Wan 3.0 相同
`happyhorse-1.0`	仅图生视频，最多九个源角度	`model`、`prompt`、`images`	3–15 秒，720p/1080p
`happyhorse-1.1`	与 1.0 相同的契约，每秒单价更低	`model`、`prompt`、`images`	3–15 秒，720p/1080p
`minimax-h3-max`	文生视频、首帧、首尾帧	`model`、`prompt`	最短 5 秒，480P/768P，支持 seed
`minimax-h3-max-turbo`	与 H3 Max 相同的契约	`model`、`prompt`	最短 5 秒，480P/768P，每秒单价减半

每个模型页会列出全部字段、默认值、枚举、组合限制、请求示例、响应和错误行为。

查询可用模型

GET /v1/media/models?media_type=video 无需鉴权。

curl "https://api.beatapi.io/v1/media/models?media_type=video"

{
  "data": {
    "object": "list",
    "data": [{
      "id": "minimax-h3",
      "object": "generation_model",
      "name": "MiniMax H3",
      "media_type": "video",
      "input_modes": ["text", "frames", "reference"]
    }]
  }
}

id 是稳定公开模型别名；input_modes 可能包含 text、image、frames 或 reference。内部供应商路由不属于公开契约。

通用创建契约

POST /v1/videos/tasks

请求头	类型	必填	规则
`Authorization`	string	是	`Bearer <BEATAPI_API_KEY>`
`Content-Type`	string	是	`application/json`
`Idempotency-Key`	string	否，建议使用	最长 255 字符；每个逻辑创建使用一个键

请求体必须且只能匹配一个模型参数结构；model 是判别字段，未知字段会被拒绝。

curl https://api.beatapi.io/v1/videos/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: video-seedance-2-5-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "雨夜市场中的电影感跟拍镜头。",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

成功请求返回 201 Created 和 data.id。每 5–10 秒轮询 GET /v1/tasks/{task_id}，成功结果位于 data.output.media[] 和 data.output.r2_url。相同幂等请求会返回已接受任务；同一键配不同请求体返回 409 idempotency_conflict。

通用错误

HTTP	常见错误码	客户端动作
`400`	`bad_request`	修正字段、取值、组合、数量或媒体 URL
`400`	`content_policy_violation`	修改提示词或素材，不要原样重发
`401`	`missing_api_key` / `invalid_api_key`	补上 Bearer API 密钥，或更换错误、过期、停用、额度用尽的密钥
`402`	`insufficient_credits`	充值后再创建任务
`403`	`forbidden`	密钥或账户无权执行，例如免费额度不能调用该模型
`409`	`idempotency_conflict`	仅用完全相同请求体复用该键
`429`	`rate_limit_exceeded`	遵守 `Retry-After`
`500`	`internal_error`	退避后重试一次
`503`	`processing_unavailable` / `processing_timeout` / `processing_failed` / `result_transfer_failed`	退避重试，未扣费

错误响应包含 error.code、英文的 error.message、error.retryable、error.request_id，429 时另带 error.retry_after_seconds。任务被接受后才失败的，查询依然返回 200，原因见 data.error_code；全部错误码与重试规则见错误码。模型页面是最终生产请求契约。