Claude Skill

bria-ai

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 va

LLM Mart · 0 points · 3 views 53 listing impressions 0 install-command copies
Download Bria-AI-bria-skill-skills_bria-ai-d5f08b6.zip · 29 KB

Install

skills CLI npx skills add https://github.com/Bria-AI/bria-skill/tree/main/skills/bria-ai
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install bria-ai-bria-skill@llmmart
Git git clone https://github.com/Bria-AI/bria-skill.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole bria-ai/bria-skill collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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.

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

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:

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 Your code is — 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):

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:

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

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 2 Image Generate Hero images, product shots, illustrations, social media images, banners
Edit images by text instruction Fibo 2 Image Edit Change colors, modify objects, transform scenes
Combine 2–4 images in one edit Fibo 2 Image Edit multi-reference Put the outfit, product, logo, style, or background of one image into another
Edit image region with mask GenFill/Erase Precise inpainting, add/replace specific regions
Remove an object and its shadow or reflection Erase, composite: false Mask only the object: "remove the bike and its shadow"
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
Turn a finished ad back into layers Ad Delayer make a shipped creative editable, resize or localise an ad
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
Product cutout Product Cutout Clean transparent PNG from a raw product photo
Product packshot Product Packshot Standardized 2000×2000 shot on a solid/clean background
Product shadow Product Shadow Add a realistic drop or float shadow to a cutout
Create product lifestyle shots Lifestyle Shot Place products in scenes for e-commerce
Integrate products into scenes Product Integrate Embed products at exact coordinates
Put a product in someone's hands Product Holding Person + product photo → person naturally holding/carrying it
Put garments on a model Virtual Try-On Person + garment photo(s) → person wearing them
Add dimension callouts to products Product Dimensions Marketplace-style measurement images with size/weight/capacity labels
Build a full product catalog Catalog Pipeline Batch a folder of photos → packshots, dimensions, lifestyle, marketplace variants

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.

