电商产品广告的 Ecommerce Video API 接入指南

当你的产品需要从商品图片稳定生成广告视频，而不是做一次性创意 demo 时，ecommerce video API for product ads 这类工作流才真正有价值。API 应该接收素材、快速返回 task id、暴露任务状态、按 credits 计费，并交付你的系统可以存储或发布的托管 MP4。

• 当一组商品图和简短创意 brief 需要变成 paid social 或落地页视频时，使用 POST /v1/ecommerce-video/tasks。
• 商品图应该是公开 HTTPS URL；本地素材先通过 POST /v1/files 上传。
• 把视频生成当作异步任务：创建 task、轮询 GET /v1/tasks/{task_id}，需要时再加 webhook。
• 当前 launch 计费为 Ecommerce Video 1080p 每秒 15 credits，所以 15 秒广告会预留 225 credits。
• 不要把上游 provider id、临时 URL 或 provider-specific state 暴露给客户。

快速结论

当接入必须支撑真实商品运营时，选择 ecommerce video API for product ads：多张商品图、短视频时长、横竖方比例、账号 credits、并发、任务日志、webhook 和稳定输出 URL 都要一起工作。

不要只是因为“AI video 很新”就使用它。它适合产品经理或增长团队提出的可重复系统需求：

• 从 1 到 7 张商品图生成一条商品广告视频。
• 把每次广告请求绑定到账号、API key、request id 和 credit ledger。
• 在不改变客户侧契约的情况下生成 9:16、1:1 或 16:9 版本。
• 当活动素材失败时，让支持团队能查看同一条 task 记录。
• 返回托管 MP4，而不是让客户追踪 provider 文件。

这就是原始模型调用和工作流 API 的产品差别。

工作流形态

核心循环应该保持很小：

1. 上传或托管商品图片。
2. 创建 Ecommerce Video task。
3. 保存返回的 task_id 和 request_id。
4. 每 5-10 秒带 jitter 轮询 task，或接收 task.succeeded / task.failed webhook。
5. task 成功后读取 output.media[].url。
6. 从 task record 展示最终 usage 和错误，而不是从 provider log 里拼证据。

公开契约是工作流形态的：

export BEATAPI_API_KEY="sk_your_key"

curl https://api.beatapi.io/v1/ecommerce-video/tasks \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["https://media.beatapi.io/samples/smart-bottle.png"],
    "duration": 15,
    "prompt": "Fast product launch ad for paid social.",
    "aspect_ratio": "9:16",
    "language": "en"
  }'

创建成功会返回 201 和 queued task。15 秒 ecommerce ad 在 launch 价格下会预留并扣除 225 credits：

{
  "data": {
    "id": "task_p9Lm2",
    "object": "task",
    "workflow": "ecommerce-video",
    "status": "queued",
    "stage": "queued",
    "output": null,
    "usage": {
      "credits_reserved": 225,
      "credits_charged": 225,
      "billable_duration_seconds": 15,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_def456",
    "error_code": null,
    "error_message": null
  }
}

什么时候适合使用

当你的团队正在构建这些产品界面时，Ecommerce Video API 很适合：

如果你要直接实验模型行为、计费和客服不需要绑定到生成任务，或者用户更需要手动创作控制，那就更适合使用底层 video model API。

请求契约

BeatAPI 的 launch 请求保持紧凑：

• images 必填，传入 1 到 7 个公开 HTTPS 图片 URL。
• duration 必填，整数范围是 10 到 60 秒。
• prompt 可选，最多 2000 字符。
• aspect_ratio 可选，支持 16:9、9:16 和 1:1。
• language 可选，支持 en 或 zh。

这个窄契约是刻意设计的。商品广告系统经常失败，是因为把太多 provider-specific controls 泄露给了客户集成。稳定的 ecommerce video API 应该允许产品团队在同一个公开形态背后改进 routing、validation、retry 和 provider。

商品广告 prompt 结构

Prompt 应该偏运营，不要写成抽象诗句。一个有用的 prompt 会说明商品是什么、广告强调什么，以及输出给哪个渠道：

Create a 15-second vertical product ad for a smart insulated bottle.
Show the bottle in clean close-ups, then in an active commuter scene.
Emphasize cold retention, leak-proof carry, and a modern matte finish.
Use fast paid-social pacing, bright natural light, and concise on-screen benefit beats.
Avoid medical claims, fake discounts, and unreadable small text.

这个 prompt 仍然是素材契约的补充。图片负责商品身份，prompt 负责节奏、卖点和使用场景。

接入示例

假设一个电商平台希望每个卖家都能在商品详情页生成一条视频广告。

产品团队不应该围绕模型参数设计 UI，而应该围绕商品任务设计：

即使平台也使用 webhook，轮询仍然是 source of truth：

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

task 成功后，保存 output.media 里的托管 MP4 URL。不要让客户依赖临时 provider URL 或内部 job id。

上线检查清单

上线 ecommerce video API integration 前，检查这些运营细节：

• 图片 URL 是公开 HTTPS URL，并且 BeatAPI 可以访问。
• 卖家的本地上传会先通过 /v1/files。
• UI 在提交前把 duration 限制到 10-60 秒。
• 用户确认创意 brief 前已经选择 aspect ratio。
• 后端保存 task_id、request_id、workflow、status、usage 和 output URL。
• 轮询间隔为 5-10 秒并带 jitter，而不是紧密循环。
• Webhook handler 校验 BeatAPI signature，同时保留 polling fallback。
• 用户提示能区分 queued、processing、succeeded 和 failed。
• 批量创建任务前展示 credit estimate。
• 失败任务把 error_code 和 error_message 暴露给支持人员，而不是只写日志。

常见错误和修复方式

FAQ

What is an ecommerce video API for product ads?

它是一种 API 工作流，把商品图片、短创意 brief、duration 和输出格式变成异步商品广告视频任务。在 BeatAPI 中，launch endpoint 是 POST /v1/ecommerce-video/tasks。

应该传几张商品图？

传 1 到 7 个公开 HTTPS 图片 URL。优先使用清楚的商品图：正面、细节、包装，以及可用的生活方式场景图。

可以上传本地商品文件吗？

可以。先用 POST /v1/files 上传本地素材，再把返回的 HTTPS URL 传入 ecommerce video task。

商品广告视频最长可以多长？

Ecommerce Video API launch contract 接受 10 到 60 秒的 duration。Paid social 和 marketplace 场景通常更适合较短视频。

怎么估算 credits？

当前 Ecommerce Video 1080p 每秒 15 credits。10 秒任务是 150 credits，15 秒任务是 225 credits，30 秒任务是 450 credits。

应该用 polling 还是 webhooks？

先用 polling，因为更容易调试。每 5-10 秒带 jitter 调用 GET /v1/tasks/{task_id}。当你需要后端完成事件时再加 webhook，但 task endpoint 仍然是 source of truth。

应用应该保存什么输出？

保存 BeatAPI task id、request id、最终 status、usage object 和 output.media[].url。这个 media URL 是面向客户的 MP4 输出。

这只适合 paid social ads 吗？

不是。产品团队也可以用于 marketplace listing video、landing-page hero video、offer test 和 creative variants。同一个 task contract 可以覆盖这些界面。

什么时候不适合这个工作流？

当你需要直接实验底层模型、逐帧编辑或完整手动创作套件时，不适合。Ecommerce Video API 面向的是可重复的商品广告自动化。