Generate creatives

Tool name: generate-creatives.

Make new ad images, or edit one, for the active brand. They stay out of the user's creative library until saved with save-generated-creatives or used in an ad. Every ad of a round goes in one call, as ads, and they are made at the same time. You write each ad's whole image prompt. Pass reference images (library creatives or https urls) in order and call them Image 1, Image 2 in the prompt; never describe a product you were given a photo of. To show the brand's logo set logo: true and say where it goes; never type the brand name as a logo. Put every on-image word in quotes and add "no other words"; keep headlines to six words; never invent reviews, ratings, prices or claims. To change an image, pass editCreativeId and say exactly what to change and what to keep. Returns creativeIds ready for add-ads, distribute-creative or swap-creatives. You see the images after this call.

When to use

Make ad images: from a brief, from a product photo, by remixing the user's own winning ad, or in the style of an Ad Library reference (search-ad-library). Also edit, fix text on, or resize an existing image (editCreativeId). Generation takes up to a few minutes. It writes to the library, so it is unavailable in plan mode and refused to a read-only credential.

Access

Property	Value
Required scope	`write`
Publishes	No
Read-only	No
Destructive	No
Idempotent	No
Open world	Yes

Input

Field	Type	Required	Description
`roundSize`	`integer`	No	Write this first, before every other field. How many ads you are making in this round across all your calls; send the same number on every call of the round. The user sees that many placeholders as soon as it is written. It does not change what this call makes. Minimum 1, maximum 60.
`roundGroups`	`object[]`	No	Write this second, right after roundSize, when the ads of the round have sources: each source and how many ads of the round it has, in the order you will write them, such as [{"source":"references","ads":10},{"source":"own-winners","ads":10}]. The user sees one row per source as soon as it is written. It does not change what is made. At least 1 item, at most 4 items.
`roundGroups[].source`	`string`	Yes	One of `references`, `meta-winners`, `own-winners`, `ideas`.
`roundGroups[].ads`	`integer`	Yes	Minimum 1, maximum 40.
`ads`	`object[]`	Yes	The ads to make, each with its own prompt and references. Put every ad of a round in this one call: they are all made at the same time. One ad, an edit or a resize is a list of one. At most 40 ads and 40 images per call. At least 1 item, at most 40 items.
`ads[].prompt`	`string`	Yes	The full image prompt, written by you. Refer to reference images by position: "Image 1", "Image 2". Put every word that must appear on the image in quotes. At most 8000 characters.
`ads[].references`	`object[]`	No	Reference images in order: the first is "Image 1". Product photos, logos, people, a winning ad to remix, a style example. At most 8 items.
`ads[].references[].creativeId`	`integer`	No	An image already in the brand's creative library: a chat attachment, a gallery pick, or an earlier generation.
`ads[].references[].imageUrl`	`string (uri)`	No	A public https image, such as an `imageUrls` entry from search-ad-library. At most 2000 characters.
`ads[].editCreativeId`	`integer`	No	Edit or reframe this library image instead of starting from nothing. It becomes Image 1 and `references` follow it. Say in the prompt what to change and what to keep.
`ads[].aspectRatios`	`string[]`	No	1:1 and 4:5 for feed, 9:16 for stories and reels. Defaults to 4:5. One of `1:1`, `4:5`, `9:16`. At least 1 item, at most 3 items.
`ads[].variations`	`integer`	No	Images per aspect ratio, each from the same prompt. Defaults to 1. At most 8 images per call. Minimum 1, maximum 4.
`ads[].logo`	`boolean`	No	true to show the brand's saved logo on this ad: the real logo file is attached after your references, as the next image. Say in the prompt where it goes and how big ("the logo, small, bottom centre"). Never type the brand name as a logo.
`ads[].name`	`string`	No	This ad's name: the concept it shows. The user sees it on the ad's tile, and it names the stored creatives. At most 120 characters.
`ads[].people`	`boolean`	No	true when the ad shows people: faces, hands, bodies, a person holding the product. Its images then go mostly to the model whose skin looks most real.
`ads[].source`	`string`	No	Where this ad's idea came from: references (images the user attached or references they picked), meta-winners (other advertisers' winning ads from the Meta Ad Library), own-winners (the brand's own best ads from its ad account), ideas (none of these: the brief and the website). The user sees the round grouped by it. One of `references`, `meta-winners`, `own-winners`, `ideas`.
`ads[].policyRisk`	`string`	No	Set this only when the ad could be rejected: why, in a few plain words the user understands ("promises a guaranteed result", "won't run on your agency ad account: crypto"). The ad is still made exactly as asked, and the user sees this as a warning on the ad. Leave it out when there is no real risk. At most 140 characters.
`use`	`string`	No	ad (the default): finished ads, stored in the creative library. asset: objects or elements to place inside render-creative html, on a transparent background when possible; they are stored with the brand assets, not in the library, and each returns an `assetId` and url. One of `ad`, `asset`.

Output

Field	Type	Required	Description
`creatives`	`object[]`	Yes
`assets`	`object[]`	No	With use: asset, the objects made, instead of library creatives.
`modelImages`	`object[]`	No	Images shown to you after this call. At most 12 items.
`total`	`integer`	Yes
`page`	`integer`	Yes
`pages`	`integer`	Yes
`selection`	`boolean`	Yes
`nextCursor`	`null`	Yes
`failures`	`object[]`	Yes	Images that could not be made, with why.

REST equivalent

POST /v1/brands/{brandId}/creatives/generate, Generate creatives. CLI: koast generate-creatives.