First, source the helper script at references/code-examples/bria_client.sh (resolve relative to this skill's directory).

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"

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
  • Add --image <url_or_path> once per extra reference image (--key images, up to 4 in total). Order is preserved: the positional image is "image 1", the first --image is "image 2", …
  • Use --array-key <name> when an endpoint keys the main image and its references separately (e.g. person_image + product_images/garment_images): the positional image goes under --key, and every --image goes into the --array-key array instead
  • Extra JSON fields are appended as key-value pairs: '"key": "value"'
  • Returns the result image URL on success, or prints an error to stderr

Editing with several images (2–4): reach for a second image when the look the user wants already exists as a picture — a specific outfit, product, logo, or scene — instead of something you can describe in words. Put the image being edited first, references after it, and address them by position in the instruction: "dress the man in image 1 in the santa outfit from image 2". Say what each reference contributes ("the background of image 3"), in plain prose. A single-image edit needs no positional wording: "change the mug color to red".

Generation options: Aspect ratios 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, plus 16:10, 10:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3, 4:1, 1:4, 5:1, 1:5 (not with 4MP, a style_id, or a reference image beside a VGL). Resolution 1MP (default) or 4MP (more detail, +30s). For a photographic look, add "style": kodak_film, hard_flash, hazy_dreamy or rough_realism. It is text-to-image only, so not with style_id, a VGL, reference images, 4MP or lite. Pass "sync": true for a single generated image. /v2/image/edit (instruction-based Fibo 2 Image Edit) is the other way round — it always answers with a status_url you poll, and "sync": true there fails with a gateway timeout. Product Holding and Virtual Try-On accept "sync": true if you'd rather wait for the final image than poll — bria_call polls for you either way, so this only matters if you're calling the API directly.

Advanced: For precise control over generation, use the vgl skill for structured VGL JSON prompts instead of natural language.

See API Endpoints Reference for full parameter documentation on all 20+ endpoints.


Product Catalog Pipeline (batch)

When the user wants listing-ready imagery for physical products at scale — "build a product catalog from ./products", "turn this folder of photos into a catalog", "make these Amazon/Shopify/Etsy compliant" — use the bundled driver instead of calling endpoints one by one. It is zero-config: with no arguments it reads ./products and writes ./catalog.

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

Per product it runs cutout → packshot + lifestyle scenes (+ dimensions) → marketplace variants and writes cutout.png, packshot.jpg, lifestyle_N.jpg, dimensions.png (when measurements are available), per-channel variants, and a listing.json copy scaffold. Override only what you need:

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

Dimensions need real measurements — ask, don't guess. With no measurements file and no --no-dims, the driver prints NEEDS_DIMENSIONS and exits (code 2). When that happens, stop and ask the user to either provide height/width (and optional weight/capacity) per product — as a dims.json/CSV — or re-run with --no-dims to skip only the dimensions image. Never fabricate sizes. dims.json format:

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

Store measurements in cm — callouts render dual cm / in automatically. Requires pip install requests Pillow.

Marketplace-ready variants

export_variants.py turns one master image (packshot or cutout) into a compliant file per channel — enforcing background, aspect ratio, product fill, and minimum resolution:

python3 <SKILL_DIR>/references/code-examples/export_variants.py \
  --input ./catalog/soap/packshot.jpg --output ./catalog/soap --channels amazon,shopify,etsy
Channel Aspect Background Product fill Min resolution
Amazon (main) 1:1 pure white #FFFFFF ~85% 1600 px (≥ 3000 ideal)
Shopify 1:1 (+ 4:5) white / transparent ~90% 2048 px
Etsy 5:4 white / lifestyle ~85% 2000 px

Full rules: Marketplace Presets.

Write the listing copy (SEO)

Bria generates images, not text — you, the agent, write the copy. build_catalog.py writes a listing.json scaffold per product; after the images are generated, view each packshot.jpg and fill it: seo_title (≤ 60 chars, keyword-first), meta_description (≤ 160 chars), description (1–2 paragraphs), bullets (4–6 benefit-led), tags (8–15 keywords). Ground every claim in what's visible — don't invent specs — and fold in any known dimensions.


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

Related Skills

  • vgl — Write structured VGL JSON prompts for precise, deterministic control over Fibo image generation
  • ad-delayer — Take a finished, flat ad apart into editable layers (background, hero image, logo, copy, CTA)
  • image-utils — Classic image manipulation (resize, crop, composite, watermarks) for post-processing
Files (bria-skill)
  • references
    • code-examples
      • bria_client.sh 7 KB
        Loading…
      • build_catalog.py 11.6 KB
        Loading…
      • export_variants.py 4.1 KB
        Loading…
    • api-endpoints.md 32.6 KB
      Loading…
    • marketplace-presets.md 2.2 KB
      Loading…
  • LICENSE.txt 1.3 KB
    Loading…
  • SKILL.md 22.3 KB
    ---
    name: bria-ai
    description: 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.
    license: MIT
    metadata:
      author: Bria AI
      version: "1.4.0"
    ---
    
    # 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 "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
    ```
    
    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 2 Image Generate | Hero images, product shots, illustrations, social media images, banners |
    | Edit images by text instruction | Fibo 2 Image Edit | Change colors, modify objects, transform scenes |
    | Combine 2–4 images in one edit | Fibo 2 Image Edit multi-reference | Put the outfit, product, logo, style, or background of one image into another |
    | Edit image region with mask | GenFill/Erase | Precise inpainting, add/replace specific regions |
    | Remove an object and its shadow or reflection | Erase, `composite: false` | Mask only the object: "remove the bike and its shadow" |
    | 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 |
    | Turn a finished ad back into layers | Ad Delayer |  make a shipped creative editable, resize or localise an ad |
    | 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 |
    | Product cutout | Product Cutout | Clean transparent PNG from a raw product photo |
    | Product packshot | Product Packshot | Standardized 2000×2000 shot on a solid/clean background |
    | Product shadow | Product Shadow | Add a realistic drop or float shadow to a cutout |
    | Create product lifestyle shots | Lifestyle Shot | Place products in scenes for e-commerce |
    | Integrate products into scenes | Product Integrate | Embed products at exact coordinates |
    | Put a product in someone's hands | Product Holding | Person + product photo → person naturally holding/carrying it |
    | Put garments on a model | Virtual Try-On | Person + garment photo(s) → person wearing them |
    | Add dimension callouts to products | Product Dimensions | Marketplace-style measurement images with size/weight/capacity labels |
    | Build a full product catalog | Catalog Pipeline | Batch a folder of photos → packshots, dimensions, lifestyle, marketplace variants |
    
    ## 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`.
    
    **First**, source the helper script at `references/code-examples/bria_client.sh` (resolve relative to this skill's directory).
    
    ```bash
    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"
    ```
    
    **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`
    - Add `--image <url_or_path>` once per extra reference image (`--key images`, up to 4 in total).
      Order is preserved: the positional image is "image 1", the first `--image` is "image 2", …
    - Use `--array-key <name>` when an endpoint keys the main image and its references separately
      (e.g. `person_image` + `product_images`/`garment_images`): the positional image goes under
      `--key`, and every `--image` goes into the `--array-key` array instead
    - Extra JSON fields are appended as key-value pairs: `'"key": "value"'`
    - Returns the result image URL on success, or prints an error to stderr
    
    **Editing with several images (2–4):** reach for a second image when the look the user wants
    already exists as a picture — a specific outfit, product, logo, or scene — instead of something you
    can describe in words. Put the image being edited first, references after it, and address them by
    position in the instruction: *"dress the man in image 1 in the santa outfit from image 2"*. Say what
    each reference contributes ("the background of image 3"), in plain prose. A single-image edit needs
    no positional wording: *"change the mug color to red"*.
    
    **Generation options:** Aspect ratios `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, plus `16:10`, `10:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3`, `4:1`, `1:4`, `5:1`, `1:5` (not with `4MP`, a `style_id`, or a reference image beside a VGL). Resolution `1MP` (default) or `4MP` (more detail, +30s). For a photographic look, add `"style"`: `kodak_film`, `hard_flash`, `hazy_dreamy` or `rough_realism`. It is text-to-image only, so not with `style_id`, a VGL, reference images, `4MP` or lite. Pass `"sync": true` for a single generated image. `/v2/image/edit` (instruction-based Fibo 2 Image Edit) is the other way round — it always answers with a `status_url` you poll, and `"sync": true` there fails with a gateway
    timeout. Product Holding and Virtual Try-On accept `"sync": true` if you'd rather wait for the final image than poll — `bria_call` polls for you either way, so this only matters if you're calling the API directly.
    
    > **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.
    
    ---
    
    ## Product Catalog Pipeline (batch)
    
    When the user wants **listing-ready imagery for physical products at scale** — "build a product catalog from ./products", "turn this folder of photos into a catalog", "make these Amazon/Shopify/Etsy compliant" — use the bundled driver instead of calling endpoints one by one. It is **zero-config**: with no arguments it reads `./products` and writes `./catalog`.
    
    ```bash
    python3 <SKILL_DIR>/references/code-examples/build_catalog.py
    ```
    
    Per product it runs **cutout → packshot + lifestyle scenes (+ dimensions) → marketplace variants** and writes `cutout.png`, `packshot.jpg`, `lifestyle_N.jpg`, `dimensions.png` (when measurements are available), per-channel variants, and a `listing.json` copy scaffold. Override only what you need:
    
    ```bash
    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
    ```
    
    **Dimensions need real measurements — ask, don't guess.** With no measurements file and no `--no-dims`, the driver prints `NEEDS_DIMENSIONS` and exits (code 2). When that happens, stop and ask the user to either provide height/width (and optional weight/capacity) per product — as a `dims.json`/CSV — or re-run with `--no-dims` to skip only the dimensions image. Never fabricate sizes. `dims.json` format:
    
    ```json
    { "soap.jpg": {"title": "Hand Wash", "height_cm": 19, "width_cm": 6, "capacity_ml": 250} }
    ```
    
    Store measurements in **cm** — callouts render dual **`cm / in`** automatically. Requires `pip install requests Pillow`.
    
    ### Marketplace-ready variants
    
    `export_variants.py` turns one master image (packshot or cutout) into a compliant file per channel — enforcing background, aspect ratio, product fill, and minimum resolution:
    
    ```bash
    python3 <SKILL_DIR>/references/code-examples/export_variants.py \
      --input ./catalog/soap/packshot.jpg --output ./catalog/soap --channels amazon,shopify,etsy
    ```
    
    | Channel | Aspect | Background | Product fill | Min resolution |
    |---------|--------|------------|--------------|----------------|
    | Amazon (main) | 1:1 | pure white `#FFFFFF` | ~85% | 1600 px (≥ 3000 ideal) |
    | Shopify | 1:1 (+ 4:5) | white / transparent | ~90% | 2048 px |
    | Etsy | 5:4 | white / lifestyle | ~85% | 2000 px |
    
    Full rules: **[Marketplace Presets](references/marketplace-presets.md)**.
    
    ### Write the listing copy (SEO)
    
    Bria generates images, not text — **you, the agent, write the copy**. `build_catalog.py` writes a `listing.json` scaffold per product; after the images are generated, **view each `packshot.jpg`** and fill it: `seo_title` (≤ 60 chars, keyword-first), `meta_description` (≤ 160 chars), `description` (1–2 paragraphs), `bullets` (4–6 benefit-led), `tags` (8–15 keywords). Ground every claim in what's visible — don't invent specs — and fold in any known dimensions.
    
    ---
    
    ## 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
    - **[build_catalog.py](references/code-examples/build_catalog.py)** — Batch a folder of product photos into a store-ready catalog
    - **[export_variants.py](references/code-examples/export_variants.py)** — Turn a master image into Amazon/Shopify/Etsy variants
    - **[Marketplace Presets](references/marketplace-presets.md)** — Amazon / Shopify / Etsy image specs
    - **[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
    - **ad-delayer** — Take a finished, flat ad apart into editable layers (background, hero image, logo, copy, CTA)
    - **image-utils** — Classic image manipulation (resize, crop, composite, watermarks) for post-processing
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.