Creatives

/creatives/generate

Generates a creative from a brief — a still image, or a multi-slide carousel with type: carousel.

This is the other way to make a creative — /creatives/upload is the one where you supply the media.

It answers before the work is done. Composing a creative is an LLM pipeline that runs for minutes, far longer than a request should wait, so you get a generation to poll at /creatives/generations/{generation_id}. The creative_id is usable immediately: the creative exists from the start, empty, and fills in when the generation succeeds.

Naming product_ids builds the creative around those catalogue products, using their images and fields. Without them the composer works from the brief alone.

Generation consumes the workspace's credits, so this can fail on billing as well as on input.

Requires the creatives:write scope.

post/projects/{project_id}/creatives/generate

Request

  • Base URL: https://api.productbyte.com/v1
  • URL: https://api.productbyte.com/v1/projects/{project_id}/creatives/generate
  • Auth: HTTP bearer

Path parameters

project_idstring required

The project to create the creative in.

Request body

type'image' | 'carousel'

What to compose. carousel produces a multi-slide deck.

promptstring required

The brief, in your own words — what the creative is for, and any direction to follow. Up to 4000 characters.

namestring

What to call the creative. Worth sending: an upload takes its name from the filename, but a generated creative has nothing to take one from and is otherwise unnamed in ProductByte.

format'1:1' | '4:5' | '16:9' | '9:16' | '2:3' required

Aspect ratio to compose at.

language'en-GB' | 'en-US' | 'nl-NL' | 'fr-FR' | 'de-DE' | 'es-ES' | 'it-IT' | 'pt-PT' | 'pl-PL' | 'sv-SE' | 'da-DK' | 'fi-FI' | 'no-NO'

Language of the copy rendered into the creative. Defaults to the project’s.

product_idsstring[]

Catalogue products to build the creative around, from /products. Up to 10.

variant_countinteger

How many options to produce. Image only — a carousel composes one deck.

slide_countinteger

Slides in the deck, from 3 to 6. Carousel only; defaults to five.

Response

The generation was queued. Poll it to learn the outcome.

idstring required

Pass this to /creatives/generations/{generation_id} to follow it.

creative_idstring required

The creative being generated into. It exists from the moment the generation starts, empty until the first result lands, so you can reference it before the work finishes.

status'running' | 'succeeded' | 'failed' required

running until it settles. On succeeded, read the creative for its formats.

error_codestring

Why it failed. A stable code, never prose.

created_atstring date-time required

When the generation was started.

updated_atstring date-time required

When it last changed.

Changes

No recorded changes to this operation across all 2 revisions of this API.