How it works
The pipeline, resource graph, async pattern, and how every concept connects.
Static Ads Lab turns brand data and a design template into a Meta-ready image ad through a single API call. This page is the mental model — read it before writing integration code.
The resource graph
flowchart LR
Brand --> Product
Product --> Variant[Product variant]
Variant --> Image
Product --> Audience
Brand --> ImageAd[Image ad]
Product --> ImageAd
Audience --> ImageAd
Template[Design template] --> ImageAd
ImageAd --> PNG[Meta-ready PNG]
ImageAd --> JSON[JSON tree, if editable]- Brands hold visual identity — name, logos, color palettes, fonts.
- Products belong to a brand. Each product can have multiple variants and audiences.
- Product variants are SKUs (sizes, colors, bundles) with their own images.
- Audiences are target personas tied to a product.
- Images are uploaded assets — product photos, brand logos, lifestyle imagery.
- Design templates are reusable ad layouts. They're independent of any brand and can be reused across unlimited generations.
- Image ads are the API output: a Meta-ready PNG, optionally with an editable JSON tree.
Generating an image ad
The core workflow is one API call:
POST /v1/image-ads
{
"design_template_id": "dt_...",
"brand_id": "brand_...",
"product_id": "prod_...",
"audience_id": "aud_..."
}The API takes the design template's layout, fills it with your brand's visual identity, selects appropriate product imagery, generates ad copy tailored to the audience, and renders a final PNG. The pipeline runs asynchronously — the API returns 202 Accepted with the resource in processing status, and you poll (or stream via SSE) until it reaches completed or failed.
Optional parameters:
| Parameter | What it does |
|---|---|
product_variant_id | Use a specific variant's images instead of default product images |
prompt | Guide creative direction with a text prompt |
editable | true returns an editable JSON tree alongside the PNG |
options.generate_ai_images | Whether AI imagery is used |
options.generate_copy | Whether AI ad copy is used |
node_overrides | Override specific elements (text, images) before generation |
See Image ads and Editable image ads for the full workflow.
Flat vs editable image ads
There are two SKUs:
| Type | SKU | Output | Best for |
|---|---|---|---|
| Flat | flat_image_ad | Meta-ready PNG | High-volume generation, batch workflows |
| Editable | editable_image_ad | PNG + JSON tree, mutable via PATCH | Custom editors, programmatic refinement, Figma sync |
Flat is the default. Set "editable": true to get an editable ad.
The async job pattern
Design templates and image ads are created asynchronously.
stateDiagram-v2
[*] --> processing: POST returns 202
processing --> completed: Pipeline finished
processing --> failed: Pipeline error
completed --> [*]
failed --> [*]When you submit a creation request, the API:
- Validates inputs (brand exists, product belongs to brand, template is ready, wallet has funds).
- Creates the resource with
status: "processing"and returns202 Accepted. - Queues the generation job.
- Processes the job — this is where the AI pipeline runs.
- Updates the resource to
completed(with results) orfailed(with an error).
Track progress via polling or SSE.
Status lifecycle
A resource starts in processing and ends in either completed or failed. There are no intermediate states. The progress field updates during processing with pipeline-stage information.
You're only billed for successful generations. If a job fails, your wallet is not deducted.