审批与交付 · API 与 webhook

通过 API，从你自己的系统创建横幅。

API 是从你的代码请求横幅的方式。可以在不消耗积分的情况下测试，并在任务完成时收到 webhook（自动签名的通知）。

POST /api/v1/bannersbm_test_…

Idempotency-Key: 7c1e9a52

{
  "prompt": "Tu mañana, bien tostada",
  "sizes": ["300x250", "728x90"],
  "locales": ["es-CR", "en-US"]
}

→ 202 { "id": "job_test_…", "status": "queued" }

测试密钥不消耗积分。

从你的代码创建横幅

包含提示词、尺寸和语言的请求会返回一个任务，它会在所有尺寸中生成一个概念；你可以查询直到完成。

签名通知

测试安全

测试密钥总是返回示例横幅，不使用 AI，也不消耗积分。如果用相同的幂等密钥重试请求，不会重复扣费。

使用方法

从密钥到横幅，三个步骤。

创建密钥
测试密钥（bm_test_…）用于开始，或生产密钥（bm_live_…）。完整密钥只显示一次。
发出请求
发送提示词、尺寸和语言，并附带一个幂等性标头。
等待通知
查询任务，或在横幅准备好时接收 webhook。

关键信息

费用、限制和要求。

可用于: 团队、代理机构和企业版方案。
密钥: 生产密钥和测试密钥；只保存指纹，不保存值。
Webhook events: All 13 documented events are emitted today, including banner.generated, generation.failed, review.approved, and export.ready.
Signature: Standard Webhooks: webhook-id, webhook-timestamp, and webhook-signature headers (HMAC SHA-256, with a 5-minute tolerance) on every notice.

分步学习如何使用

通过 API 创建横幅教程 用 webhook 接收通知教程

使用此功能的横幅示例

Nébula · 金融

Marejada · 旅游

Pulso · 运动

关于「API 与 webhook」的问题

哪些方案包含 API？

团队（每月 $99）、代理机构（每月 $299）和企业版（每月起 $1,500）。Starter 不包含 API 和 webhook。

测试时会消耗积分吗？

使用测试密钥时不会：它们始终返回示例横幅，不使用 AI，也不消耗积分。生产密钥使用与应用相同的积分。

如果我重试请求会怎样？

使用 Idempotency-Key 标头时，重复同一请求会返回之前的结果，而不是再次扣费。

How do I know a webhook is from BannerMotion?

Each notice carries the webhook-id, webhook-timestamp, and webhook-signature headers of the Standard Webhooks standard: an HMAC SHA-256 signature you verify with your webhook secret. The SDKs ship the verification ready to use.

Are there SDKs?

There are TypeScript and Python clients, not published yet [date to be confirmed]; ask for them at soporte@bannermotion.com. For any other language, use a client generated from the OpenAPI 3.1 specification.

将 BannerMotion 连接到你的平台。

用一个真实的活动试试看。

创建我的第一个活动联系销售