Skill: galbria/bria-ai (version 1.3.0)

--- name: bria-ai description: AI image generation, editing, and background removal API via Bria.ai — authenticates via OAuth device flow and caches credentials in ~/.bria/credentials, then calls 20+ endpoints to remove backgrounds for transparent PNGs and cutouts, generate images from text prompts, and edit photos with natural language instructions. Also create product photography and lifestyle shots, replace or blur backgrounds, upscale resolution, restyle, and batch-generate visual assets. Use this skill whenever the user wants to remove a background, create transparent PNGs, generate, edit, modify, or transform any image — including hero images, banners, social media visuals, product photos, illustrations, icons, thumbnails, ad creatives, or marketing materials. Also triggers on cutout, inpainting, outpainting, object removal or addition, photo restoration, style transfer, image enhancement, relight, reseason, sketch-to-photo, or any visual content creation. Commercially safe, royalty-free. license: MIT homepage: https://bria.ai metadata: author: Bria AI version: "1.3.0" openclaw: requires: env: - BRIA_API_KEY anyBins: - curl config: - ~/.bria/credentials primaryEnv: BRIA_API_KEY homepage: https://bria.ai emoji: "\U0001F5BC" --- # Bria — AI Image Generation, Editing & Background Removal Commercially safe, royalty-free image generation and editing through 20+ API endpoints. Generate from text, edit with natural language, remove backgrounds, create product shots, and build automated image pipelines. For additional endpoint details beyond what is documented here, see the [Bria API reference for agents](https://docs.bria.ai/llms.txt). ## When to Use This Skill Use this skill when the user wants to: - **Generate images** — "create an image of...", "make me a banner", "generate a hero image", "I need a product photo" - **Edit images** — "change the background", "make it look like winter", "add a vase to the table", "remove the person" - **Remove/replace backgrounds** — "make the background transparent", "cut out the product", "replace with a studio background" - **Product photography** — "create a lifestyle shot", "place this product in a kitchen scene", "e-commerce packshot" - **Enhance/transform** — "upscale this image", "make it higher resolution", "restyle as oil painting", "change the lighting" - **Batch/pipeline** — "generate 10 product images", "process all these images", "remove backgrounds in bulk" This skill handles the full spectrum of AI image operations. If the user mentions images, photos, visuals, or any visual content creation — use this skill. --- ## What You Can Build - **E-commerce product catalog** — Generate product photos, remove backgrounds for transparent PNGs, place products in lifestyle scenes (kitchen, office, outdoor), create packshots with consistent style - **Landing page visuals** — Generate hero images, abstract tech backgrounds, team photos, and section illustrations — all matching your brand aesthetic - **Social media content** — Instagram posts (1:1), Stories/Reels (9:16), LinkedIn banners (16:9), ad creatives — batch-generate variants for A/B testing - **Marketing campaign assets** — Seasonal transformations (summer→winter), restyle product shots for different markets, create localized visuals at scale - **Photo restoration pipeline** — Restore old damaged photos, colorize black & white images, upscale low-res photos to 4x, enhance quality automatically - **Brand asset toolkit** — Remove backgrounds from logos, blend artwork onto products (t-shirts, mugs), create consistent product photography across your entire catalog - **AI-powered design workflows** — Chain operations: generate→edit→remove background→place in scene→upscale — all automated through API pipelines --- ## Setup — Authentication Before making any API call, you need a valid Bria access token. ### Step 1: Check for existing credentials ```bash 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:** ```bash 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](https://platform.bria.ai/device/verify?user_code={user_code}) > 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): ```bash 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: ```bash INTROSPECT=$(curl -s -X POST "https://engine.prod.bria-api.com/v2/auth/token/introspect" \ -d "[REDACTED_SECRET]") 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. --- ## Core Capabilities | Need | Capability | Use Case | |------|------------|----------| | Generate images from text | FIBO Generate | Hero images, product shots, illustrations, social media images, banners | | Edit images by text instruction | FIBO-Edit | Change colors, modify objects, transform scenes | | Edit image region with mask | GenFill/Erase | Precise inpainting, add/replace specific regions | | Add/Replace/Remove objects | Text-based editing | Add vase, replace apple with pear, remove table | | Remove background (transparent PNG) | RMBG-2.0 | Extract subjects for overlays, logos, cutouts | | Replace/blur/erase background | Background ops | Change, blur, or remove backgrounds | | Expand/outpaint images | Outpainting | Extend boundaries, change aspect ratios | | Upscale image resolution | Super Resolution | Increase resolution 2x or 4x | | Enhance image quality | Enhancement | Improve lighting, colors, details | | Restyle images | Restyle | Oil painting, anime, cartoon, 3D render | | Change lighting | Relight | Golden hour, spotlight, dramatic lighting | | Change season | Reseason | Spring, summer, autumn, winter | | Composite/blend images | Image Blending | Apply textures, logos, merge images | | Restore old photos | Restoration | Fix old/damaged photos | | Colorize images | Colorization | Add color to B&W, or convert to B&W | | Sketch to photo | Sketch2Image | Convert drawings to realistic photos | | Create product lifestyle shots | Lifestyle Shot | Place products in scenes for e-commerce | | Integrate products into scenes | Product Integrate | Embed products at exact coordinates | ## How to Call Any Endpoint Use `bria_call` for all API calls. It handles URL passthrough, local file base64 encoding, JSON construction, API call, and async polling in a single function call. The API key is auto-loaded from `~/.bria/credentials`. ```bash source ~/.agents/skills/bria-ai/references/code-examples/bria_client.sh # Generate (no image input — pass empty string) RESULT=$(bria_call /v2/image/generate "" '"prompt": "your description", "aspect_ratio": "16:9", "sync": true') # Remove background RESULT=$(bria_call /v2/image/edit/remove_background "/path/to/local/image.png") # Replace background RESULT=$(bria_call /v2/image/edit/replace_background "https://example.com/img.jpg" '"prompt": "sunset beach"') # Edit image (uses images array — pass --key images) RESULT=$(bria_call /v2/image/edit "/path/to/image.png" --key images '"instruction": "make it look warmer"') # Upscale RESULT=$(bria_call /v2/image/edit/increase_resolution "https://example.com/img.jpg" '"scale": 4') # Lifestyle shot RESULT=$(bria_call /v1/product/lifestyle_shot_by_text "/path/to/product.png" '"prompt": "modern kitchen countertop"') echo "$RESULT" ``` **Calling convention:** `bria_call <endpoint> <image_or_empty> [--key <json_key>] [extra JSON fields...]` - Pass a URL, local file path, or `""` (empty) for endpoints without image input - Use `--key images` when the endpoint expects an `images` array instead of `image` - Extra JSON fields are appended as key-value pairs: `'"key": "value"'` - Returns the result image URL on success, or prints an error to stderr **Generation options:** Aspect ratios `1:1`, `16:9`, `4:3`, `9:16`, `3:4`. Resolution `1MP` (default) or `4MP` (more detail, +30s). Pass `"sync": true` for single images. > **Advanced**: For precise control over generation, use the **vgl** skill for structured VGL JSON prompts instead of natural language. See **[API Endpoints Reference](references/api-endpoints.md)** for full parameter documentation on all 20+ endpoints. --- ## Prompt Engineering Tips - **Style**: "professional product photography" vs "casual snapshot", "flat design illustration" vs "3D rendered" - **Lighting**: "soft natural light", "studio lighting", "dramatic shadows" - **Background**: "white studio", "gradient", "blurred office", "transparent" - **Composition**: "centered", "rule of thirds", "negative space on left for text" - **Quality keywords**: "high quality", "professional", "commercial grade", "4K", "sharp focus" - **Negative prompts**: "blurry, low quality, pixelated", "text, watermark, logo" ### Recipes by Use Case **Hero banner (16:9):** `"Modern tech startup workspace with developers collaborating, bright natural lighting, clean minimal aesthetic"` — include "clean background" or "minimal" for text overlay space **Product photo (1:1):** `"Professional product photo of [item] on white studio background, soft shadows, commercial photography lighting"` — then remove background for transparent PNG **Presentation visual (16:9):** `"Abstract visualization of data analytics, blue and purple gradient, modern corporate style, clean composition with space for text"` — common themes: "abstract technology", "business collaboration", "minimalist geometric patterns" **Instagram post (1:1):** `"Lifestyle photo of coffee and laptop on wooden desk, morning light, cozy atmosphere"` **Story/Reel (9:16):** `"Vertical product showcase of smartphone, floating in gradient background, tech aesthetic"` --- ## Additional Resources - **[API Endpoints Reference](references/api-endpoints.md)** — Complete endpoint documentation with request/response formats for all 20+ endpoints - **[Shell Client (bria_client.sh)](references/code-examples/bria_client.sh)** — Single-function helper: `bria_call` handles auth, base64, JSON, polling - **[Full API docs for agents (llms.txt)](https://docs.bria.ai/llms.txt)** — Agent-ready Bria API reference; use when this skill's summary is not enough ## Related Skills - **vgl** — Write structured VGL JSON prompts for precise, deterministic control over FIBO image generation - **image-utils** — Classic image manipulation (resize, crop, composite, watermarks) for post-processing

