音乐视频

POST https://api.beatapi.io/v1/music-video/tasks

使用图片、音频和创意控制项创建音乐视频工作流任务。

鉴权

Authorization   string   必填

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

Authorization: Bearer <BEATAPI_API_KEY>

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

请求体

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

本地素材无法通过公网 HTTPS URL 访问时，请先上传输入文件，再使用返回的 data.url。

mv_tier   enum<string>   选填

音乐视频套餐。省略时使用标准版（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<string>   选填

对话、旁白或歌词使用的语言。中英文混合时建议显式指定。

取值与默认值: 可选值 en、zh

quality   enum<string>   选填

生成质量或速度档位。请使用当前模型允许的英文枚举值。

取值与默认值: 可选值 standard、high；默认值 standard

style   string   选填

简洁的视觉风格说明，例如电影感、动漫、纪录片或时尚编辑风格。

取值与默认值: 最多 200 字符

aspect_ratio   enum<string>   选填

输出素材的宽高比。

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

resolution   enum<string>   选填

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

取值与默认值: 可选值 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<string>   选填

音乐视频的合成方式。auto 自动合成，manual 会在 requires_action 等待审核。

取值与默认值: 可选值 auto、manual；默认值 auto

mv_mode   enum<string>   选填

premium 高级版音乐视频的具体模式。不同模式对 images 和 lip_ref_urls 有不同要求。

取值与默认值: 可选值 sing、sing_perform、dance、perform

lip_ref_urls   string[]   选填

premium 高级版演唱模式使用的一张或两张公网 HTTPS 正面近景人脸图片。

取值与默认值: 1–2 项

响应

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

1
{
2
  "data": {
3
    "id": "task_8K2qA",
4
    "object": "task",
5
    "task_kind": "workflow",
6
    "capability_id": "music-video",
7
    "capability_version": 1,
8
    "workflow": "music-video",
9
    "status": "queued",
10
    "stage": "queued",
11
    "storyboard": {
12
      "shots": []
13
    },
14
    "created_at": 1782210000,
15
    "updated_at": 1782210000,
16
    "completed_at": null,
17
    "output": null,
18
    "usage": {
19
      "credits_reserved": 1.5,
20
      "credits_charged": 1.5,
21
      "billable_duration_seconds": 15,
22
      "credits_settled": 0,
23
      "credits_refunded": 0
24
    },
25
    "request_id": "req_abc123",
26
    "error_code": null,
27
    "error_message": null
28
  }
29
}

人工审核流程

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 读取托管结果。

错误