Design templates

A design template is a reusable ad layout the API fills with your brand, product, and audience content. Templates are independent of any brand and can be used across unlimited image ad generations.

Mental model

Templates capture the structure of an ad — what goes where, what's a headline, what's a product shot, what's a CTA. They don't carry brand-specific styling; that's applied at generation time.

You can create a template two ways:

1. Use a public template from our library — browse pre-built templates in the dashboard, ready to use immediately. No API call needed.
2. Upload your own — submit a reference ad image (a screenshot of an ad you like). The API runs an AI pipeline that detects layout, identifies text and image regions, and assembles a structured template.

ID prefix: dt_.

Fields

Lifecycle

stateDiagram-v2
  [*] --> processing: POST /v1/design-templates
  processing --> completed
  processing --> failed
  completed --> [*]
  failed --> [*]

A template must reach status: "completed" before it can be used to generate image ads.

Endpoints

Common patterns

Convert a reference image into a template

const response = await fetch("https://api.staticadslab.com/v1/design-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference_image_url: "https://example.com/ad-screenshot.png",
  }),
});
const { data } = await response.json();
console.log(data.id, data.status); // dt_..., "processing"

Then poll until completed:

async function waitForTemplate(id) {
  while (true) {
    const r = await fetch(
      `https://api.staticadslab.com/v1/design-templates/${id}`,
      { headers: { "X-API-Key": "YOUR_API_KEY" } },
    );
    const { data } = await r.json();
    if (data.status === "completed") return data;
    if (data.status === "failed") throw new Error("Template generation failed");
    await new Promise((res) => setTimeout(res, 2000));
  }
}

Pick a completed public template

const response = await fetch(
  "https://api.staticadslab.com/v1/design-templates?status=completed",
  { headers: { "X-API-Key": "YOUR_API_KEY" } },
);
const { data } = await response.json();
const template = data[0];

Pitfalls

• Templates created via reference image take a few seconds to a minute to process. Don't pass a processing template to POST /v1/image-ads — the request will be rejected.
• Templates are workspace-scoped. You can list and use templates created in your organization (and public ones); you can't list other organizations' templates.
• The current_json_tree is the source of truth for the layout. You can PATCH it, but you usually don't need to — the AI generation pipeline tunes layout per ad.

Related

• JSON trees
• Image ads
• Async jobs

Prompt for your agent

Read https://www.staticadslab.com/docs/resources/design-templates.mdx and create a function that takes a reference image URL, creates a design template, polls until completed, and returns the template ID. Throw on failure.