Render creative
Turn an html ad layout into an image for the active brand.
Tool name: render-creative.
Turn an html ad layout into an image for the active brand. It stays out of the user's creative library until saved with save-generated-creatives or used in an ad. Use it when exact words, prices, numbers, brand fonts or the logo matter, or to fill a saved template. Write a full html page with inline css at the size of the aspect ratio; load fonts from Google Fonts and images only from Koast storage urls (library creatives, view-images copies, generate-creatives assets). Page scripts do not run. Returns a creativeId ready for add-ads, distribute-creative or swap-creatives, and shows you the image.
When to use
Compose an ad in html and css: real brand fonts, exact copy and prices, a logo or product photo placed exactly, or many versions of one layout through a saved template (templateId and values). It writes to the library, so it is unavailable in plan mode. Takes up to a minute, longer the first time.
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. |
html | string | No | A complete html page for the ad, laid out at the size of the aspect ratio. Page scripts do not run. Only inline data: urls, Koast storage urls and Google Fonts load; every other request is blocked. At most 200000 characters. |
templateId | integer | No | Render a saved template from list-creative-templates instead of html. |
values | object | No | With templateId: the text for each {{slot}} of the template, by slot name. Values go in as plain text. |
aspectRatio | string | Yes | 1:1 renders at 1080x1080, 4:5 at 1080x1350, 9:16 at 1080x1920. One of 1:1, 4:5, 9:16. |
name | string | No | Name for the stored creative. At most 120 characters. |
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. |
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. |
Output
| Field | Type | Required | Description |
|---|---|---|---|
creatives | object[] | Yes | |
total | integer | Yes | |
page | integer | Yes | |
pages | integer | Yes | |
selection | boolean | Yes | |
nextCursor | null | Yes | |
failures | object[] | Yes | The render, when it could not be made, with why. |
blocked | string[] | Yes | Requests the page made that were blocked, so what they would have loaded is missing from the image. |
modelImages | object[] | No | Images shown to you after this call. At most 12 items. |
REST equivalent
POST /v1/brands/{brandId}/creatives/render, Render creative. CLI: koast render-creative.