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.

POST

/v1/brands/{brandId}/creatives/render

Authorization

bearerAuth

headerAuthorizationBearer <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.

Path Parameters

brandId*integer

The brand the request acts on. Every brand-scoped resource lives under its brand.

Header Parameters

Request Body

application/json

body

roundSize?integer

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.

Range1 <= value <= 60

html?string

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.

Length1 <= length <= 200000

templateId?integer

Render a saved template from list-creative-templates instead of html.

Range0 < value <= 9007199254740991

values?

With templateId: the text for each {{slot}} of the template, by slot name. Values go in as plain text.

aspectRatio*string

1:1 renders at 1080x1080, 4:5 at 1080x1350, 9:16 at 1080x1920.

Value in"1:1""4:5""9:16"

name?string

Name for the stored creative.

Length1 <= length <= 120

source?string

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.

Value in"references""meta-winners""own-winners""ideas"

policyRisk?string

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.

Length1 <= length <= 140

Response Body

Render creative

application/json

response

creatives*array<>

total*integer

Range-9007199254740991 <= value <= 9007199254740991

page*integer

Range-9007199254740991 <= value <= 9007199254740991

pages*integer

Range-9007199254740991 <= value <= 9007199254740991

selection*boolean

nextCursor*null

failures*array<>

The render, when it could not be made, with why.

blocked*array<string>

Requests the page made that were blocked, so what they would have loaded is missing from the image.

modelImages?array<>

Images shown to you after this call

Itemsitems <= 12

[key: string]?unknown

curl -X POST "https://example.com/v1/brands/0/creatives/render" \  -H "Authorization: Bearer koast_sk_..." \  -H "Content-Type: application/json" \  -d '{    "aspectRatio": "1:1"  }'

{  "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    }  ],  "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    }  ],  "blocked": [    "string"  ],  "modelImages": [    {      "url": "string",      "label": "string",      "property1": null,      "property2": null    }  ],  "property1": null,  "property2": null}

Required scope: write. CLI: koast render-creative, see Creatives commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.