path: references/api-endpoints.md
content: # 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.3.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",
  "num_results": 1,
  "seed": null
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required* | Image description (* or use `structured_prompt`) |
| `aspect_ratio` | string | "1:1" | "1:1", "4:3", "16:9", "3:4", "9:16" |
| `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 |
| `num_results` | int | 1 | Number of images (1-4) |
| `seed` | int | random | For reproducibility |
| `structured_prompt` | string | - | JSON from previous generation (for refinement). Use with `prompt` to refine, or alone with `seed` to recreate. |
| `image_url` | string | - | Reference image (for inspire mode) |

**Input Combination Rules** (mutually exclusive):
- `prompt` — Generate from text
- `image_url` — Generate inspired by a reference image
- `image_url` + `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`, `num_results`, and `seed`.

**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 using natural language instructions. No mask required.

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

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `images` | array | required | Array of image URLs or base64 data URLs |
| `instruction` | string | required | Edit instruction in natural language |

### 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",
  "negative_prompt": "string",
  "num_results": 1
}
```

**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" |
| `negative_prompt` | string | - | What to avoid |
| `num_results` | int | 1 | Number of variations |

**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 | required | Target ratio: "1:1", "4:3", "16:9", "3:4", "9:16" |
| `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",
  "scale": 2
}
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `image` | string | required | Source image URL |
| `scale` | int | 2 | Upscale factor (2 or 4) |

### POST /v1/product/lifestyle_shot_by_text

Place a product in a lifestyle scene using text description.

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

### POST /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://..."
}
```

