bria-ai

Bria — AI 图像生成、编辑与背景移除

通过 20 多个 API 端点，安全商用、免版税地生成和编辑图像。根据文本生成图像、使用自然语言编辑图像、移除背景、创建产品图，并构建自动化图像流水线。

如需了解本文档未介绍的更多端点详情，请参阅 面向 Agent 的 Bria API 参考。

何时使用此技能

当用户想要执行以下操作时，请使用此技能：

• 生成图像 — “创建一张……的图像”、“帮我制作一张横幅”、“生成一张主视觉图”、“我需要一张产品照片”
• 编辑图像 — “更换背景”、“让它看起来像冬天”、“在桌上加一个花瓶”、“移除那个人”
• 移除／替换背景 — “让背景透明”、“抠出产品”、“替换成影棚背景”
• 产品摄影 — “创建一张生活方式照片”、“把这个产品放进厨房场景”、“电商白底图”
• 增强／转换 — “放大这张图像”、“提高分辨率”、“转换成油画风格”、“改变光线”
• 批量处理／流水线 — “生成 10 张产品图像”、“处理这些图像”、“批量移除背景”

此技能涵盖 AI 图像操作的全部范围。如果用户提到图像、照片、视觉素材或任何视觉内容创作，请使用此技能。

---

可以构建的内容

• 电商产品目录 — 生成产品照片，移除背景以创建透明 PNG，将产品放入生活场景（厨房、办公室、户外），并以统一风格制作白底图
• 落地页视觉素材 — 生成主视觉图、抽象科技背景、团队照片和版块插图，全部符合你的品牌风格
• 社交媒体内容 — Instagram 帖子（1:1）、快拍／Reels（9:16）、LinkedIn 横幅（16:9）、广告创意素材——批量生成不同版本以进行 A/B 测试
• 营销活动素材 — 季节性转换（夏季→冬季）、为不同市场重新设计产品图风格、大规模创建本地化视觉素材
• 照片修复流水线 — 修复老旧受损照片，为黑白图像上色，将低分辨率照片放大至 4 倍，并自动提升画质
• 品牌素材工具包 — 移除 Logo 背景，将艺术图案融合到产品上（T 恤、马克杯），为整个产品目录创建风格统一的产品摄影素材
• AI 驱动的设计工作流 — 串联操作：生成→编辑→移除背景→放入场景→放大——全部通过 API 流水线自动完成

---

设置 — 身份验证

进行任何 API 调用之前，你需要有效的 Bria 访问令牌。

步骤 1：检查是否已有凭据

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

如果输出为 READY，直接进行 API 调用——无需进一步检查。 如果输出为 CREDENTIALS_FOUND，跳至步骤 3。 如果输出为 NO_CREDENTIALS，继续步骤 2。

步骤 2：通过设备授权进行身份验证

启动设备授权流程：

2a. 请求设备代码：

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

解析响应字段：

• device_code — 用于轮询令牌（请保留，不要向用户显示）
• user_code — 用户必须输入的代码（例如 BRIA-XXXX）
• interval — 两次轮询尝试之间的秒数

2b. 向用户展示一个登录链接。 原样告知用户以下内容，不要添加其他内容：

连接你的 Bria 账户： 点击此处登录 你的代码是 {user_code}——已自动填入。

不要展示两个链接。不要单独展示原始 URL。不要使用 API 响应中的 verification_uri。只保留一个可点击链接。

2c. 轮询令牌。 向用户显示代码后，立即开始轮询。按给定间隔尝试最多 60 次（默认 5 秒）：

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

如果输出包含 AUTHENTICATED，继续步骤 3。否则代码已过期——从步骤 2a 重新开始。

身份验证确认之前，不要进行任何 API 调用。

步骤 3：验证账单状态并解析 API 密钥

检查持有者令牌，以确认账单状态并获取用于调用 Bria API 的真实 API 密钥：

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

解读输出：

• 如果输出 BILLING_ERROR: ...，请将消息原样转达给用户，并停止。不要进行任何 API 调用。
• 如果输出 TOKEN_EXPIRED，表示会话已失效。请告知用户会话已过期，并从步骤 2 重新开始。
• 否则，BRIA_API_KEY 现在包含真实 API 密钥，并已缓存以供后续调用。请继续下一节。

---

核心能力

