Skip to content

Bria-AI/bria-skill / skills/bria-ai

bria-ai

Verified

Image generation, photo editing, background removal — transparent PNG images, cutouts, ecommerce packshots, product catalogs, lifestyle shots via Bria.ai. Build store-ready e-commerce catalogs at scale — shadows, product dimensions images, lifestyle scenes, marketplace listing variants. ALWAYS use this skill when the user wants to generate, edit, or transform any image — hero images, banners, social media visuals, product photos, illustrations, icons, thumbnails, ad creatives, or marketing materials — or to build a product catalog, create a packshot, stage a lifestyle shot, remove a background, make transparent PNGs, or batch-process product photos. Triggers on packshot, product catalog, product shot creator, lifestyle shot, cutout, product dimensions image, inpainting, outpainting, object removal, upscale, photo restoration, style transfer, relight, reseason, sketch-to-photo. Commercially safe, royalty-free.

references/api-endpoints.md

View on GitHub
# 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 2 - 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", "16:10", "10:16", "2:1", "1:2", "21:9", "9:21", "3:1", "1:3", "4:1", "1:4", "5:1", "1:5" |
| `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. |
| `style` | string | - | Photographic look for text-to-image: `"kodak_film"`, `"hard_flash"`, `"hazy_dreamy"` or `"rough_realism"`. Use it when the user asks for one of these looks. Prompt only: rejected with `style_id`, `structured_prompt`, `images`, `"4MP"`, lite or tailored. |
| `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`. `style` works only with `prompt` alone. 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) |
| `prompt` | string | Optional. A filled `prompt` runs the guided cut (add, drop or narrow what the cut keeps) and is priced as a guided call. Omitted or blank, it is the plain cut at the plain price. |

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

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

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

Remove the background, optionally following a plain-English prompt for what to keep, drop, or narrow
to, e.g. "without the dog", "only the chair". Starts from the same cut as plain remove background,
then adjusts only what the prompt names. Returns PNG with transparency, same as the plain route.

**Request:**
```json
{
  "image": "https://publicly-accessible-image-url",
  "prompt": "only the laptop"
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `image` | string | Source image URL (JPEG, PNG, WEBP) |
| `prompt` | string | Optional. Plain-English text naming what to keep, drop, or narrow to. Omitted or blank returns the plain cut, still billed as a guided call. |

Any remove-background option that still applies to a cutout (e.g. output format) carries over unchanged.

Takes **15-20 seconds** — call with `"sync": false` and poll `status_url`, same as any other async
endpoint.

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

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

**A 404 means guided removal is unavailable for this organization right now**, not a bad request.
Don't retry the guided route; fall back to plain
`/v2/image/edit/remove_background` and say so in one line.

---

## Fibo 2 - 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", "16:10", "10:16", "2:1", "1:2", "21:9", "9:21", "3:1", "1:3", "4:1", "1:4", "5:1", "1:5". 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",
  "composite": false
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `image` | string | required | Source image URL |
| `mask` | string | required | Mask URL (white=erase, black=keep). Mask only the object, in both modes |
| `composite` | bool | true | `true` = pixel perfect: everything outside the mask stays as it was. `false` = context aware: also removes what the object casts outside the mask, such as its shadow or reflection |

Send `composite: false` by default: it also removes the object's shadow or reflection, and the rest of the image may be lightly re-rendered. Send `true` only when nothing outside the mask may change (catalog retouching, faces, products, text near the object).

### 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/extract_object

Pull one named object out of a scene as its own cutout — not a background-removal call, a
single-object extraction. Use this when the user names a specific thing to lift out (e.g. "extract
the tree"), as opposed to adjusting what a background-removal cutout keeps.

**Request:**
```json
{
  "image": "base64-or-url",
  "prompt": "the tree"
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `image` | string | required | Source image URL or base64 |
| `prompt` | string | required | What to extract, in natural language (e.g. "the red car") |
| `autocrop` | bool | false | If true, tightly crop the output PNG to the cutout's bounding box |
| `remove_background` | bool | false | If true, refine the cutout alpha with background removal; if false, uses SAM segmentation instead |

### 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)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall