> 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.

# BeatAPI 视频 API

> 对比 BeatAPI 视频生成模型、输入模式、时长、分辨率、音频控制和模型专属请求契约。

# 视频 API

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

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

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

## 查询可用模型

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

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

```json
{
  "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` 是判别字段，未知字段会被拒绝。

```bash
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`；全部错误码与重试规则见[错误码](/errors)。模型页面是最终生产请求契约。