需求	能力	用例
根据文本生成图像	Fibo 2 Image Generate	主视觉图、产品图、插图、社交媒体图像、横幅
根据文本指令编辑图像	Fibo 2 Image Edit	更改颜色、修改对象、转换场景
在一次编辑中组合 2–4 张图像	Fibo 2 Image Edit multi-reference	将一张图像中的服装、产品、徽标、风格或背景放入另一张图像
使用蒙版编辑图像区域	GenFill/Erase	精确修复，添加／替换特定区域
移除对象及其阴影或倒影	Erase, composite: false	仅遮罩对象：“移除自行车及其阴影”
添加／替换／移除对象	基于文本的编辑	添加花瓶、将苹果替换为梨、移除桌子
移除背景（透明 PNG）	RMBG-2.0	提取主体，用于叠加、徽标、剪贴图
将完成的广告还原为图层	Ad Delayer	让已发布的创意素材可编辑、调整广告尺寸或本地化广告
替换／模糊／擦除背景	Background ops	更换、模糊或移除背景
扩展图像／扩图	Outpainting	扩展边界、更改宽高比
提升图像分辨率	Super Resolution	将分辨率提升 2 倍或 4 倍
增强图像质量	Enhancement	改善光线、色彩和细节
更改图像风格	Restyle	油画、动漫、卡通、3D 渲染
更改光线	Relight	黄金时段、聚光灯、戏剧性光效
更改季节	Reseason	春、夏、秋、冬
合成／混合图像	Image Blending	应用纹理、徽标、合并图像
修复旧照片	Restoration	修复旧照片／受损照片
为图像上色	Colorization	为黑白图像上色，或将图像转换为黑白
草图转照片	Sketch2Image	将绘图转换为逼真的照片
产品抠图	Product Cutout	从原始产品照片生成干净的透明 PNG
产品白底图	Product Packshot	在纯色／干净背景上生成标准化的 2000×2000 产品图
产品阴影	Product Shadow	为抠图添加逼真的投影或悬浮阴影
创建产品生活方式图	Lifestyle Shot	将产品放入场景中，用于电子商务
将产品融入场景	Product Integrate	在指定坐标处嵌入产品
让人物手持产品	Product Holding	人物 + 产品照片 → 人物自然手持／携带产品
让模特试穿服装	Virtual Try-On	人物 + 服装照片 → 人物穿上服装
为产品添加尺寸标注	Product Dimensions	类似电商平台的测量图，带有尺寸／重量／容量标签
构建完整产品目录	Catalog Pipeline	批量处理文件夹中的照片 → 白底图、尺寸图、生活方式图、电商平台变体图

如何调用任意端点

所有 API 调用都使用 bria_call。它会在一次函数调用中处理 URL 直传、本地文件的 base64 编码、JSON 构建、API 调用和异步轮询。API 密钥会自动从 ~/.bria/credentials 加载。

首先，加载辅助脚本 references/code-examples/bria_client.sh（相对于此技能所在目录解析）。

source <SKILL_DIR>/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')

# Generate with a photographic look (style: kodak_film, hard_flash, hazy_dreamy or rough_realism)
RESULT=$(bria_call /v2/image/generate "" '"prompt": "a woman reading on a city bus", "style": "kodak_film", "seed": 5555, "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"')

# Edit with reference images — each --image adds the next one, in order
RESULT=$(bria_call /v2/image/edit "https://example.com/man.jpg" --key images \
  --image "https://example.com/santa.png" \
  '"instruction": "dress the man in image 1 in the santa outfit from image 2"')

# Upscale (`desired_increase` is 2 or 4 — no other value. Transparency is preserved by default)
RESULT=$(bria_call /v2/image/edit/increase_resolution "https://example.com/img.jpg" '"desired_increase": 4')

# Product cutout → transparent PNG (use --key file for a local image)
CUTOUT=$(bria_call /v1/product/cutout "/path/to/raw.jpg" --key file)

# Packshot on white from the cutout URL
RESULT=$(bria_call /v1/product/packshot "$CUTOUT" --key image_url '"background_color": "#FFFFFF"')

# Lifestyle shot
RESULT=$(bria_call /v1/product/lifestyle_shot_by_text "/path/to/product.png" '"scene_description": "modern kitchen countertop"')

# Product holding — person + product photo, no prompt needed
RESULT=$(bria_call /v2/image/edit/product/holding "/path/to/person.jpg" --key person_image \
  --array-key product_images --image "https://example.com/product.png" \
  '"instruction": "Replace the paper coffee cup in her right hand with the can, logo facing the camera."')

