Audio to Video API：构建异步音乐视频工作流

audio to video API 不应该被设计成一次阻塞式渲染请求，而应该被当作异步产品工作流：后端先准备可访问的音频和图片 URL，创建 music-video 任务，保存 task id，通过轮询或 webhook 观察状态，任务成功后再保存托管 MP4 URL。

• 用户上传本地音频、图片或字幕文件时，先用 POST /v1/files。
• 使用 POST /v1/music-video/tasks 创建生成任务。
• 每 5-10 秒带抖动轮询 GET /v1/tasks/{task_id}；后端需要完成事件时再接入 /v1/webhooks。
• 当 status 变为 succeeded 后，从 output.media[].url 读取最终视频。
• 把上游 provider 细节封装在 BeatAPI task contract 后面，让产品只暴露一个稳定集成面。

快速答案

可靠的实现路径是：

1. 将输入音频和视觉参考图验证或上传为公开 HTTPS URL。
2. 调用 POST /v1/music-video/tasks，传入这些 URL、prompt、画幅、分辨率，以及可选字幕或 lip-sync 设置。
3. 在数据库中持久化返回的 BeatAPI task id。
4. 轮询 GET /v1/tasks/{task_id}，直到任务进入 succeeded 或 failed。
5. 当后端需要完成事件时，注册 webhook，而不是只依赖前端轮询。
6. 保存 output.media[].url、usage 和 request_id，用于交付和客服排查。

这个形态比长时间挂起一个 HTTP 请求更稳。audio-to-video 任务可能经历排队、生成、storyboard、editing 和 composing 阶段。即使用户关闭浏览器标签页，产品仍然应该可以恢复和观察任务。

工作流结构

audio-to-video API 要负责的不只是生成本身，还要提供文件、状态、输出和恢复能力的契约。

准备输入

BeatAPI music-video 任务需要一个音频 URL 和一到七个图片 URL。这些 URL 应该是公网可访问的 HTTPS 地址。如果用户在你的应用中上传文件，先通过 POST /v1/files 上传，再把返回的 URL 传给任务。

调用 API 前建议做这些预检查：

• 音频：公开 HTTPS mp3、wav、aac 或 m4a。
• 音频时长：10-180 秒。
• 文件大小：已验证上传素材不超过 50 MB。
• 图片：公开 HTTPS png、jpg、jpeg 或 webp。
• 图片数量：1-7 张。
• 图片宽高比：大致在 1:4 到 4:1 之间。
• Prompt：可选，最长 3000 字符。
• srt_url：可选；启用字幕时应指向 .srt 文件。
• duration：仅作为无法检测音频时长时的兜底，不用于覆盖已检测时长。

提前验证可以让用户更快修复输入，也能减少昂贵的失败任务。BeatAPI 在任务创建时仍会验证 URL 形态、文件元数据、文本长度、枚举值和音频时长。

创建任务

先从最小请求开始，只在产品场景需要时再增加控制项。

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。你的数据库应该同时记录 BeatAPI task id、user id、内部 job id、当前状态、request id，以及存在时的最终输出 URL。不要把 provider job id 当作产品中唯一持久引用。

轮询与 Webhook

BeatAPI 任务可能经过 queued、processing、storyboard_ready、requires_action、editing、composing、succeeded 和 failed。

每 5-10 秒带抖动轮询任务端点：

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

成功任务会在 output.media 暴露最终 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"
        }
      ]
    },
    "usage": {
      "credits_reserved": 150,
      "credits_charged": 150,
      "credits_settled": 150,
      "credits_refunded": 0
    },
    "request_id": "req_abc123"
  }
}

接入 webhook 后，把 task.succeeded 和 task.failed 当作后端更新事件。用 BeatAPI webhook headers 验签；如果 handler 需要最新事实，再回查一次任务端点。

完整示例

假设一个创作者应用允许音乐人上传 30 秒 preview 和一张艺人图，目标是生成竖版社交短片。

实现形态：

1. 浏览器把 MP3 和图片上传到你的后端。
2. 后端分别通过 POST /v1/files 上传本地文件。
3. 后端用返回 URL 创建 BeatAPI music-video 任务。
4. 后端保存 { user_id, internal_job_id, beatapi_task_id, status, request_id }。
5. 前端轮询你的后端，而不是直接轮询 BeatAPI。
6. 后端轮询 BeatAPI 或接收 webhook。
7. 任务成功后，后端保存 output.media[0].url 并向用户展示 MP4。
8. 任务失败后，后端基于 error_code、error_message 和 usage/refund 证据展示可操作状态。

可复用任务 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"
}

如果是歌词视频产品，保持同一套 audio-to-video API 流程，只调整工作流控制项：

{
  "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"
}

常见错误与修复

上线检查清单

在向客户开放 audio-to-video API 工作流前，确认：

• API key 只保存在服务端。
• 本地音频、图片和 SRT 文件在创建任务前已上传。
• 素材 URL 是公开 HTTPS URL。
• 创建任务前已验证音频时长和文件大小。
• 数据库把 BeatAPI task id 和内部 job id 绑定保存。
• 前端通过你的后端轮询。
• 后端轮询带 jitter，并在终态停止。
• Webhook handler 会验签且具备幂等性。
• 最终 MP4 URL、request id、usage 和错误信息被保存，方便支持排查。
• UI 对输入验证失败和任务终态失败都给出清晰重试路径。

FAQ

什么是 audio to video API？

audio to video API 接收音频素材和视觉方向，通过异步任务返回生成视频。在 BeatAPI 中，music-video 工作流包含 audio_url、images、prompt 控制、任务状态、可选 webhook 和托管 MP4 输出。

创建任务前必须上传文件吗？

只有当用户文件是本地文件或公网不可访问时才需要。BeatAPI 任务需要公开 HTTPS 输入 URL。使用 POST /v1/files 可以把本地图片、音频或字幕变成任务可用 URL。

应该轮询还是使用 webhook？

先用轮询，因为简单且可恢复。当后端需要完成事件时再加入 webhook。即使使用 webhook，GET /v1/tasks/{task_id} 仍然是状态事实来源。

可以创建歌词视频吗？

可以。你的工作流需要提供音频、视觉参考和字幕控制。使用 add_subtitle、subtitle_color 和 srt_url 生成带字幕的输出。

可以使用 lip sync 吗？

可以，当任务需要表演型视频且提供了所需参考控制时使用。产品场景需要时启用 lip_sync 并提供 lip_ref_url。

任务创建后应该保存什么？

保存内部 job id、BeatAPI task id、status、request id、usage 字段、最终 output.media URL，以及任何终态 error 字段。这是支持排查和重试的最小上下文。

任务失败时会怎样？

当没有生成可用输出时，任务端点会返回终态 failed 和错误信息。产品应该保留 task record，并基于错误展示重试或支持路径。

下一步应该从哪里开始集成？

如果你的产品需要带任务状态、webhook、credits 和托管 MP4 输出的 audio-to-video 生成，请从 Music Video API 页面开始。