# Bria.ai API Reference

## Base URL & Authentication

**Base URL:** `https://engine.prod.bria-api.com`

**Authentication:** Include these headers in all requests:
```
api_token: YOUR_BRIA_API_KEY
Content-Type: application/json
User-Agent: BriaSkills/<version>
```

> **Required:** Always include the `User-Agent: BriaSkills/<version>` header (where `<version>` is the current skill version from `package.json`, e.g. `BriaSkills/1.4.0`) in every API call, including status polling requests.

---

## FIBO - Image Generation

### POST /v2/image/generate

Generate images from text prompts using FIBO's structured prompt system.

**Request:**
```json
{
  "prompt": "string (required)",
  "aspect_ratio": "1:1",
  "resolution": "1MP",
  "negative_prompt": "string",
  "seed": null,
  "style_id": "default"
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required* | Image description (* or use `structured_prompt`) |
| `aspect_ratio` | string | "1:1" | "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9" |
| `resolution` | string | "1MP" | Output image resolution. "1MP" or "4MP". "4MP" improves image details, especially for photorealism, but increases latency by ~30 seconds. |
| `negative_prompt` | string | - | What to exclude |
| `seed` | int | random | For reproducibility |
| `style_id` | string | "default" | Named prompt style that shapes how the prompt becomes the image. `"default"` (standard) or `"photoreal"` (tuned for photorealistic results). Optional — omit for the standard style. |
| `structured_prompt` | string | - | JSON from previous generation (for refinement). Use with `prompt` to refine, or alone with `seed` to recreate. |
| `images` | array | - | Reference image for inspire mode: an array holding one image URL or base64 string |

**Input Combinations** — at least one of `prompt`, `images` or `structured_prompt` is required:
- `prompt` — Generate from text
- `images` — Generate inspired by a reference image
- `images` + `prompt` — Generate inspired by image, guided by text
- `structured_prompt` + `seed` — Recreate a previous image exactly
- `structured_prompt` + `prompt` + `seed` — Refine a previous image with new instructions

All combinations support `aspect_ratio`, `negative_prompt`, `seed`, and `style_id`. Note that `"sync": true`
cannot be combined with `"resolution": "4MP"` — that pairing is rejected.

**Response:**
```json
{
  "request_id": "uuid",
  "status_url": "https://engine.prod.bria-api.com/v2/status/uuid"
}
```

**Completed Result:**
```json
{
  "status": "COMPLETED",
  "result": {
    "image_url": "https://...",
    "structured_prompt": "{...}",
    "seed": 12345
  }
}
```

---

## RMBG-2.0 - Background Removal

### POST /v2/image/edit/remove_background

Remove background from image. Returns PNG with transparency.

**Request:**
```json
{
  "image": "https://publicly-accessible-image-url"
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `image` | string | Source image URL (JPEG, PNG, WEBP) |

**Response:**
```json
{
  "request_id": "uuid",
  "status_url": "https://..."
}
```

**Completed Result:**
```json
{
  "status": "COMPLETED",
  "result": {
    "image_url": "https://...png"
  }
}
```

---

## FIBO-Edit - Image Editing

### POST /v2/image/edit

Edit an image with a natural language instruction — no mask required. Send one image to change it,
or 2–4 images to combine them: the subject from one with an outfit, product, style, or background
from another.

**Request:**
```json
{
  "images": ["https://source-image-url"],
  "instruction": "change the mug color to red"
}
```

**Multi-reference request.** `images` is ordered, and the instruction addresses each entry by its
position — the first is "image 1", the second "image 2", and so on:
```json
{
  "images": ["https://man-image-url", "https://santa-outfit-image-url"],
  "instruction": "dress the man in image 1 in the santa outfit from image 2",
  "seed": 1234
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `images` | array | required | 1–4 image URLs or base64 data URLs. **Order matters** — the instruction refers to them as "image 1", "image 2", … in the order they are sent |
| `instruction` | string | required | Edit instruction in natural language. Refer to additional images by position |
| `seed` | int | random | For reproducibility — the same images, instruction and seed reproduce the same result |
| `aspect_ratio` | string | - | Output ratio: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9". Honored only with 2 or more images. Do not send it on a single-image request — the output follows that image regardless and the response carries a `warning`; to change one image's ratio, use `/v2/image/edit/expand` |
| `model_version` | string | - | Deprecated and ignored — the service picks the edit model from the request contents. A value that is sent comes back with a notice in `warning`; omit it |

**Writing a multi-reference instruction:**
- Put the image being edited first and the references after it.
- Say what each reference contributes ("the outfit from image 2", "the background of image 3"), not
  just that it exists.
- Plain prose, plain words — "image 1", "image 2". No brackets, tags, or markup.

This endpoint is asynchronous: it answers with `request_id` and `status_url`, which you poll. Do
not send `"sync": true` here — an instruction edit takes longer than a single response is allowed to
take, so a synchronous request fails with a gateway timeout even though the job itself is fine.

**Constraints** — each returns 422 with a readable message:
- More than 4 images. Trim the set before sending; the request is refused, not truncated.
- A `mask` together with 2 or more images (masked edits are single-image only).
- 2 or more images together with a tailored `model_id` or `model_version: FIBO_BBQ` — both of those
  run on the single-reference model.

**Completed Result:**
```json
{
  "status": "COMPLETED",
  "result": {
    "image_url": "https://...",
    "seed": 1234,
    "structured_prompt": "{...}",
    "warning": null
  }
}
```

The result also carries the structured instruction the edit was rendered from — named
`structured_prompt` on a polled result and `structured_instruction` on an inline `"sync": true`
response. Read whichever is present.

`warning` is set when a parameter was accepted but not honored — `aspect_ratio` on a single-image
request, a supplied `model_version`, or a tuning parameter the serving model does not read. Relay it
to the user rather than dropping it.

### POST /v2/image/edit/gen_fill

Generate content in a masked region (inpainting).

**Request:**
```json
{
  "image": "https://source-image-url",
  "mask": "https://mask-image-url",
  "prompt": "what to generate",
  "mask_type": "manual"
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `image` | string | required | Source image URL |
| `mask` | string | required | Mask URL (white=edit, black=keep) |
| `prompt` | string | required | What to generate in masked area |
| `mask_type` | string | "manual" | "manual" or "automatic" |

**Mask Requirements:**
- White pixels (255) = area to edit
- Black pixels (0) = area to preserve
- Same aspect ratio as source image

### POST /v2/image/edit/erase

Remove objects defined by mask.

**Request:**
```json
{
  "image": "https://source-image-url",
  "mask": "https://mask-image-url"
}
```

### POST /v2/image/edit/erase_foreground

Remove primary subject and fill with background.

**Request:**
```json
{
  "image": "https://source-image-url"
}
```

### POST /v2/image/edit/replace_background

Replace background with AI-generated content.

**Request:**
```json
{
  "image": "https://source-image-url",
  "prompt": "new background description"
}
```

### POST /v2/image/edit/blur_background

Apply blur effect to image background.

**Request:**
```json
{
  "image": "https://source-image-url"
}
```

### POST /v2/image/edit/expand

Expand/outpaint an image to extend its boundaries.

**Request:**
```json
{
  "image": "base64-string-or-url",
  "aspect_ratio": "16:9",
  "prompt": "optional description for new content"
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `image` | string | required | Source image URL or base64 string |
| `aspect_ratio` | string \| float | - | Target ratio: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", or a float. Omit it and pass `canvas_size` instead |
| `prompt` | string | - | Optional - describe content to generate |

### POST /v2/image/edit/enhance

Enhance image quality (lighting, colors, details).

**Request:**
```json
{
  "image": "https://source-image-url"
}
```

### POST /v2/image/edit/increase_resolution

Upscale image resolution.

**Request:**
```json
{
  "image": "https://source-image-url",
  "desired_increase": 4,
  "preserve_alpha": true
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `image` | string | required | Source image URL |
| `desired_increase` | int | 2 | Upscale factor: 2 or 4 |
| `preserve_alpha` | bool | true | Preserve transparency. Set `true` when input has an alpha channel — the API upscales and recombines the alpha server-side, so you don't need to handle it client-side. |

### POST /v1/product/cutout

Remove the background from a product photo → clean transparent PNG. The `/v1/product/*` endpoints take `image_url` (URL) or `file` (base64).

**Request:**
```json
{ "image_url": "https://…/raw.jpg" }
```
Response: `{ "result_url": "https://…png" }` (synchronous).

### POST /v1/product/packshot

Standardized 2000×2000 packshot on a solid/clean background.

| Parameter | Type | Notes |
|-----------|------|-------|
| `image_url` / `file` | string | Product image (a cutout is recommended) |
| `background_color` | string | Hex like `#FFFFFF`, or `transparent` |
| `sku` | string | Optional label/id |

Response: `{ "result_url": "…" }` (synchronous).

### POST /v1/product/shadow

Add a realistic shadow to a product cutout.

| Parameter | Type | Notes |
|-----------|------|-------|
| `image_url` / `file` | string | Product cutout |
| `type` | string | `regular` (drop) or `float` (elliptical) |
| `background_color` | string | Hex or `transparent` |
| `shadow_intensity` | int | 0–100 (approx) |

Response: `{ "result_url": "…" }` (synchronous).

### POST /v1/product/lifestyle_shot_by_text

Place a product in a lifestyle scene using text description.

**Request:**
```json
{
  "file": "BASE64_ENCODED_IMAGE",
  "scene_description": "modern kitchen countertop, natural lighting",
  "placement_type": "automatic"
}
```

**Parameters:**

| Parameter | Type | Notes |
|-----------|------|-------|
| `image_url` / `file` | string | Product (cutout recommended) |
| `scene_description` | string | Environment + lighting + mood |
| `mode` | string | `base`, `high_control` (recommended), `fast` |
| `placement_type` | string | `automatic`, `automatic_aspect_ratio`, `manual_placement`, `custom_coordinates`, `manual_padding`, `original` |
| `aspect_ratio` | string | e.g. `1:1`, `4:5`, `16:9` (with `automatic_aspect_ratio`) |
| `num_results` | int | Number of variations |
| `sync` | bool | `true` returns results inline |
| `optimize_description` | bool | Let Bria refine the prompt |

Response: `{ "result": [[ "image_url", "seed", "session_id" ], …] }` — extract `result[0][0]`.

### POST /v1/product/lifestyle_shot_by_image

Same as `lifestyle_shot_by_text`, but the scene comes from a reference background image instead of a text description.

| Parameter | Type | Notes |
|-----------|------|-------|
| `image_url` / `file` | string | Product |
| `ref_image_urls` | array | One or more background reference URLs |
| `placement_type` | string | see above |
| `num_results` | int | variations |

Response: `{ "result": [[ "image_url", … ], …] }`.

### POST /v2/image/edit/product/integrate

Integrate and embed one or more products into a predefined scene at precise user-defined coordinates. The product is automatically matched to the scene's lighting, perspective, and aesthetics. Products are automatically cut out from their background as part of the pipeline.

**Request:**
```json
{
  "scene": "https://scene-image-url",
  "products": [
    {
      "image": "https://product-image-url",
      "coordinates": {
        "x": 100,
        "y": 200,
        "width": 300,
        "height": 400
      }
    }
  ],
  "seed": 42
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `scene` | string | required | Scene image URL or base64. Accepted formats: jpeg, jpg, png, webp |
| `products` | array | required | Array of product objects (1 to N products) |
| `products[].image` | string | required | Product image URL or base64. If it has an alpha channel, no cutout is applied; otherwise automatic cutout is applied |
| `products[].coordinates` | object | required | Placement and scaling of the product within the scene |
| `products[].coordinates.x` | int | required | X-coordinate of the product's top-left corner (pixels) |
| `products[].coordinates.y` | int | required | Y-coordinate of the product's top-left corner (pixels) |
| `products[].coordinates.width` | int | required | Desired product width in pixels (must not exceed scene dimensions) |
| `products[].coordinates.height` | int | required | Desired product height in pixels (must not exceed scene dimensions) |
| `seed` | int | random | Seed for deterministic generation |

**Response:**
```json
{
  "request_id": "uuid",
  "result": {
    "image_url": "https://..."
  }
}
```

**Async Response (202):**
```json
{
  "request_id": "uuid",
  "status_url": "https://..."
}
```

### POST /v2/image/edit/product/holding

Put a product in someone's hands. Send `person_image` and one to three `product_images`, and the endpoint returns the person naturally holding or carrying the product. No prompt is needed — a person photo and a product photo are a complete request. The person's identity, pose, background, and original aspect ratio are preserved, and the product keeps its exact geometry, colours, branding, and label text. Several product references in one call can compose packaging, a second angle, or a companion item into a single shot. Add an optional `instruction` to art-direct a specific shot (e.g. "Replace the paper coffee cup in her right hand with the can, logo facing the camera.").

**Request:**
```json
{
  "person_image": "https://person-image-url",
  "product_images": [
    "https://product-image-url"
  ],
  "instruction": "Replace the paper coffee cup in her right hand with the can, logo facing the camera."
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `person_image` | string | required | Photo of the person to edit. URL or base64. Accepted formats: jpeg, jpg, png, webp |
| `product_images` | array | required | One to three product images: packaging, a second angle, or a companion item. Each entry is a URL or base64, same as `person_image` |
| `instruction` | string | - | Extra direction for this shot. Optional — send only the detail to steer, not a full prompt |
| `aspect_ratio` | string | `person_image`'s aspect ratio | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9` |
| `seed` | int | random | Seed for deterministic generation |
| `sync` | bool | false | `true` holds the connection open and returns the final image; `false` returns a `status_url` to poll |
| `webhook_url` | string | - | Receive the result via webhook when the async job completes |
| `output_type` | string | - | `png` or `jpeg` |
| `visual_output_content_moderation` | bool | false | If true, returns 422 on visual output moderation failure |

By default (`sync` omitted or `false`) this endpoint is asynchronous: it answers with `request_id` and `status_url`, which you poll.

**Async Response (202):**
```json
{
  "request_id": "uuid",
  "status_url": "https://..."
}
```

**Completed Result:**
```json
{
  "status": "COMPLETED",
  "result": {
    "image_url": "https://...",
    "seed": 1234,
    "structured_prompt": "{...}",
    "warning": null
  }
}
```

The result also carries the structured prompt the shot was rendered from, in `structured_prompt`
(same field name and meaning as on `/v2/image/edit`). `warning` is set when a parameter was
accepted but not honored — relay it to the user rather than dropping it.

### POST /v2/image/edit/product/virtual-tryon

Put garments on a model. Send `person_image` and one to three `garment_images`, and the endpoint returns the person wearing them. No prompt is needed — a person photo and the garments are a complete request. Garment fidelity carries through: print scale, stripe alignment across seams, collar and closure type, and how a garment reads from behind. The person's identity, pose, background, and original aspect ratio are preserved. Send a full outfit together to change several items in one call instead of stacking edits. Add an optional `instruction` to direct the styling (e.g. "He wears the navy blazer over the white t-shirt he already has, and the grey tailored trousers instead of his jeans.").

**Request:**
```json
{
  "person_image": "https://person-image-url",
  "garment_images": [
    "https://garment-image-url"
  ],
  "instruction": "He wears the navy blazer over the white t-shirt he already has."
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `person_image` | string | required | Photo of the person to edit. URL or base64. Accepted formats: jpeg, jpg, png, webp |
| `garment_images` | array | required | One to three garment or accessory images to put on the person. Each entry is a URL or base64, same as `person_image` |
| `instruction` | string | - | Extra direction for this shot. Optional — send only the detail to steer, not a full prompt |
| `aspect_ratio` | string | `person_image`'s aspect ratio | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9` |
| `seed` | int | random | Seed for deterministic generation |
| `sync` | bool | false | `true` holds the connection open and returns the final image; `false` returns a `status_url` to poll |
| `webhook_url` | string | - | Receive the result via webhook when the async job completes |
| `output_type` | string | - | `png` or `jpeg` |
| `visual_output_content_moderation` | bool | false | If true, returns 422 on visual output moderation failure |

By default (`sync` omitted or `false`) this endpoint is asynchronous: it answers with `request_id` and `status_url`, which you poll.

**Async Response (202):**
```json
{
  "request_id": "uuid",
  "status_url": "https://..."
}
```

**Completed Result:**
```json
{
  "status": "COMPLETED",
  "result": {
    "image_url": "https://...",
    "seed": 1234,
    "structured_prompt": "{...}",
    "warning": null
  }
}
```

The result also carries the structured prompt the shot was rendered from, in `structured_prompt`
(same field name and meaning as on `/v2/image/edit`). `warning` is set when a parameter was
accepted but not honored — relay it to the user rather than dropping it.

### POST /v2/image/edit/product/generate/dimensions

Render a marketplace-ready dimension image from a product photo. (The older
`/v2/image/edit/product_dimensions` path still works but is deprecated — use this one.)

How it works: the background is removed automatically, then measurement callout lines + labels are drawn around the product, with an optional title and optional weight/capacity text. Three visual styles. Useful for e-commerce listings (Amazon-style "dimensions" images).

**Request:**
```json
{
  "image": "https://product-image-url",
  "style": "default",
  "dimensions": [
    {"name": "height", "value": 12, "unit": "cm", "position": "left"},
    {"name": "width_bottom", "value": 6, "unit": "cm", "position": "bottom"}
  ],
  "title": "Gummies Bottle",
  "weight": {"value": 250, "unit": "g", "label": "Net Weight"},
  "capacity": {"value": 500, "unit": "ml"},
  "background": "white",
  "output_format": "png"
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `image` | string | required | Product photo URL or base64. Background is removed automatically — no pre-cutout needed |
| `dimensions` | array | required | One or more dimension callouts (min 1) |
| `dimensions[].name` | string | required | `height`, `width_bottom`, or `width_top` (`length`/`depth` not currently enabled) |
| `dimensions[].value` | float | required | Physical measurement value (must be > 0) |
| `dimensions[].unit` | string | required | `mm`, `cm`, `m`, `in`, `"` (inches), `ft`, `'` (feet) |
| `dimensions[].position` | string | per-name | Callout side: `top`, `bottom`, `left`, `right`. Defaults: height→`left`, width_bottom→`bottom`, width_top→`top` |
| `style` | string | required | `default`, `childlike`, or `elegant` |
| `units_display` | string | "single" | `single`, `dual_bullet`, `dual_slash`, `dual_parens`. For dual modes, supply two `dimensions` entries with the same `name`+`position` but different `unit` (e.g. `in` and `cm`) — they merge into one dual-unit label |
| `background` | string | "white" | `white`, `cream`, `charcoal`, or a hex color (e.g. `#f5f0e8`) |
| `title` | string | - | Optional headline above the product (max 80 chars) |
| `title_position` | string | "top_center" | `top_left`, `top_center`, `top_right` |
| `weight` | object | - | Optional weight callout below the product |
| `weight.value` | float | required* | Weight value (> 0) *if `weight` is provided |
| `weight.unit` | string | required* | `lb`, `oz`, `g`, `kg` |
| `weight.label` | string | "Weight" | `Weight` or `Net Weight` |
| `capacity` | object | - | Optional capacity callout below the product |
| `capacity.value` | float | required* | Capacity value (> 0) *if `capacity` is provided |
| `capacity.unit` | string | required* | `fl_oz`, `ml`, `l`, `qt`, `gal`, `cups` |
| `output_format` | string | "png" | `png`, `jpeg`, or `dual` (composite PNG + a transparent overlay-only PNG, returned as two images) |
| `output_size` | int | 2200 | Square output edge length in px (256–2200) |
| `proportional_lines` | bool | true | Scale each dimension line's length to its measurement (the largest per axis spans the product) |

**Async Response (202):**
```json
{
  "request_id": "uuid",
  "status_url": "https://..."
}
```

Poll `status_url` for the result. `dual` output returns two images: `[composite, overlay]`.

---

## Text-Based Object Editing

### POST /v2/image/edit/add_object_by_text

Add a new object to an image using natural language.

**Request:**
```json
{
  "image": "base64-or-url",
  "instruction": "Place a red vase with flowers on the table"
}
```

### POST /v2/image/edit/replace_object_by_text

Replace an existing object with a new one.

**Request:**
```json
{
  "image": "base64-or-url",
  "instruction": "Replace the red apple with a green pear"
}
```

### POST /v2/image/edit/erase_by_text

Remove a specific object by name.

**Request:**
```json
{
  "image": "base64-or-url",
  "object_name": "table"
}
```

---

## Image Transformation

### POST /v2/image/edit/blend

Blend/merge images or apply textures.

**Request:**
```json
{
  "image": "base64-or-url",
  "instruction": "Place the art from this image on the shirt, keep the art exactly the same"
}
```

### POST /v2/image/edit/reseason

Change the season or weather of an image.

**Request:**
```json
{
  "image": "base64-or-url",
  "season": "winter"
}
```

**Seasons:** `spring`, `summer`, `autumn`, `winter`

### POST /v2/image/edit/restyle

Transform the artistic style of an image.

**Request:**
```json
{
  "image": "base64-or-url",
  "style": "oil_painting"
}
```

**Style IDs:** `render_3d`, `cubism`, `oil_painting`, `anime`, `cartoon`, `coloring_book`, `retro_ad`, `pop_art_halftone`, `vector_art`, `story_board`, `art_nouveau`, `cross_etching`, `wood_cut`

### POST /v2/image/edit/relight

Modify the lighting setup of an image.

**Request:**
```json
{
  "image": "base64-or-url",
  "light_type": "sunrise light",
  "light_direction": "front"
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `image` | string | required | Source image URL or base64 |
| `light_type` | string | "soft overcast daylight lighting" | Lighting preset (see values below) |
| `light_direction` | string | required | `front`, `side`, `bottom`, `top-down` |

**Light Types:** `midday`, `blue hour light`, `low-angle sunlight`, `sunrise light`, `spotlight on subject`, `overcast light`, `soft overcast daylight lighting`, `cloud-filtered lighting`, `fog-diffused lighting`, `side lighting`, `moonlight lighting`, `starlight nighttime`, `soft bokeh lighting`, `harsh studio lighting`

---

## Image Restoration & Conversion

### POST /v2/image/edit/sketch_to_colored_image

Convert a sketch or line drawing to a photorealistic image.

**Request:**
```json
{
  "image": "sketch-base64-or-url"
}
```

### POST /v2/image/edit/restore

Restore old/damaged photos by removing noise, scratches, and blur.

**Request:**
```json
{
  "image": "base64-or-url"
}
```

### POST /v2/image/edit/colorize

Add color to B&W photos or convert to B&W.

**Request:**
```json
{
  "image": "base64-or-url",
  "color": "contemporary color"
}
```

**Colors:** `contemporary color`, `vivid color`, `black and white colors`, `sepia vintage`

### POST /v2/image/edit/crop_foreground

Remove background and crop tightly around the foreground.

**Request:**
```json
{
  "image": "base64-or-url"
}
```

---

## Structured Instructions

### POST /v2/structured_instruction/generate

Generate a structured JSON instruction from natural language (no image generated).

**Request:**
```json
{
  "images": ["base64-or-url"],
  "instruction": "change to golden hour lighting",
  "mask": "optional-mask-url"
}
```

**Returns:** `structured_instruction` JSON that can be passed to `/v2/image/edit`

---

## Ad Delayer - Flat Ad to Editable Layers

### POST /v2/ads/delayer

Take a finished, flat ad apart into layers. Asynchronous, and a typical ad takes **2-3 minutes**.

**Request:**
```json
{
  "attachments": ["https://publicly-accessible-image-url"],
  "prompt": "optional guidance for the extraction",
  "thinking_effort": "medium",
  "output_format": "json",
  "sync": false
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `attachments` | array | The source ad. **Exactly one** entry: a public direct image URL, raw base64, or a `data:` URI |
| `prompt` | string | Optional natural-language guidance for the extraction |
| `thinking_effort` | string | `low`, `medium` (default), `high` |
| `output_format` | string | `json` for the layer manifest (default), `html` for the reconstructed render |
| `sync` | boolean | Send `false` — the run is far longer than an HTTP response can wait |

Unknown fields are rejected. Dimensions are capped at 2048 px per side unless the organisation has
enterprise-tier entitlement.

**The result is a pointer, not the layers.** On completion the status response carries
`result.url`, which is a link to `creation.json` — a manifest of every layer with its box, paint
order, text and typography. Only image layers carry an `asset_path`, which is a public URL to
download separately; text layers keep their copy in the manifest, which is what makes them
editable.

> **`bria_call` does not complete this flow.** It looks for `result_url` / `image_url` in the
> status response and gives up after 90 seconds, whereas this endpoint returns `result.url` after
> 2-3 minutes, and the layers then need a second and third fetch. Use the **ad-delayer** skill,
> which polls for up to 6 minutes, follows the pointer, and downloads every layer into a folder
> named after the input.

---

## Status Polling

### GET /v2/status/{request_id}

Check async request status.

**Response:**
```json
{
  "status": "IN_PROGRESS | COMPLETED | ERROR",
  "result": {
    "image_url": "https://..."
  },
  "request_id": "uuid"
}
```

**Status Values:**
- `IN_PROGRESS` - Still processing
- `COMPLETED` - Success, result available
- `ERROR` - The request failed (this is the literal value; there is no `FAILED`)
- `UNKNOWN` - No such request id

**Polling Pattern:**
```python
import requests, time

def poll(status_url, api_key, timeout=120):
    headers = {"api_token": api_key, "User-Agent": "BriaSkills/1.4.0"}
    for _ in range(timeout // 2):
        r = requests.get(status_url, headers=headers)
        data = r.json()
        if data["status"] == "COMPLETED":
            return data["result"]["image_url"]
        if data["status"] in ("ERROR", "UNKNOWN"):
            raise Exception(data.get("error"))
        time.sleep(2)
    raise TimeoutError()
```

---

## Error Handling

### HTTP Status Codes

| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Bad request |
| 401 | Unauthorized - invalid API key |
| 415 | Unsupported media type |
| 422 | Validation failed / Content moderation blocked |
| 429 | Rate limited |
| 500 | Server error |

### Supported Image Formats

- **Input:** JPEG, JPG, PNG, WEBP (RGB, RGBA, CMYK)
- **Output:** PNG (with transparency where applicable)

# Marketplace Presets

Specs the variant exporter enforces per channel. Values reflect each marketplace's main-image guidance at time of writing — always confirm against the latest official policy before a large publish.

## Amazon (main product image)

| Rule | Value |
|------|-------|
| Background | Pure white `#FFFFFF` (RGB 255,255,255) |
| Aspect ratio | 1:1 (square) |
| Product fill | Product fills ~85% of the frame |
| Minimum resolution | 1600 px longest side (≥ 1000 to zoom); 2000–3000 px recommended |
| Format | JPEG (also TIFF/PNG accepted) |
| Not allowed on main | Text, logos, watermarks, props, additional objects, borders |

Notes: the main image must be the product only on pure white. Lifestyle/props belong in the secondary image slots, not the main.

## Shopify

| Rule | Value |
|------|-------|
| Background | White or transparent (be consistent across the catalog) |
| Aspect ratio | 1:1 primary; 4:5 also common for product pages |
| Product fill | ~90%, consistent padding across all products |
| Recommended resolution | 2048 × 2048 (supports zoom); max 4472 × 4472 / 20 MP |
| Format | JPEG (white bg) or PNG (transparent) |

Notes: Shopify is flexible, but a uniform background + padding across the catalog is what makes a store look professional.

## Etsy

| Rule | Value |
|------|-------|
| Aspect ratio | 5:4 landscape (thumbnail crop) |
| Background | White or lifestyle — Etsy encourages context/lifestyle shots |
| Product fill | ~85% |
| Recommended resolution | 2000 px+ on the shortest side |
| Format | JPEG or PNG |

Notes: Etsy thumbnails crop to ~5:4, so keep the product centered with margin so nothing important is clipped.

## How the exporter applies these

`export_variants.py` (and `build_catalog.py`) for each channel:
1. Finds the product's bounding box (via alpha channel, or near-white detection).
2. Builds a canvas at the channel aspect ratio with the shortest side ≥ the channel minimum.
3. Scales the product so it spans the channel's fill ratio of the frame.
4. Centers it on the channel background (white by default; `--bg transparent` for PNG).
5. Saves JPEG (white/solid bg) or PNG (transparent).

Override fill with `--fill 0.8` and background with `--bg "#F5F0E8"` when a brand needs it.