如何通过 API 从音频生成音乐视频

要通过 API 从音频生成音乐视频，不要把它当成一个同步生成请求，而应该把它设计成异步工作流：先让音频和参考图可访问，再创建 music-video task，随后轮询或监听 webhook，最后保存 task 返回的托管 MP4 URL。

• 当用户上传的是本地音频、图片或字幕时，先用 POST /v1/files 转成可复用 HTTPS URL。
• 用 POST /v1/music-video/tasks 创建生成任务。
• 每 5-10 秒带一点 jitter 轮询 GET /v1/tasks/{task_id}，或用 /v1/webhooks 接收完成事件。
• 当 status 变成 succeeded 后，从 output.media[].url 读取最终 MP4。
• 把上游 provider job 留在后端内部，对产品和客户暴露 BeatAPI task id。

快速答案

最短的稳定路径是：

1. 把输入音频和参考图上传或托管为公开 HTTPS URL。
2. 将这些 URL 连同视觉 prompt 和输出参数发送到 POST /v1/music-video/tasks。
3. 在你的数据库中保存返回的 task id。
4. 轮询 GET /v1/tasks/{task_id}，直到任务进入终态。
5. 成功后持久化 output.media 里的托管 MP4 URL。
6. 失败时，把 error_code、error_message 和 usage/refund 证据展示给支持流程。

这比让一个 HTTP 请求一直等待生成完成更可靠。音乐视频生成是长任务，可能经历 storyboard、edit 或 compose 阶段，而且用户关闭浏览器后任务仍然需要可观察。

工作流模型

通过 API 从音频生成音乐视频，不只是“发送 MP3，拿回视频”。一个可用于生产的 music video generation API 需要处理五件事：

准备音频和图片

BeatAPI music-video task 需要一个公开 HTTPS 音频 URL，以及 1-7 个公开 HTTPS 图片 URL。如果用户在你的应用里上传本地文件，先用 POST /v1/files 上传，再把返回的 url 用在 task 请求里。

上线前建议在 UI 里做这些预校验：

• 音频：公开 HTTPS mp3、wav、aac 或 m4a。
• 音频时长：10-180 秒。
• 音频大小：50 MB 或更小。
• 图片：公开 HTTPS png、jpg、jpeg 或 webp。
• 图片数量：1-7 张。
• 单张图片大小：50 MB 或更小。
• 图片比例：大致在 1:4 到 4:1 之间。
• Prompt：可选，最多 3000 字符。
• srt_url：可选，但应指向 .srt 文件。
• duration：只在 BeatAPI 无法检测音频时长时作为计费 fallback，不应拿来覆盖已检测时长。

这些预校验能更快给用户反馈，也能保护 credits。BeatAPI 在创建 task 时仍会校验 URL 形态、枚举值、文本长度、音频时长和文件元数据。

创建任务

创建任务的请求可以很小。先从 audio、images、prompt 和输出控制开始，只有当产品场景需要时再加入 lip-sync 或字幕字段。

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 '{
    "audio_url": "https://media.beatapi.io/samples/neon-singer-preview.mp3",
    "images": ["https://media.beatapi.io/samples/neon-singer.png"],
    "prompt": "Neon rooftop performance with cinematic light trails, slow dolly movement, energetic chorus cuts.",
    "language": "en",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "quality": "standard",
    "lip_sync": false,
    "add_subtitle": false,
    "compose_mode": "auto"
  }'

返回 task id 后要立刻保存。你的产品不应该依赖浏览器标签页、队列 worker 内存，或上游 provider job id 作为唯一引用。

轮询或使用 Webhook

BeatAPI task 会经历 queued、processing、storyboard_ready、requires_action、editing、composing、succeeded、failed 等状态。

每 5-10 秒带一点 jitter 轮询：

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

成功响应会在 output.media 中暴露最终媒体：

{
  "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"
        }
      ]
    },
    "usage": {
      "credits_reserved": 150,
      "credits_charged": 150,
      "credits_settled": 150,
      "credits_refunded": 0
    },
    "request_id": "req_abc123"
  }
}

如果你的产品有后端 job runner，可以为 task.succeeded 和 task.failed 添加 webhook。即使使用 webhook，也要保留轮询作为恢复路径，因为 webhook 投递失败不应该让用户看不到真实 task 状态。

