> 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. # 音乐视频 > 使用图片、音频和创意控制项创建音乐视频工作流任务。 `POST https://api.beatapi.io/v1/music-video/tasks` 使用图片、音频和创意控制项创建音乐视频工作流任务。 ## 鉴权 `Authorization`   `string`   **必填** 在 `Authorization` 请求头中以 Bearer 令牌发送服务端 API 密钥，可在[控制台](https://beatapi.io/dashboard)创建。 ``` Authorization: Bearer ``` 永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 `Content-Type: application/json`。建议为每个逻辑创建请求设置唯一的 `Idempotency-Key`，只有完全相同的请求体才能安全复用原键。 ## 请求体 字段名、类型和枚举值保留英文原样，用途和限制用中文说明。 本地素材无法通过公网 HTTPS URL 访问时，请先[上传输入文件](/quick-guide#upload-an-input-file)，再使用返回的 `data.url`。 `mv_tier`   `enum`   **选填** 音乐视频套餐。省略时使用标准版（`standard`），高级版请求必须填写 `premium`。 **取值与默认值:** 可选值 `standard`、`premium`；默认值 `standard` --- `images`   `string[]`   **选填** 按当前模型或工作流要求排序的公网 HTTPS 图片 URL 列表。 **取值与默认值:** 0–7 项 --- `audio_url`   `string`   **必填** 公网可访问的 HTTPS 音频 URL。本地文件请先通过 `POST /v1/files` 上传。 **取值与默认值:** 格式 `uri` --- `prompt`   `string`   **选填** 描述生成、编辑或分析目标的提示词。 **取值与默认值:** 最多 3000 字符 --- `language`   `enum`   **选填** 对话、旁白或歌词使用的语言。中英文混合时建议显式指定。 **取值与默认值:** 可选值 `en`、`zh` --- `quality`   `enum`   **选填** 生成质量或速度档位。请使用当前模型允许的英文枚举值。 **取值与默认值:** 可选值 `standard`、`high`；默认值 `standard` --- `style`   `string`   **选填** 简洁的视觉风格说明，例如电影感、动漫、纪录片或时尚编辑风格。 **取值与默认值:** 最多 200 字符 --- `aspect_ratio`   `enum`   **选填** 输出素材的宽高比。 **取值与默认值:** 可选值 `1:1`、`16:9`、`9:16`、`4:3`、`3:4` --- `resolution`   `enum`   **选填** 输出素材的分辨率或质量档位。 **取值与默认值:** 可选值 `540p`、`720p`、`1080p`；默认值 `720p` --- `lip_sync`   `boolean`   **选填** 是否生成口型同步表演。启用后需按套餐规则传入人脸参考图。 **取值与默认值:** 默认值按生成方式为 `false` --- `lip_ref_url`   `string`   **选填** 用于口型同步的公网 HTTPS 正面近景人脸图片 URL。 **取值与默认值:** 格式 `uri` --- `add_subtitle`   `boolean`   **选填** 是否将生成或传入的字幕烧录到最终视频中。 **取值与默认值:** 默认值按生成方式为 `false` --- `subtitle_color`   `string`   **选填** 烧录字幕时使用的颜色。 --- `srt_url`   `string`   **选填** 可选的公网 HTTPS `.srt` 字幕文件 URL。本地字幕请先上传。 **取值与默认值:** 格式 `uri` --- `duration`   `integer`   **选填** 请求的输出时长，单位为秒。 **取值与默认值:** 取值范围 10–300 --- `compose_mode`   `enum`   **选填** 音乐视频的合成方式。`auto` 自动合成，`manual` 会在 `requires_action` 等待审核。 **取值与默认值:** 可选值 `auto`、`manual`；默认值 `auto` --- `mv_mode`   `enum`   **选填** `premium` 高级版音乐视频的具体模式。不同模式对 `images` 和 `lip_ref_urls` 有不同要求。 **取值与默认值:** 可选值 `sing`、`sing_perform`、`dance`、`perform` --- `lip_ref_urls`   `string[]`   **选填** `premium` 高级版演唱模式使用的一张或两张公网 HTTPS 正面近景人脸图片。 **取值与默认值:** 1–2 项 ## 响应 成功请求返回 HTTP `201`，响应体如下。 ```json { "data": { "id": "task_8K2qA", "object": "task", "task_kind": "workflow", "capability_id": "music-video", "capability_version": 1, "workflow": "music-video", "status": "queued", "stage": "queued", "storyboard": { "shots": [] }, "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 1.5, "credits_charged": 1.5, "billable_duration_seconds": 15, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_abc123", "error_code": null, "error_message": null } } ``` ## 人工审核流程 `compose_mode` 为 `manual` 时，请轮询到任务进入 `requires_action`，再使用返回的分镜和镜头 ID 完成后续处理。 1. 提示词或 `premium` 高级版参考图需要调整时，调用 `POST /v1/music-video/tasks/{task_id}/shots/{shot_id}/edit` 编辑分镜。 2. 需要托管预览时，调用 `GET /v1/music-video/tasks/{task_id}/shots/{shot_id}/media` 获取镜头媒体。 3. 选定镜头准备完成后，调用 `POST /v1/music-video/tasks/{task_id}/compose` 合成音乐视频。 编辑或合成后继续轮询同一个父任务。`auto` 自动合成不需要调用这些接口。 ## 下一步 保存接受响应中的 `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` | 幂等键在 24 小时内已用于其他请求体或路径，或使用该键的首个请求仍在处理中（`idempotency_conflict`）。只对完全相同的请求复用原键。 | | `429` | 请求过于频繁（`rate_limit_exceeded`，含免费模型限额）。按 `Retry-After`（也在 `error.retry_after_seconds`）等待后重试。 | | `500` | 内部异常（`internal_error`），可以重试；持续出现时请保留 `request_id` 联系支持。 | | `503` | 请求未能完成（`processing_unavailable`、`processing_timeout`、`processing_failed` 或 `result_transfer_failed`），未扣费，可退避重试；503 不带 `Retry-After` 和 `retry_after_seconds`。BeatAPI 不返回 502 或 504。实时接口在本部署未启用时为 `realtime_disabled`（不可重试），容量暂时不足时为 `realtime_capacity_unavailable`（可重试）。 |