# Virtual try-on — person + garment photo(s), no prompt needed. Send a full outfit together
# to change several items in one call.
RESULT=$(bria_call /v2/image/edit/product/virtual-tryon "/path/to/person.jpg" --key person_image \
  --array-key garment_images --image "https://example.com/blazer.png" \
  --image "https://example.com/trousers.png" \
  '"instruction": "He wears the navy blazer over the white t-shirt he already has, and the grey tailored trousers instead of his jeans."')

# Product dimensions — auto-removes background, draws measurement callouts.
# Dual cm / in labels: repeat each dimension with the same name+position in both
# units and set "units_display": "dual_slash" so they merge into one "12 cm / 4.7 in" label.
RESULT=$(bria_call /v2/image/edit/product_dimensions "/path/to/product.png" \
  '"style": "default", "units_display": "dual_slash", "dimensions": [{"name": "height", "value": 12, "unit": "cm", "position": "left"}, {"name": "height", "value": 4.7, "unit": "in", "position": "left"}, {"name": "width_bottom", "value": 6, "unit": "cm", "position": "bottom"}, {"name": "width_bottom", "value": 2.4, "unit": "in", "position": "bottom"}], "title": "Gummies Bottle", "capacity": {"value": 500, "unit": "ml"}, "weight": {"value": 250, "unit": "g", "label": "Net Weight"}')

echo "$RESULT"

调用约定： bria_call <endpoint> <image_or_empty> [--key <json_key>] [extra JSON fields...]

• 传入 URL、本地文件路径，或在不需要图像输入的端点传入 ""（空字符串）
• 如果端点需要 images 数组而不是 image，请使用 --key images
• 每张额外的参考图像都添加一次 --image <url_or_path>（--key images 时最多共 4 张）。 顺序会保留：位置参数图像是“图像 1”，第一个 --image 是“图像 2”，依此类推
• 如果端点分别指定主图像和参考图像的键（例如 person_image + product_images/garment_images），请使用 --array-key <name>： 位置参数图像会传入 --key，每个 --image 则会传入 --array-key 数组
• 额外的 JSON 字段以键值对形式追加：'"key": "value"'
• 成功时返回结果图像 URL；出错时将错误打印到 stderr

使用多张图像（2–4 张）进行编辑： 如果用户想要的效果已经存在于图片中（例如特定服装、产品、徽标或场景），而不是可以用文字描述的内容，请使用第二张图像。先放要编辑的图像，再放参考图像，并在指令中按位置引用：“给图像 1 中的男人穿上图像 2 中的圣诞老人服装”。用普通文字说明每张参考图像的用途（例如“图像 3 的背景”）。单图像编辑无需按位置说明：“将马克杯的颜色改为红色”。

生成选项： 纵横比可选 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（不能与 4MP、style_id 或 VGL 旁的参考图像一起使用）。分辨率可选 1MP（默认）或 4MP（细节更多，耗时 +30s）。要获得照片质感，请添加 "style"：kodak_film、hard_flash、hazy_dreamy 或 rough_realism。此选项仅适用于文生图，不能与 style_id、VGL、参考图像、4MP 或 lite 一起使用。传入 "sync": true 可同步生成单张图像。/v2/image/edit（基于指令的 Fibo 2 图像编辑）则相反：它总是返回一个需要轮询的 status_url，在此处使用 "sync": true 会导致网关超时。Product Holding 和 Virtual Try-On 支持 "sync": true，这样你可以等待最终图像而非轮询；无论哪种方式，bria_call 都会代为轮询，因此只有直接调用 API 时才需要考虑这一点。

高级用法：如需精确控制生成过程，请使用 vgl 技能，通过结构化 VGL JSON 提示词代替自然语言。

有关全部 20 多个端点的完整参数文档，请参阅 API 端点参考。

---

产品目录流水线（批量）

当用户想要批量生成可直接用于上架的实体产品图片时——例如“从 ./products 构建产品目录”“把这个文件夹中的照片整理成目录”“让这些图片符合 Amazon/Shopify/Etsy 的要求”——请使用捆绑的驱动程序，而不要逐个调用端点。它无需配置：不带参数运行时，会读取 ./products 并写入 ./catalog。

python3 <SKILL_DIR>/references/code-examples/build_catalog.py

对于每个产品，它会依次执行抠图 → 商品图 + 场景图（+ 尺寸图）→ 各市场渠道的变体，并生成 cutout.png、packshot.jpg、lifestyle_N.jpg、dimensions.png（有尺寸数据时）、各渠道变体，以及用于填写商品文案的 listing.json 框架。只覆盖你需要修改的选项：