接入示例

假设一个创作者平台让音乐人上传 30 秒试听音频和一张艺人图片。产品目标是生成竖版社交短片，而不是完整剪辑器。

推荐实现形态：

1. 浏览器把 MP3 和图片上传到你的后端。
2. 后端把每个本地文件发送到 POST /v1/files。
3. 后端用返回的 URL 创建 BeatAPI music-video task。
4. 后端保存 { user_id, beatapi_task_id, status, request_id }。
5. 前端轮询你的后端，而不是直接轮询 BeatAPI。
6. 后端轮询 BeatAPI 或接收 webhook。
7. 当 status 为 succeeded 时，后端保存 output.media[0].url。
8. UI 展示 MP4；如果失败，则展示 retry/support 信息。

可复用的 task payload：

{
  "audio_url": "https://media.beatapi.io/inputs/file_song_preview.mp3",
  "images": ["https://media.beatapi.io/inputs/file_artist_portrait.png"],
  "prompt": "Create a vertical artist promo video for a synth-pop chorus. Use neon reflections, close-up performance energy, quick cuts on beat, and no visible text.",
  "language": "en",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "quality": "standard",
  "lip_sync": false,
  "add_subtitle": false,
  "compose_mode": "auto"
}

如果你做的是歌词视频产品，只改 workflow 控制：

{
  "audio_url": "https://media.beatapi.io/inputs/file_song_preview.mp3",
  "images": ["https://media.beatapi.io/inputs/file_cover_art.png"],
  "prompt": "Create a clean lyric visualizer with soft camera movement, rhythmic background motion, and safe empty space for subtitles.",
  "language": "en",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "quality": "standard",
  "add_subtitle": true,
  "subtitle_color": "#FFFFFF",
  "srt_url": "https://media.beatapi.io/inputs/file_lyrics.srt",
  "compose_mode": "auto"
}

常见错误和修复

上线检查清单

上线“通过 API 从音频生成音乐视频”功能前，确认你的集成已经具备：

• API key 只保存在服务端。
• 本地音频、图片和字幕的文件上传路径。
• 对文件类型、大小、时长、图片数量的 UI 预校验。
• 数据库记录 BeatAPI task id、workflow、status、request id、usage 和 output URL。
• 带 5-10 秒 cadence 和 jitter 的轮询。
• 后端 webhook 验证。
• 用户可见的 failed 状态，能给出 retry 指引但不暴露 provider 内部细节。
• 通过你的账户 UI 展示 credit balance 和 usage。
• 支持视图可查看 task id、request id、error_code、error_message 和 usage。

FAQ

只用音频文件能生成音乐视频吗？

BeatAPI music-video task 需要一个音频 URL 和至少一个图片 URL。图片会锚定视觉方向，让工作流有明确参考来生成视频。

每个任务都必须先上传文件吗？

不需要。如果你已经有满足要求的公开 HTTPS URL，可以直接使用。只有当产品从本地上传或私有素材开始时，才需要用 /v1/files 转成可复用公开 URL。

前端应该直接调用 BeatAPI 吗？

通常不应该。API key 应该留在后端。让前端通过你的应用上传文件、创建任务，并轮询你自己的 task record。

什么时候用 webhook，而不是轮询？

最简单的集成可以只用轮询。当后端需要自动接收完成通知时再加 webhook。即使启用 webhook，也要把 task endpoint 保留为恢复状态的 source of truth。

如果任务失败会怎样？

任务会返回 failed，并带有 error_code、error_message、usage 和 request_id 等证据。你可以根据这些信息决定展示重试、退款还是支持路径。

音乐视频任务如何消耗 credits？

BeatAPI 根据检测到的或 fallback 的 billable duration 以及输出控制计费。公开 launch 价格包括 540p、720p、1080p、high quality 和 lip-sync add-on。你的产品最好把计费展示绑定到 task record，方便支持团队解释最终结果。

最终输出是可下载 MP4 吗？

成功任务会在 output.media 返回托管 MP4。你的产品可以存储和播放这个 URL，而不是把 provider-specific 输出链接暴露给客户。