bria-ai

使用商业安全的 AI 模型生成、编辑和转换图像。从文本创建图像，通过自然语言指令进行编辑，删除背景（透明 PNG），替换背景，添加/替换/删除对象，修复，替换，升级（2x/4x），增强质量，重新设计（油画，动漫，3D），重新照明，重新季节，恢复旧照片，着色，草图到照片以及产品生活方式照片。用于需要英雄图像、横幅、产品照片、场景中的产品植入、图标、插图或背景的网站、应用程序、演示文稿。也适用于电子商务摄影、批量生成和管道。触发器包括图像生成、生成/创建图像、编辑照片、删除背景、透明 PNG、替换背景、产品拍摄、生活方式场景、高档、风格转换、照片修复、着色、草图到图像、涂色、修复、剪切主题、将产品集成到场景中。

## 概述（中文）

使用商业安全的 AI 模型生成、编辑和转换图像。从文本创建图像，通过自然语言指令进行编辑，删除背景（透明 PNG），替换背景，添加/替换/删除对象，修复，替换，升级（2x/4x），增强质量，重新设计（油画，动漫，3D），重新照明，重新季节，恢复旧照片，着色，草图到照片以及产品生活方式照片。用于需要英雄图像、横幅、产品照片、场景中的产品植入、图标、插图或背景的网站、应用程序、演示文稿。也适用于电子商务摄影、批量生成和管道。触发器包括图像生成、生成/创建图像、编辑照片、删除背景、透明 PNG、替换背景、产品拍摄、生活方式场景、高档、风格转换、照片修复、着色、草图到图像、涂色、修复、剪切主题、将产品集成到场景中。

## 原文

# Bria — Generate, Edit & Remove Background from Images with AI

Generate, edit, and create visual assets using Bria's commercially-safe AI models (Fibo, Fibo-Edit,  RMBG-2.0, GenFill, and more). Remove or replace backgrounds, create product lifestyle shots, generate transparent PNGs, batch generate images, and build pipeline workflows. Unlike black-box generators, Bria gives you fine-grained control: edit by text instruction, mask specific regions, add/replace/remove individual objects, change lighting or season independently.

## Setup — API Key Check

Before making any Bria API call, check for the API key and help the user set it up if missing:

### Step 1: Check if the key exists (without printing the key)

```bash
if [ -z "$BRIA_API_KEY" ]; then
  echo "BRIA_API_KEY is not set"
else
  echo "BRIA_API_KEY is set"
fi
```

If the output is **not empty**, skip to the next section.

### Step 2: If the key is missing, guide the user

Tell the user exactly this:
> To use image generation, you need a free Bria API key.
>
> 1. Go to https://platform.bria.ai/console/account/api-keys
> 2. Sign up or log in
> 3. Click **Create API Key**

Wait for the user to provide their API key. Do not proceed until they give you the key.

**Do not proceed with any image generation or editing until the API key is confirmed set.**

---

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

## Quick Reference

### Generate an Image (FIBO)

```bash
curl -X POST "https://engine.prod.bria-api.com/v2/image/generate" \
  -H "api_token: $BRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: BriaSkills/1.2.6" \
  -d '{
    "prompt": "your description",
    "aspect_ratio": "16:9",
    "resolution": "1MP",
    "sync": true
  }'
```

**Aspect ratios**: `1:1` (square), `16:9` (hero/banner), `4:3` (presentation), `9:16` (mobile/story), `3:4` (portrait)

**Resolution**: `1MP` (default) or `4MP` (improved details for photorealism, adds ~30s latency)

**Sync mode**: Pass `"sync": true` in the request body for single image generation to get the result directly in the response. For batch/multiple image generation, omit `sync` (or set `false`) and use polling instead.

> **Advanced**: For precise, deterministic control over generation, use **[VGL structured prompts](../vgl/SKILL.md)** instead of natural language. VGL defines every visual attribute (objects, lighting, composition) as explicit JSON.

### Remove Background (RMBG-2.0)

```bash
curl -X POST "https://engine.prod.bria-api.com/v2/image/edit/remove_background" \
  -H "api_token: $BRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: BriaSkills/1.2.6" \
  -d '{"image": "https://..."}'
```

Returns PNG with transparency.

### Edit Image (FIBO-Edit) - No Mask Required

```bash
curl -X POST "https://engine.prod.bria-api.com/v2/image/edit" \
  -H "api_token: $BRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: BriaSkills/1.2.6" \
  -d '{
    "images": ["https://..."],
    "instruction": "change the mug to red"
  }'
```

### Edit Image Region with Mask (GenFill)

```bash
curl -X POST "https://engine.prod.bria-api.com/v2/image/edit/gen_fill" \
  -H "api_token: $BRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: BriaSkills/1.2.6" \
  -d '{
    "image": "https://...",
    "mask": "https://...",
    "prompt": "what to generate in masked area"
  }'
```

### Expand Image (Outpainting)

```bash
curl -X POST "https://engine.prod.bria-api.com/v2/image/edit/expand" \
  -H "api_token: $BRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: BriaSkills/1.2.6" \
  -d '{
    "image": "base64-or-url",
    "aspect_ratio": "16:9",
    "prompt": "coffee shop background, wooden table"
  }'
```

### Upscale Image

```bash
curl -X POST "https://engine.prod.bria-api.com/v2/image/edit/increase_resolution" \
  -H "api_token: $BRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: BriaSkills/1.2.6" \
  -d '{"image": "https://...", "scale": 2}'
```

### Create Product Lifestyle Shot

```bash
curl -X POST "https://engine.prod.bria-api.com/v1/product/lifestyle_shot_by_text" \
  -H "api_token: $BRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: BriaSkills/1.2.6" \
  -d '{
    "image": "https://product-with-transparent-bg.png",
    "prompt": "modern kitchen countertop, natural morning light"
  }'
```

### Integrate Products into Scene

Place one or more products at exact coordinates in a scene. Products are automatically cut out and matched to the scene's lighting and perspective.

```bash
curl -X POST "https://engine.prod.bria-api.com/image/edit/product/integrate" \
  -H "api_token: $BRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: BriaSkills/1.2.6" \
  -d '{
    "scene": "https://scene-image-url",
    "products": [
      {
        "image": "https://product-image-url",
        "coordinates": {"x": 100, "y": 200, "width": 300, "height": 400}
      }
    ]
  }'
```

---

## Response Handling

### Sync (single image generation)

For single image requests, pass `"sync": true` in the request body. The response returns the result directly — no polling needed.

### Async with polling (batch generation)

For batch or multiple image generation, omit `sync` (or set `"sync": false`). The response returns a status URL to poll:

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

Poll the status_url until `status: "COMPLETED"`, then get `result.image_url`.

```python
import requests, time

def get_result(status_url, api_key):
    while True:
        r = requests.get(status_url, headers={"api_token": api_key, "User-Agent": "BriaSkills/1.2.6"})
        data = r.json()
        if data["status"] == "COMPLETED":
            return data["result"]["image_url"]
        if data["status"] == "FAILED":
            raise Exception(data.get("error"))
        time.sleep(2)
```

---

## Prompt Engineering Tips

- **Style**: "professional product photography" vs "casual snapshot", "flat design illustration" vs "3D rende