---

## 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",
  "overlay": "texture-or-art-url",
  "instruction": "Place the art 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 | required | 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",
  "prompt": "optional description"
}
```

### 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`

---

## Status Polling

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

Check async request status.

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

**Status Values:**
- `IN_PROGRESS` - Still processing
- `COMPLETED` - Success, result available
- `FAILED` - Error occurred

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

def poll(status_url, api_key, timeout=120):
    headers = {"api_token": api_key, "User-Agent": "BriaSkills/1.3.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"] == "FAILED":
            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)


path: references/code-examples/bria_client.sh
content: #!/bin/bash
# bria_client.sh — Self-contained helper for Bria API calls.
# Zero dependencies beyond curl, base64, sed (standard on macOS/Linux).
#
# Usage:
#   source bria_client.sh
#   RESULT=$(bria_call /v2/image/generate "" '"prompt":"a sunset","aspect_ratio":"16:9","sync":true')
#   RESULT=$(bria_call /v2/image/edit/remove_background "/path/to/image.png")
#   RESULT=$(bria_call /v2/image/edit/replace_background "https://example.com/img.jpg" '"prompt":"sunset beach"')
#   RESULT=$(bria_call /v2/image/edit "/path/to/image.png" --key images '"instruction":"make it red"')
#
# BRIA_API_KEY is auto-loaded from ~/.bria/credentials if not already set.

BRIA_API_BASE="${BRIA_API_BASE:-https://engine.prod.bria-api.com}"
BRIA_USER_AGENT="BriaSkills/1.3.0"

