AI 音乐视频 API vs 视频生成 API

如果你的产品只需要调用模型生成视频片段，可以用 video generation API。如果你的产品需要稳定地把歌曲、参考图、prompt、字幕或口型同步变成可交付的音乐视频，就应该用 AI Music Video API，也就是面向产品工作流的 AI 音乐视频 API。

• 原始 video generation API 适合灵活的 prompt-to-video 或 image-to-video 生成。
• AI Music Video API 更适合音频、歌词、参考图、时序、交付和计费需要一起流转的产品场景。
• 对产品团队来说，真正难的通常不是再换一个模型，而是补齐 workflow API 层。
• 更稳的架构是把上游生成能力藏在内部，对客户暴露稳定的任务契约。
• 在 Beat API 里，这个契约围绕 /v1/music-video/tasks、/v1/tasks/{task_id}、/v1/files 和 /v1/webhooks 展开。

结论

如果你只是做内部 demo，原始视频生成 API 通常够用。你发送 prompt 或图片，等待生成，然后下载结果。比如 OpenAI video generation guide 这类接口会把视频创建、编辑、扩展和素材下载能力直接暴露给开发者。

如果你在做一个每天给用户使用的产品，困难会转移到模型调用之上。音乐应用、创作者工具、营销批量生成系统或自动化后端都需要接收真实素材、校验输入、快速返回 task id、让进度可观察、交付稳定 MP4 URL、扣费或退款，并让客服和运营团队能看懂任务记录。

这就是 video generation API 和 AI Music Video API 的差别。前者是生成原语，后者是产品工作流。

两类 API 各自负责什么

有些供应商 API 本身也有任务和 webhook 能力。Replicate predictions 可以发送 prediction 事件 webhook，Vidu One Click AI-MV 有 callback、edit、compose 概念，HeyGen lipsync jobs 也支持轮询或 callback URL。这些能力有价值，但它们仍然是供应商契约。产品团队需要的是一个能够承受供应商变化的稳定公开契约。

选择矩阵

适合选择原始 video generation API 的情况：

• 你的产品还在测试多种视觉风格和模型能力。
• 用户可以接受供应商参数和偶发的手工修复。
• 你暂时不需要音乐视频专用输入契约。
• 计费、退款和客服支持可以放在生成请求之外。
• 你还没有准备好把稳定输出交给另一个系统消费。

适合选择 AI Music Video API 的情况：

• 客户会提交歌曲、试听音频、歌词或 SRT，并期待成片。
• 你的应用需要为社媒、活动或广告输出竖版、方形、横版视频。
• 你需要 task id、轮询、webhook 和托管 MP4 输出。
• 你希望上游供应商细节不要进入公开 API。
• 你需要把 credits、并发、usage 记录、失败原因和重试都绑定到同一条任务。
• 你以后可能更换或增加供应商，但不想让客户改集成代码。

实用判断很简单：如果客户问的是“能不能生成一个片段”，video generation API 可能够用。如果客户问的是“我的产品能不能稳定地把歌曲变成视频”，你需要 AI Music Video API。

产品团队真正需要什么

1. 面向工作流的输入契约

音乐视频请求不只是文字 prompt。真实请求通常包含：

• images：一到七个公开 HTTPS 参考图。
• audio_url：公开 HTTPS MP3、WAV、AAC 或 M4A 文件。
• prompt：视觉方向、表演概念、场景说明或镜头 brief。
• language：例如 en 或 zh 的语言提示。
• style、aspect_ratio、resolution、quality：输出规划控制。
• lip_sync、lip_ref_url、add_subtitle、subtitle_color、srt_url：用于表演视频、歌词视频或字幕视频的可选控制。
• compose_mode：自动合成或人工检查 storyboard。

Beat API 用 POST /v1/music-video/tasks 保持公开入口简单，再让 task 承载这些细节。

2. 生成前的素材处理

很多产品问题不是模型生成失败，而是模型运行之前就已经出错。用户拖入本地 MP3、私有图片 URL、过大的参考图，或者后缀不对的 SRT 文件。原始模型 API 可能很晚才拒绝，或者返回供应商自己的错误。

产品 API 应该提前校验：

• Beat API task 输入必须是公开 HTTPS URL。
• 本地图片、音频或字幕可以先通过 /v1/files 变成可复用 HTTPS 素材。
• 当前 launch 输入素材大小上限是 50 MB。
• 上传音频会在进入 workflow 前做时长检查。
• Music Video 音频建议在 10 到 180 秒之间。

这些校验不是装饰。它们保护生成成本、用户体验和支持效率。

3. 客户可以依赖的异步任务状态

视频生成是长任务。API 不应该让客户一直挂着一个 HTTP 请求等 MP4。它应该快速返回 task id，并让任务可查询。

Beat API 的公开循环是：

1. 用 POST /v1/music-video/tasks 创建任务。
2. 每 5-10 秒带一点 jitter 轮询 GET /v1/tasks/{task_id}。
3. 当 status 变成 succeeded 或 failed 时停止。
4. 成功后读取 output.media[].url。
5. 如果不想只靠轮询，再用 /v1/webhooks。

即使启用了 webhook，task endpoint 仍然是 source of truth。

4. 属于你产品的 Webhook，而不是供应商格式

供应商 callback 对你的后端很有用，但不应该意外变成客户面对的 webhook 契约。

Beat API 使用面向客户的 webhook header：

• x-beatapi-event
• x-beatapi-timestamp
• x-beatapi-signature

