Ad Delayer

Ad Delayer — Flat Ads Back Into Editable Layers

Take a finished ad — a JPEG or PNG with everything baked into one image — and get it back as editable layers. Bria's Ad Delayer reads the creative, separates it into background, imagery, logo, headline, body copy, and CTA, and returns each layer as its own asset plus a manifest describing where it sits, how big it is, and how its text is styled. Commercially safe, royalty-free, production-ready.

The everyday problem it solves: the ad shipped, the design file is gone, and someone needs a new size, a new price, or a translated headline.

When to Use This Skill

Use this skill when the user wants to:

• Turn a flat ad into layers — "turn this ad into layers", "delayer this", "de-layer this creative", "image to layers"
• Recover a lost design file — "I lost the PSD", "we don't have the source file", "recover an editable version"
• Make a finished ad editable — "make this ad editable", "I need to change the headline on this banner", "swap the price in this creative"
• Pull the pieces out of a creative — "extract the layers", "get the logo and copy out of this ad separately", "split this banner into its elements"
• Rebuild an ad for resizing or localisation — "I need this ad in other sizes", "translate the copy on this ad", "rebuild it so we can restyle it"
• Read an ad's structure — "what elements is this ad made of?", "give me the text, fonts, and positions in this creative"
• Batch a folder of finished ads — "delayer all the ads in this folder"

When NOT to Use This Skill

• "Just remove the background" / "I need a cutout" → use the remove-background skill. That is one transparent PNG of the foreground subject. This skill is the opposite job: it takes a whole ad apart into many layers, keeping text as text and reporting where each piece sits. If the ask is a single subject on transparency, it is not delayering.
• Cutting one object out for compositing → remove-background (whole subject) or bria-ai (erase_from_image for one object)
• Generating or editing an image — new visuals, restyling, inpainting, expanding → bria-ai
• Resize, crop, watermark, format conversion on a file you already have → image-utils
• Building a fresh ad from scratch (no source creative to take apart) → bria-ai

This skill does one thing: take a finished ad image apart into editable layers.

Setup — Authentication

Before making any API call, you need a valid Bria access token.

Step 1: Check for existing credentials

if [ -f ~/.bria/credentials ]; then
  BRIA_ACCESS_TOKEN=$(grep '^access_token=' "$HOME/.bria/credentials" | cut -d= -f2-)
  BRIA_API_KEY=$(grep '^api_token=' "$HOME/.bria/credentials" | cut -d= -f2-)
fi
if [ -z "$BRIA_ACCESS_TOKEN" ]; then
  echo "NO_CREDENTIALS"
elif [ -n "$BRIA_API_KEY" ]; then
  echo "READY"
else
  echo "CREDENTIALS_FOUND"
fi

If the output is READY, skip straight to making API calls — no introspection needed. If the output is CREDENTIALS_FOUND, skip to Step 3. If the output is NO_CREDENTIALS, proceed to Step 2.

Step 2: Authenticate via device authorization

Start the device authorization flow:

2a. Request a device code:

DEVICE_RESPONSE=$(curl -s -X POST "https://engine.prod.bria-api.com/v2/auth/device/authorize" \
  -H "Content-Type: application/json")
echo "$DEVICE_RESPONSE"

Parse the response fields:

• device_code — used to poll for the token (keep this, don't show to user)
• user_code — the code the user must enter (e.g. BRIA-XXXX)
• interval — seconds between poll attempts

2b. Show the user a single sign-in link. Tell them exactly this — nothing more:

Connect your Bria account: Click here to sign in Your code is {user_code} — it's already filled in.

Do NOT show two links. Do NOT show the raw URL separately. Do NOT use verification_uri from the API response. Keep it to one clickable link.

2c. Poll for the token. After showing the user the code, immediately start polling. Try up to 60 times with the given interval (default 5 seconds):

for i in $(seq 1 60); do
  TOKEN_RESPONSE=$(curl -s -X POST "https://engine.prod.bria-api.com/v2/auth/token" \
    -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
    -d "device_code=$DEVICE_CODE")
  ACCESS_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | sed -n 's/.*"access_token" *: *"\([^"]*\)".*/\1/p')
  if [ -n "$ACCESS_TOKEN" ]; then
    BRIA_ACCESS_TOKEN="$ACCESS_TOKEN"
    REFRESH_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | sed -n 's/.*"refresh_token" *: *"\([^"]*\)".*/\1/p')
    mkdir -p ~/.bria
    printf 'access_token=%s\nrefresh_token=%s\n' "$BRIA_ACCESS_TOKEN" "$REFRESH_TOKEN" > "$HOME/.bria/credentials"
    echo "AUTHENTICATED"
    break
  fi
  sleep 5
done

If the output contains AUTHENTICATED, proceed to Step 3. Otherwise the code expired — start over from Step 2a.

Do not proceed with any API call until authentication is confirmed.

Step 3: Verify billing status and resolve API key

Introspect the bearer token to check billing status and obtain the real API key for Bria API calls:

INTROSPECT=$(curl -s -X POST "https://engine.prod.bria-api.com/v2/auth/token/introspect" \
  -d "token=$BRIA_ACCESS_TOKEN")
BILLING_STATUS=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"billing_status" *: *"\([^"]*\)".*/\1/p')
if [ "$BILLING_STATUS" = "blocked" ]; then
  BILLING_MSG=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"billing_message" *: *"\([^"]*\)".*/\1/p')
  echo "BILLING_ERROR: $BILLING_MSG"
fi
ACTIVE=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"active" *: *\([^,}]*\).*/\1/p' | tr -d ' ')
if [ "$ACTIVE" = "false" ]; then
  # Clear stale tokens so re-auth starts fresh (credentials file is re-created in Step 2c)
  printf '' > "$HOME/.bria/credentials"
  echo "TOKEN_EXPIRED"
fi
BRIA_API_KEY=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"api_token" *: *"\([^"]*\)".*/\1/p')
if [ -n "$BRIA_API_KEY" ]; then
  grep -v '^api_token=' "$HOME/.bria/credentials" > "$HOME/.bria/credentials.tmp" 2>/dev/null || true
  printf 'api_token=%s\n' "$BRIA_API_KEY" >> "$HOME/.bria/credentials.tmp"
  mv "$HOME/.bria/credentials.tmp" "$HOME/.bria/credentials"
fi

Interpret the output:

• If it prints BILLING_ERROR: ... — relay the message to the user exactly as shown and stop. Do not make any API calls.
• If it prints TOKEN_EXPIRED — the session is no longer valid. Tell the user their session expired and restart from Step 2.
• Otherwise, BRIA_API_KEY now contains the real API key and is cached for future calls. Proceed to the next section.

How to Delayer an Ad