bria_call() {
  local endpoint image key extra payload result http_code body url status_url poll i
  endpoint="$1"; image="$2"; shift 2

  key="image"; extra=""
  while [ $# -gt 0 ]; do
    case "$1" in
      --key) key="$2"; shift 2 ;;
      *) extra="${extra:+$extra, }$1"; shift ;;
    esac
  done

  if [ -z "$BRIA_API_KEY" ] && [ -f "$HOME/.bria/credentials" ]; then
    BRIA_API_KEY=$(grep '^api_token=' "$HOME/.bria/credentials" | cut -d= -f2-)
  fi
  [ -z "$BRIA_API_KEY" ] && { echo "ERROR: BRIA_API_KEY not set. Run auth first." >&2; return 1; }

  # --- Build JSON payload to temp file (safe for large images) ---
  payload="/tmp/bria_payload_$$.json"

  if [ -z "$image" ]; then
    printf '{' > "$payload"
  elif printf '%s' "$image" | grep -qE '^https?://'; then
    if [ "$key" = "images" ]; then
      printf '{"images": ["%s"]' "$image" > "$payload"
    else
      printf '{"%s": "%s"' "$key" "$image" > "$payload"
    fi
  else
    [ ! -f "$image" ] && { echo "ERROR: File not found: $image" >&2; return 1; }
    if [ "$key" = "images" ]; then
      printf '{"images": ["' > "$payload"
    else
      printf '{"%s": "' "$key" > "$payload"
    fi
    base64 < "$image" | tr -d '\n' >> "$payload"
    if [ "$key" = "images" ]; then
      printf '"]' >> "$payload"
    else
      printf '"' >> "$payload"
    fi
  fi

  if [ -n "$extra" ]; then
    if [ -z "$image" ]; then
      printf '%s' "$extra" >> "$payload"
    else
      printf ', %s' "$extra" >> "$payload"
    fi
  fi
  printf '}' >> "$payload"

  # --- API call ---
  result="/tmp/bria_result_$$.json"
  http_code=$(curl -s -o "$result" -w '%{http_code}' -X POST \
    "${BRIA_API_BASE}${endpoint}" \
    -H "api_token: $BRIA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "User-Agent: $BRIA_USER_AGENT" \
    -d @"$payload")

  body=$(cat "$result")
  rm -f "$payload" "$result"

  # --- Error handling ---
  case "$http_code" in
    401) echo "ERROR 401: API key invalid. Delete ~/.bria/credentials and re-authenticate." >&2; return 1 ;;
    403) echo "ERROR 403: Billing/quota issue. Visit https://platform.bria.ai/pricing" >&2; echo "$body" >&2; return 1 ;;
    5*) echo "ERROR $http_code: Server error. Try again shortly." >&2; return 1 ;;
  esac

  if [ "${http_code:-0}" -ge 400 ] 2>/dev/null; then
    echo "ERROR $http_code: $body" >&2; return 1
  fi

  # --- Extract result URL (sync response) ---
  url=$(printf '%s' "$body" | sed -n 's/.*"result_url" *: *"\([^"]*\)".*/\1/p')
  [ -n "$url" ] && { echo "$url"; return 0; }
  url=$(printf '%s' "$body" | sed -n 's/.*"image_url" *: *"\([^"]*\)".*/\1/p')
  [ -n "$url" ] && { echo "$url"; return 0; }

  # --- Async: poll status_url ---
  status_url=$(printf '%s' "$body" | sed -n 's/.*"status_url" *: *"\([^"]*\)".*/\1/p')
  if [ -n "$status_url" ]; then
    i=0
    while [ "$i" -lt 30 ]; do
      sleep 3
      poll=$(curl -s "$status_url" \
        -H "api_token: $BRIA_API_KEY" \
        -H "User-Agent: $BRIA_USER_AGENT")
      if printf '%s' "$poll" | grep -qE '"status" *: *"(ERROR|FAILED)"'; then
        echo "ERROR: Job failed. Response: $poll" >&2; return 1
      fi
      url=$(printf '%s' "$poll" | sed -n 's/.*"result_url" *: *"\([^"]*\)".*/\1/p')
      [ -z "$url" ] && url=$(printf '%s' "$poll" | sed -n 's/.*"image_url" *: *"\([^"]*\)".*/\1/p')
      [ -n "$url" ] && { echo "$url"; return 0; }
      i=$((i + 1))
    done
    echo "ERROR: Polling timed out after 90 seconds" >&2
    return 1
  fi

  echo "$body"
}


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)