POST/api/v1/banners

Create a banner

Creates a concept in all the sizes and locales you ask for. Responds 202 with a job; check its status or wait for the webhook.

A single request creates a concept: one banner idea delivered complete in all the sizes and locales you send. You do not need one request per size or per locale: there is a single charge, per concept, and it grows with the sizes and locales you send.

The response is immediate: a job that the AI finishes later. Check its status at statusUrl or wait for the banner.generated webhook. Requires the generate permission.

What is charged

Each request charges 1 concept, according to the sizes and locales you send. With Sonnet 5.5 it is 8 + 1.5 × sizes + 0.5 × (locales − 1) credits, with no steps: 1 size in 1 locale costs 10 credits; 4 sizes in 1 locale, 14 credits; up to 12 sizes, 26 credits. If you ask for 4 sizes in 2 locales, you get 8 pieces and pay 15 credits.

The API uses your workspace's default model (Settings), and the price depends on it: a concept with 4 sizes and 1 locale costs 7 credits with Haiku 5.5, 14 with Sonnet 5.5, 28 with Opus 5.5 and 70 with Fable 5.1. Test keys do not charge. If the job fails, the credits are returned. To know the cost before asking, use "Estimate credits" (link at the end).

Headers

HeaderRequirementDescription

Authorization

Required

Bearer bm_live_… (live) or bm_test_… (testing).

Content-Type

Required

application/json

Idempotency-Key

Optional

Up to 200 characters. The same key with the same body returns the same response; with a different body, a 422 error.

Body (JSON, maximum 256 KB)

FieldRequirementDescription

promptstring

Required

Campaign description: what you sell, to whom and with what tone. From 1 to 2000 characters.

sizesstring[]

Optional

Sizes in the format 300x250. From 1 to 12. The concept comes out in all of them. If omitted, 300x250, 728x90, 160x600 and 320x50 are used (or those of campaignId, if you send it; or those of the reference frames).

localesstring[]

Optional

Locales in the format es-CR or en-US. From 1 to 10. The first one is the base language. The concept comes out in all of them; each locale after the first adds 0.5 credits with Sonnet 5.5. If omitted, es-CR is used (or those of campaignId, if you send it). Options: es-CR, es-MX, es-ES, en-US, en-GB, pt-BR, fr-CA, fr-FR, de-DE, it-IT.

styleIdstring

Optional

Id of a visual style. If it does not exist, the 400 error lists the valid ids.

variantinteger

Optional

Alternative number, from 0 (default) to 50. With 1 or more, the AI looks for an idea different from the obvious one.

campaignIdstring

Optional

Existing campaign in your workspace. If omitted, a new campaign is created using the start of the prompt as its name.

referenceobject

Optional

An already designed composition, for example Figma frames. Explained below.

Unknown fields are not accepted: they respond 400.

Reference composition

If you already have the design, send it in reference: source (figma, image or other) and frames, up to 12, one per size. Each frame carries its size, its background and its layers (up to 60): a box in pixels (x, y, w, h), the stacking order z, the kind (text, image, vector or shape), the role in the hierarchy (headline, cta, logo…), the literal text with its style, and the fills.

The reference texts are the banner's texts, as they are. Images and logos are mandatory: upload them first to the library (link at the end) and send their assetId.
Positions and hierarchy are respected per size. Sizes without a frame are adapted from the closest one.
It does not count toward the 2000 characters of prompt; that is why the body accepts up to 256 KB.

Responses

HTTPcodeDescription

202

—

Job created: one concept with all the requested sizes and locales. Follow its status at statusUrl.

400

bad_request

The JSON or a field is not valid, or an assetId in the reference does not exist in your workspace.

401

unauthorized

The key is missing, invalid or was revoked.

402

insufficient_credits

You do not have enough credits.

403

forbidden

The key does not have permission to generate, or the Owner's email is not verified (email_unverified).

404

not_found

The campaignId does not exist in your workspace.

409

conflict

There is a request with that Idempotency-Key still in progress.

413

payload_too_large

The body exceeds 256 KB.

422

idempotency_mismatch

That Idempotency-Key was already used with another request.

429

rate_limited

You exceeded the limit per minute, or your plan already has the maximum number of jobs at once. Check Retry-After.

Limit: 60 requests per minute per key. [PLACEHOLDER: confirm the value in production]. If you exceed it, the response includes Retry-After.

With a test key

With bm_test_… the response is already resolved (status: "succeeded"), includes test: true, the creativeId and a bannerUrl, and is the same for the same request. Those ids can only be read with test keys and do not exist in your workspace.

Job statusCheck a generation job or follow it live with SSE events.Get a bannerReads the spec, the current version, the pieces and the texts of a concept, or lists the concepts in your workspace.Webhook eventsThe 13 events, all emitted today: when they fire, what the data field carries and an example of each.File libraryUpload images, logos and fonts to the workspace library, list them and remove them.Estimate creditsFind out how many credits an operation would cost and what your balance is, without reserving anything.

이 페이지가 도움이 되었나요?