Source the helper script at references/code-examples/bria_delayer_client.sh (resolve <SKILL_DIR> to this skill's own directory), then make one call. It handles the local-file encoding, the JSON, the submit, the polling, and downloading every layer. The API key is auto-loaded from ~/.bria/credentials.

source <SKILL_DIR>/references/code-examples/bria_delayer_client.sh

# A local ad file
bria_delayer "/path/to/summer-sale.jpg"
# → saved summer-sale-layers/result.json
# → saved summer-sale-layers/background_1.png
# → saved summer-sale-layers/logo_1.png
# → saved summer-sale-layers/product_1.png
# → 3 layer image(s) plus result.json in summer-sale-layers

# An ad URL
bria_delayer "https://example.com/creatives/summer-sale.jpg"

That's it. One function call. Delayering is asynchronous and takes 2–3 minutes for a typical ad — the helper polls for up to 6 minutes and tells the user when it is still working.

Input

• Local file path — encoded and sent with the request. No upload step, no temporary URL to manage.
• Image URL — any publicly accessible, direct link to the image file. Passed straight through.

One ad per call — the API takes exactly one image per request. To do several, loop (see Examples).

Supported formats: PNG, JPEG, WEBP, AVIF, GIF, TIFF, BMP, SVG, PDF. There is no file-size limit. Ads larger than 800 px on either side need an enterprise plan; on other plans they are rejected before any work is done, so resize the ad first if the account is capped.

Options

Two environment variables control the wait: BRIA_POLL_INTERVAL (default 10 seconds) and BRIA_POLL_ATTEMPTS (default 36, giving a 6-minute ceiling).

Output

One folder per input ad, named <input-stem>-layers/:

summer-sale-layers/
├── result.json          # the layer manifest
├── background_1.png     # one file per image layer, named by its layer id
├── logo_1.png
├── product_1.png
└── text_1_svg.svg       # each text layer's outlined-glyph twin (see below)

result.json is the full description of the ad:

{
  "canvas": { "width": 1080, "height": 1350 },
  "layers": [
    {
      "id": "canvas_background",
      "type": "vector",
      "subtype": "background",
      "bbox": { "x": 0, "y": 0, "width": 1080, "height": 1350 },
      "z_order": 0,
      "style": { "background_color": "#F4EFE7" }
    },
    {
      "id": "logo_1",
      "type": "image",
      "subtype": "logo",
      "bbox": { "x": 74, "y": 64, "width": 180, "height": 62 },
      "z_order": 4,
      "asset_path": "https://.../logo_1.png"
    },
    {
      "id": "primary_copy_1",
      "type": "text",
      "subtype": "headline",
      "bbox": { "x": 74, "y": 320, "width": 640, "height": 210 },
      "z_order": 5,
      "text": "Summer Sale\nup to 40% off",
      "text_style": {
        "color": "#1B1B1B",
        "font_family": "Poppins",
        "font_weight": 700,
        "font_size_px": 88,
        "line_height": 1.05,
        "text_align": "left"
      }
    }
  ],
  "font_stylesheets": ["https://fonts.googleapis.com/css2?family=Poppins:wght@400;700"]
}

Layer ids are role slots — canvas_background, background_1, logo_1, image_1, product_1, primary_copy_1, secondary_copy_1, cta_1, and so on, falling back to {subtype}_{index} when no slot was assigned. Filenames come straight from those ids; nothing is renamed or invented. Text layers carry their copy and typography in the manifest rather than as a flat image, which is what makes the headline editable. Only image layers have an asset_path, so a text-heavy ad yields fewer files than layers. z_order is paint order, back to front.

Copy comes back twice. Each piece of text is a pair: text_<n>_svg is an image layer holding an .svg of the text with its glyphs outlined as paths — an exact reproduction, but no longer editable text, and text_<n>_font is a text layer holding the same words as editable copy plus its text_style. The _font twin is marked "hidden": true, because the outlined SVG is what reproduces the ad exactly. Rebuilding the ad unchanged means painting the _svg layers and skipping every hidden layer; changing a headline, a font, or the language means dropping that _svg layer and rendering its _font twin instead. Painting both draws the text on top of itself.

Examples

Delayer one ad and read back what it is made of

source <SKILL_DIR>/references/code-examples/bria_delayer_client.sh
bria_delayer "/path/to/creatives/black-friday-1080x1350.jpg"
cat black-friday-1080x1350-layers/result.json

Delayer an ad from a URL, with guidance

source <SKILL_DIR>/references/code-examples/bria_delayer_client.sh
bria_delayer "https://example.com/ads/spring-promo.png" \
  --prompt "the small print at the bottom is one legal text layer; the badge top-left is the brand logo"

Take extra care on a dense creative

source <SKILL_DIR>/references/code-examples/bria_delayer_client.sh
bria_delayer "/path/to/multi-product-carousel.png" --effort high --out-dir ./carousel-layers

A very large or unusually complex ad

Big canvases take longer than the 6-minute default. Widen the window rather than re-running:

source <SKILL_DIR>/references/code-examples/bria_delayer_client.sh
BRIA_POLL_ATTEMPTS=90 bria_delayer "/path/to/billboard-6000x3000.png"   # 15-minute ceiling

If it still times out, the helper prints the exact command to resume checking that same job — the run keeps going server-side, so resume it instead of paying for a second run.

Delayer a folder of finished ads

source <SKILL_DIR>/references/code-examples/bria_delayer_client.sh
for ad in creatives/*.jpg; do
  [ -f "$ad" ] || continue
  bria_delayer "$ad" && echo "Done: $ad" || echo "Failed: $ad" >&2
done

Runs are sequential on purpose: the default limit is 9 delayering submits a minute per account, and each run takes minutes anyway.

How It Works

1. The ad is sent to Bria's delayering endpoint (POST /v2/ads/image_to_layers) — a local file is encoded into the request, a URL is passed through
2. The API accepts the job with HTTP 202 and a status_url; the work runs asynchronously
3. The helper polls that status URL every 10 seconds until the run reaches a terminal state
4. On completion the response carries a pointer to the layer manifest; the helper fetches it as result.json
5. Every image layer's asset_path is downloaded next to the manifest, named after its layer id

Common Errors

Delayering runs asynchronously, so most failures arrive when the job's status is polled rather than as an immediate rejection. The helper handles all of these — this table is what it tells the user, and what it does next.

Only the 401 / 403 row is an authentication problem. A rejected or unreadable image, a failed run, or a timeout says nothing about the credentials — do not re-run the sign-in step for those, and do not clear ~/.bria/credentials.

Two rules for handling any of these:

• The helper already applies the retry policy in the last column. Never re-submit the same ad by hand — every submit is a billed 2–3 minute run, and a failure the table marks "No" will fail again for the same reason. If the ad looks fine locally and Bria still rejects it, that is worth reporting, not retrying.
• Tell the user the cause and the fix, not the mechanics. Endpoints, tokens, status URLs, poll counts and HTTP codes are not useful to them; the files you produced, or what to change about the ad, are.

Additional Resources

• API Endpoints Reference — the real endpoint contract: request fields, the 202/status/result-pointer flow, the manifest schema, error shapes, rate limits
• Shell Client (bria_delayer_client.sh) — bria_delayer (one call, end to end) plus bria_delayer_submit, bria_delayer_wait, and bria_delayer_download if the steps are needed separately

Related Skills

• remove-background — One transparent PNG of the foreground subject (RMBG 2.0). Use it for cutouts; use this skill when a whole ad has to come apart
• bria-ai — Full Bria API access: generate images, edit photos, remove objects, upscale, restyle, product photography, and 20+ more endpoints
• image-utils — Local post-processing with Python Pillow: resize, crop, composite the recovered layers back together
• vgl — Structured VGL JSON for deterministic control over new image generation