python3 <SKILL_DIR>/references/code-examples/build_catalog.py \
  --input ./photos --output ./store \
  --scenes "clean marble surface, soft studio light|cozy wooden desk, warm morning light" \
  --variants amazon,shopify --dims ./dims.json

尺寸必须基于真实测量值——请询问，不要猜测。 如果没有尺寸文件，且未指定 --no-dims，驱动程序会输出 NEEDS_DIMENSIONS 并退出（代码 2）。出现这种情况时，请停止并询问用户是否愿意为每个产品提供高度/宽度（以及可选的重量/容量），格式可用 dims.json/CSV；或者重新运行并指定 --no-dims，仅跳过尺寸图。切勿编造尺寸。dims.json 格式：

{ "soap.jpg": {"title": "Hand Wash", "height_cm": 19, "width_cm": 6, "capacity_ml": 250} }

尺寸请使用厘米保存——标注会自动显示双单位 cm / in。需要运行 pip install requests Pillow。

符合市场渠道要求的变体

export_variants.py 会将一张主图（商品图或抠图）转换为符合各渠道要求的文件——满足背景、宽高比、产品占比和最低分辨率要求：

python3 <SKILL_DIR>/references/code-examples/export_variants.py \
  --input ./catalog/soap/packshot.jpg --output ./catalog/soap --channels amazon,shopify,etsy

渠道	宽高比	背景	产品占比	最低分辨率
Amazon（主图）	1:1	纯白 #FFFFFF	~85%	1600 px（≥ 3000 理想）
Shopify	1:1（+ 4:5）	白色 / 透明	~90%	2048 px
Etsy	5:4	白色 / 场景图	~85%	2000 px

完整规则：市场渠道预设。

撰写商品文案（SEO）

Bria 生成图片，不生成文字——商品文案由你（Agent）撰写。build_catalog.py 会为每个产品生成一个 listing.json 框架；图片生成后，查看每张 packshot.jpg 并填写：seo_title（≤ 60 个字符，关键词置前）、meta_description（≤ 160 个字符）、description（1–2 个段落）、bullets（4–6 条，以利益点为主）、tags（8–15 个关键词）。所有描述都必须基于可见内容——不要编造规格——并纳入已知尺寸。

---

提示词工程技巧

• 风格：“专业产品摄影”而非“随手拍”，“扁平设计插画”而非“3D 渲染”
• 光线：“柔和自然光”、“影棚灯光”、“戏剧性阴影”
• 背景：“白色影棚”、“渐变”、“模糊的办公室”、“透明”
• 构图：“居中”、“三分法”、“左侧留白以便放置文字”
• 质量关键词：“高质量”、“专业”、“商业级”、“4K”、“清晰对焦”
• 负向提示词：“模糊、质量低、像素化”、“文字、水印、徽标”

按使用场景分类的示例

主视觉横幅（16:9）： "Modern tech startup workspace with developers collaborating, bright natural lighting, clean minimal aesthetic"——加入“clean background”或“minimal”，为叠加文字留出空间

产品照片（1:1）： "Professional product photo of [item] on white studio background, soft shadows, commercial photography lighting"——然后移除背景，生成透明 PNG

演示文稿配图（16:9）： "Abstract visualization of data analytics, blue and purple gradient, modern corporate style, clean composition with space for text"——常见主题：“abstract technology”、“business collaboration”、“minimalist geometric patterns”

Instagram 帖子（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"

---

其他资源

• API 端点参考 — 完整的端点文档，包含全部 20+ 个端点的请求和响应格式
• Shell 客户端 (bria_client.sh) — 单函数辅助工具：bria_call 负责处理身份验证、base64、JSON 和轮询
• build_catalog.py — 将一组产品照片批量整理成适用于商店的目录
• export_variants.py — 将主图转换为 Amazon/Shopify/Etsy 规格的图片
• Marketplace 预设 — Amazon / Shopify / Etsy 图片规格
• 面向 Agent 的完整 API 文档 (llms.txt) — 适用于 Agent 的 Bria API 参考；当此技能的摘要不够详尽时使用

相关技能

• vgl — 为精准、确定性地控制 Fibo 图像生成编写结构化 VGL JSON 提示词
• ad-delayer — 将完成的扁平广告拆分为可编辑图层（背景、主视觉图片、徽标、文案、CTA）
• image-utils — 用于后期处理的经典图像操作（调整大小、裁剪、合成、添加水印）