How it works
The pipeline, resource graph, async pattern, and how every concept connects.
Static Ads Lab turns a reference ad, brand data, product assets, and an audience 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
ReferenceAd[Reference ad URL] --> 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.
- Reference ad URLs are inspiration images: competitor ads, mockups, or concept images that define the composition and visual strategy.
- 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
{
"reference_ad_url": "https://cdn.example.com/reference-ad.png",
"brand_id": "brand_...",
"product_id": "prod_...",
"audience_id": "aud_..."
}The API analyzes the reference ad, snaps it to the nearest supported Meta image ad format (1:1, 4:5, or 9:16), adapts the concept to your brand/product/audience, and renders a final PNG. The pipeline runs asynchronously — the API returns 202 Accepted with the resource in processing status, and you poll 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 |
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, reference ad URL is reachable, 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.
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.