How it works

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[Layered JSON tree]

• 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 plus the editable JSON tree it was rendered from.

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, rebuilds it as editable layers, and renders a final PNG. The ad keeps the reference ad's format. Generation takes up to about 20 minutes and runs asynchronously — the API returns 202 Accepted with the resource in processing status, and you poll until it reaches completed or failed.

Optional parameters:

See Image ads and Editable image ads for the full workflow.

Every ad is editable

Every image ad (SKU editable_image_ad) is a Meta-ready PNG plus a layered JSON tree. It costs $2.00, including 1 generated image asset, plus $0.50 for each additional generated image asset; only successful generations count.

Change a finished ad three ways, and the image re-renders in the background each time:

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:

1. Validates inputs (brand exists, product belongs to brand, reference ad URL is reachable, wallet has funds).
2. Creates the resource with status: "processing" and returns 202 Accepted.
3. Queues the generation job.
4. Processes the job — this is where the AI pipeline runs.
5. Updates the resource to completed (with results) or failed (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.

Next