Design templates

A design template is a reusable ad layout stored as a JSON tree. Use templates when you want to inspect, edit, or reuse a layout structure independently of image ad generation. Image ads are created directly from reference_ad_url — design templates are optional.

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 completed template has a populated current_json_tree you can PATCH, version, or use as a reference when building custom editors. Templates created from a reference image must reach status: "completed" before you read or edit the tree.

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. Poll until status: "completed" before reading current_json_tree.
• 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 when building custom template workflows.

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.