Generate creatives
Generates the ads in ads in parallel, each from its own prompt, optionally guided by reference images (library creativeIds or https urls, in order) or by editing an existing library image (editCreativeId), and stores each image for the brand; a generated image stays out of the creative library list until it is saved with save-generated-creatives or used in an ad. Returns the stored creatives, each with the ad it came from, plus failures for images that could not be made. Synchronous; allow up to five minutes.
bearerAuthAuthorizationBearer <token>An organization API key (koast_sk_…) with the API surface enabled, or an OAuth access token issued by Koast (koast_at_…) whose audience covers this API. REST access requires an active Agency plan.
brandId*integerThe brand the request acts on. Every brand-scoped resource lives under its brand.
Idempotency-Key?stringRetrying with the same key within 24 hours returns the first response without acting again.
length <= 255application/json- body
roundSize?integerWrite 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.
1 <= value <= 60roundGroups?array<>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.
1 <= items <= 4ads*array<>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.
1 <= items <= 40use?stringad (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.
"ad""asset"Generate creatives
application/json- response
creatives*array<>assets?array<>With use: asset, the objects made, instead of library creatives.
modelImages?array<>Images shown to you after this call
items <= 12total*integer-9007199254740991 <= value <= 9007199254740991page*integer-9007199254740991 <= value <= 9007199254740991pages*integer-9007199254740991 <= value <= 9007199254740991selection*booleannextCursor*nullfailures*array<>Images that could not be made, with why.
[key: string]?unknowncurl -X POST "https://example.com/v1/brands/0/creatives/generate" \ -H "Authorization: Bearer koast_sk_..." \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "prompt": "string" } ] }'{ "creatives": [ { "creativeId": -9007199254740991, "name": "string", "kind": "image", "url": "string", "previewUrl": "string", "previewable": true, "width": 0, "height": 0, "aspectRatio": "string", "durationSeconds": null, "sizeBytes": 0, "isImported": true, "ready": true, "createdAt": "string", "variation": -9007199254740991, "ad": -9007199254740991, "policyRisk": "string", "property1": null, "property2": null } ], "assets": [ { "assetId": -9007199254740991, "url": "string", "width": 0, "height": 0, "aspectRatio": "1:1", "variation": -9007199254740991, "ad": -9007199254740991, "property1": null, "property2": null } ], "modelImages": [ { "url": "string", "label": "string", "property1": null, "property2": null } ], "total": -9007199254740991, "page": -9007199254740991, "pages": -9007199254740991, "selection": true, "nextCursor": null, "failures": [ { "aspectRatio": "1:1", "variation": -9007199254740991, "ad": -9007199254740991, "refused": true, "reason": "string", "property1": null, "property2": null } ], "property1": null, "property2": null}Required scope: write. CLI: koast generate-creatives, see Creatives commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.
Upload creative
Stores an image in the brand's creative library and returns its creativeId. Pass exactly one of imageUrl (a public https URL that Koast downloads and re-hosts) or fileData (base64 bytes, with contentType and fileName). Uploading bytes the brand already holds returns the existing creative with reused: true. Images only; no ad is created or changed.
Render creative
Renders an html ad, or a saved creative template with its slot values, at 1080 pixels wide in the aspect ratio given, and stores the image for the brand; it stays out of the creative library list until it is saved with save-generated-creatives or used in an ad. Page scripts are off and only data: urls, Koast storage and Google Fonts load; other requests are listed in blocked. Synchronous; allow up to three minutes.