客户可以用自己的 Beat API webhook secret 验证事件，不需要理解上游供应商 callback 格式。Beat API 也可以独立重试投递，而不改变 task 状态。如果 webhook 失败，客户仍然可以轮询任务。

5. 不依赖供应商临时链接的输出交付

产品团队不应该只把临时供应商 URL 返回给客户。客户集成需要稳定媒体 URL，才能存储、渲染和审计。

Beat API 成功任务会返回托管 MP4：

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "workflow": "music-video",
    "status": "succeeded",
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_8K2qA/0.mp4",
          "mime_type": "video/mp4"
        }
      ]
    }
  }
}

用户看到的是 Beat API task 和 Beat API media URL。Provider id、provider account、上游 signed URL 和内部 capacity 细节都留在产品边界之后。

6. 绑定任务生命周期的计费

音乐视频价格应该在用户批量提交之前就能解释清楚。Beat API 的公开客户费率绑定时长和输出控制：

• 540p standard：4 credits/s。
• 720p standard：5 credits/s。
• 1080p standard：6 credits/s。
• lip-sync add-on：+2 credits/s。
• 720p high：16 credits/s。
• 1080p high：18 credits/s。

重点不只是数字，而是 credits 绑定 task 记录。这样失败、退款和客服判断之后都可以解释。

7. 进入严肃工作流后的 storyboard 和 edit 控制

很多视频产品一开始只需要“生成一个最终 MP4”。但音乐视频产品最终会需要更多控制：预览镜头、编辑某个镜头、获取 shot media，再把选中的 shot compose 成最终视频。

这就是 workflow API 比 model API 更有价值的地方。模型可以生成片段，workflow 可以保留 shot id、编辑历史、输出 URL、usage 记录和最终合成关系。

接入示例

假设一个创作者平台希望音乐人上传 30 秒试听音频后自动生成推广短片。

产品团队不想暴露供应商参数，只想要一个后端集成：

export BEATAPI_API_KEY="sk_your_key"

curl https://api.beatapi.io/v1/music-video/tasks \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["https://media.beatapi.io/samples/neon-singer.png"],
    "audio_url": "https://media.beatapi.io/samples/neon-singer-preview.mp3",
    "prompt": "Neon rooftop performance with metro cutaways and cinematic light trails.",
    "language": "en",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "quality": "standard",
    "compose_mode": "auto"
  }'

客户后端拿到 task id，把它存到自己的 campaign 记录里，然后轮询：

curl https://api.beatapi.io/v1/tasks/task_8K2qA \
  -H "Authorization: Bearer $BEATAPI_API_KEY"

任务成功后，应用保存 output.media[0].url，并在创作者后台展示 MP4。如果任务失败，应用从同一条 task 记录读取 error_code、error_message 和 usage。

这就是产品价值。应用不需要理解上游 callback、signed URL、provider job id 或 provider account capacity。

迁移路径

如果你已经在用原始 video generation API，不需要一次性推倒重来。可以一层一层迁移。

1. 把当前 provider 集成先保留在内部。
2. 为用户定义一套公开 task shape。
3. 暴露状态前先统一状态名称。
4. 把最终输出存到你自己的媒体层。
5. 先跑通 polling，再增加客户 webhook。
6. 把 credits、refunds、errors 绑定到 task 记录。
7. 最后再增加 storyboard、shot edit 或 compose 控制。

常见错误是太早暴露 provider 字段。一旦客户依赖 provider job id 或 provider webhook payload，每次更换供应商都会变成公开 API 迁移。

常见失败模式

FAQ

AI Music Video API 只是视频模型的一层封装吗？

不是。它内部可以使用一个或多个视频供应商，但公开价值是 workflow contract：音频和视觉输入、异步状态、托管输出、webhook、credits 和支持证据。

什么时候应该用原始 video generation API？

当团队需要最大化模型控制、视觉实验或直接使用供应商原生能力时，可以用原始 video generation API。它适合原型和模型原生创作工具。

什么时候应该用 AI Music Video API？

当产品任务是“把这首歌或试听音频变成可重复交付的音乐视频”时，就应该用 AI Music Video API。这需要音频校验、参考图、时序控制、task state、输出托管和客户安全交付。

Beat API 会暴露 provider task id 吗？

不会。公开响应使用 Beat API task id 和 workflow name。Provider id、provider account、上游 capacity 和 signed upstream output URL 都是内部细节。

用了 webhook 之后还需要 polling 吗？

需要保留。Webhook 是可选完成通知。GET /v1/tasks/{task_id} 仍然是 source of truth，尤其在客户 webhook endpoint 失败或延迟时。

最小接入路径是什么？

创建 API key；如果本地素材需要托管，先通过 /v1/files 上传；创建 music-video task；轮询任务端点；成功后读取 output.media[].url。

产品团队应该怎么理解价格？

把计费绑定到公开 task 生命周期。Beat API 根据音乐视频时长和输出控制收取客户 credits，并在 task usage object 里保留 reserved、settled、refunded 和 charged credits。

首次接入必须用 storyboard edit 吗？

不需要。先从自动合成和最终托管 MP4 开始。等产品需要人工检查或更细创意控制时，再增加 storyboard review、shot media、shot edit 和 compose。

可以把 Beat API 接进现有创作者应用吗？

可以。最干净的接入点是你的服务端。API key 留在服务端，由后端替用户创建任务，并把 Beat API task id 存到你自己的项目或 campaign 记录里。

开发者应该从哪里开始？

先看 AI Music Video API 页面，再用开发者文档确认具体 /v1/* 请求和响应契约。