Crear mi primera campaña
Menú de la documentación
POST/api/v1/banners

Crear un banner

Crea un concepto en todos los tamaños e idiomas que pidas. Responde 202 con un trabajo; consulta su estado o espera el webhook.

Una sola petición crea un concepto: una idea de banner que se entrega completa en todos los sizes y locales que envíes. No hace falta una petición por tamaño ni por idioma: el cobro es uno solo, por concepto, y crece con los sizes y los locales que envíes.

La respuesta es inmediata: un trabajo que la IA termina después. Consulta su estado en statusUrl o espera el webhook banner.generated. Requiere el permiso generate.

Qué se cobra

Cada petición cobra 1 concepto, según los sizes y los locales que envíes. Con Sonnet 5.5 es 8 + 1.5 × tamaños + 0.5 × (idiomas − 1) créditos, sin escalones: 1 tamaño en 1 idioma cuesta 10 créditos; 4 tamaños en 1 idioma, 14 créditos; hasta 12 tamaños, 26 créditos. Si pides 4 tamaños en 2 idiomas, obtienes 8 piezas y pagas 15 créditos.

La API usa el modelo por defecto de tu workspace (Ajustes) y el precio depende de él: un concepto de 4 tamaños y 1 idioma cuesta 7 créditos con Haiku 5.5, 14 con Sonnet 5.5, 28 con Opus 5.5 y 70 con Fable 5.1. Las claves de pruebas no cobran. Si el trabajo falla, los créditos se devuelven. Para saber el costo antes de pedir, usa «Estimar créditos» (enlace al final).

Encabezados

EncabezadoRequisitoDescripción
Authorization
Obligatorio
Bearer bm_live_… (real) o bm_test_… (pruebas).
Content-Type
Obligatorio
application/json
Idempotency-Key
Opcional
Hasta 200 caracteres. La misma clave con el mismo cuerpo devuelve la misma respuesta; con otro cuerpo, un error 422.

Cuerpo (JSON, máximo 256 KB)

CampoRequisitoDescripción
promptstring
Obligatorio
Descripción de la campaña: qué vendes, a quién y con qué tono. De 1 a 2000 caracteres.
sizesstring[]
Opcional
Tamaños con el formato 300x250. De 1 a 12. El concepto sale en todos. Si falta, se usan 300x250, 728x90, 160x600 y 320x50 (o los de campaignId, si lo envías; o los de los frames de reference).
localesstring[]
Opcional
Idiomas con el formato es-CR o en-US. De 1 a 10. El primero es el idioma base. El concepto sale en todos; cada idioma además del primero suma 0,5 créditos con Sonnet 5.5. Si falta, se usa es-CR (o los de campaignId, si lo envías). Opciones: es-CR, es-MX, es-ES, en-US, en-GB, pt-BR, fr-CA, fr-FR, de-DE, it-IT.
styleIdstring
Opcional
Id de un estilo visual. Si no existe, el error 400 lista los ids válidos.
variantinteger
Opcional
Número de alternativa, de 0 (por defecto) a 50. Con 1 o más, la IA busca una idea distinta de la obvia.
campaignIdstring
Opcional
Campaña existente de tu workspace. Si falta, se crea una nueva con el inicio del prompt como nombre.
referenceobject
Opcional
Composición ya diseñada, por ejemplo los frames de Figma. Se explica abajo.

No se aceptan campos desconocidos: responden 400.

Composición de referencia

Si ya tienes el diseño, envíalo en reference: source (figma, image u other) y frames, hasta 12, uno por tamaño. Cada frame trae su size, su background y sus layers (hasta 60): una caja en píxeles (x, y, w, h), el orden z, el tipo (text, image, vector o shape), el papel en la jerarquía (headline, cta, logo…), el texto literal con su estilo y los rellenos.

  • Los textos de la referencia son los del banner, tal cual. Las imágenes y los logos son obligatorios: súbelos antes a la biblioteca (enlace al final) y envía su assetId.
  • Se respetan las posiciones y la jerarquía por tamaño. Los tamaños sin frame se adaptan desde el más parecido.
  • No cuenta para los 2000 caracteres de prompt; por eso el cuerpo admite hasta 256 KB.

Respuestas

HTTPcodeDescripción
202
—
Trabajo creado: un concepto con todos los tamaños e idiomas pedidos. Sigue su estado en statusUrl.
400
bad_request
El JSON o algún campo no es válido, o un assetId de la referencia no existe en tu workspace.
401
unauthorized
Falta la clave, es inválida o fue revocada.
402
insufficient_credits
No tienes créditos suficientes.
403
forbidden
La clave no tiene permiso para generar, o el correo del Propietario no está verificado (email_unverified).
404
not_found
El campaignId no existe en tu workspace.
409
conflict
Hay una petición con esa Idempotency-Key aún en proceso.
413
payload_too_large
El cuerpo supera los 256 KB.
422
idempotency_mismatch
Esa Idempotency-Key ya se usó con otra petición.
429
rate_limited
Superaste el límite por minuto o tu plan ya tiene el máximo de trabajos a la vez. Mira Retry-After.

Límite: 60 peticiones por minuto por clave. [PLACEHOLDER: confirmar el valor en producción]. Si lo superas, la respuesta trae Retry-After.

Con una clave de pruebas

Con bm_test_… la respuesta ya viene resuelta (status: "succeeded"), trae test: true, el creativeId y un bannerUrl, y es la misma para el mismo pedido. Esos ids solo se leen con claves de prueba y no existen en tu workspace.

Estado de un trabajoConsulta un trabajo de generación o síguelo en vivo con eventos SSE.Obtener un bannerLee el spec, la versión actual, las piezas y los textos de un concepto, o lista los conceptos de tu workspace.Eventos de webhooksLos 13 eventos, todos emitidos hoy: cuándo salen, qué trae el campo data y un ejemplo de cada uno.
¿Te sirvió esta página?