Claude Skill

bria-ai

Bria.ai image API — generate from text prompts, edit with natural language, remove backgrounds for transparent PNGs, and create product lifestyle shots. Authenticates via OAuth device flow, caches credentials in ~/.bria/credentials, calls 20+ endpoints. Commercially safe, royalty

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download bria-ai-bria-skill-bria-ai-openclaw_skills_bria-ai-348d2d4.zip · 16 KB
Part of bria-ai/bria-skill — 9 skills

Install

skills CLI npx skills add https://github.com/Bria-AI/bria-skill/tree/main/bria-ai-openclaw/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.

For additional endpoint details, see the Bria API reference for agents.

When to Use This Skill

  • 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"

Setup — Authentication

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
  • READY → skip to making API calls
  • CREDENTIALS_FOUND → skip to Step 3
  • NO_CREDENTIALS → proceed to Step 2

Step 2: Authenticate via device flow

Source the auth helper and run bria_auth:

source ~/.agents/skills/bria-ai/references/code-examples/bria_auth.sh
bria_auth

bria_auth will print SIGN_IN_URL=... and USER_CODE=.... Show the user exactly this — nothing more:

Connect your Bria account: Click here to sign in Your code is — it's already filled in.

Then wait; bria_auth polls automatically and prints AUTHENTICATED when done.

If it prints an error, the code expired — run bria_auth again.

Do not proceed with any API call until authentication is confirmed.

Step 3: Verify billing status and resolve API key

source ~/.agents/skills/bria-ai/references/code-examples/bria_auth.sh
bria_introspect

Interpret output:

  • BILLING_ERROR: ... — relay the message to the user verbatim and stop. Do not make any API calls.
  • TOKEN_EXPIRED — tell the user their session expired and restart from Step 2.
  • READY — BRIA_API_KEY is now cached in ~/.bria/credentials. Proceed.

Decision Tree — Which Endpoint to Use

Transparent PNG / cutout / remove background?
  → /v2/image/edit/remove_background

Generate image from scratch (text → image)?
  → /v2/image/generate

Edit existing image with text instruction?
  → /v2/image/edit  (use --key images)

Combine 2-4 images — outfit, product, logo, style, or background from one into another?
  → /v2/image/edit  (--key images, then one --image per extra reference)

Change / replace / blur background?
  → /v2/image/edit/replace_background  (prompt: "blur" or describe new bg)

Place product in a lifestyle scene?
  → /v1/product/lifestyle_shot_by_text

Upscale / increase resolution?
  → /v2/image/edit/increase_resolution  (scale: 2 or 4)

Anything else (restyle, relight, reseason, restore, colorize, sketch, blend, outpaint)?
  → See references/capabilities.md for the full endpoint list

How to Call Any Endpoint

source ~/.agents/skills/bria-ai/references/code-examples/bria_client.sh

# Generate (no image input)
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"')

# 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
RESULT=$(bria_call /v2/image/edit/increase_resolution "https://example.com/img.jpg" '"desired_increase": 4')

# Lifestyle shot
RESULT=$(bria_call /v1/product/lifestyle_shot_by_text "/path/to/product.png" '"scene_description": "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 "" 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", …
  • Returns the result image URL on success, or prints an error to stderr

Editing with several images (2-4): put the image being edited first, references after it, and address them by position — "dress the man in image 1 in the santa outfit from image 2". Say what each reference contributes, in plain prose. Single-image edits need no positional wording.

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 a single generated image. Editing endpoints are the other way round — they answer with a status_url you poll, and "sync": true on an edit fails with a gateway timeout.

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


Common Failures

  • bria_call returns empty / no URL → BRIA_API_KEY was not set. Run Step 3 (bria_introspect) to cache it.
  • Async job times out → Some endpoints take 60–90s. If bria_call reports a timeout, retry once; the job may have been queued.
  • ERROR 401 → API key is stale. Delete ~/.bria/credentials and re-authenticate from Step 2.
  • BILLING_ERROR → Relay message to user verbatim, do not retry API calls.
  • Local file not found → Pass the absolute path; bria_client.sh handles base64 encoding automatically.
  • /v2/image/edit returns wrong result → Confirm --key images flag is present; this endpoint requires the images array format.

Resources

Related Skills

  • vgl — Structured VGL JSON prompts for precise, deterministic control over FIBO image generation
  • image-utils — Classic image manipulation (resize, crop, composite, watermarks) for post-processing
Files (bria-skill)
  • references
    • code-examples
      • bria_auth.sh 3.4 KB
        #!/bin/bash
        # bria_auth.sh — Device authorization flow and token introspection for Bria.ai.
        # Source this file, then call bria_auth to authenticate, or bria_introspect to verify.
        #
        # Usage:
        #   source ~/.agents/skills/bria-ai/references/code-examples/bria_auth.sh
        #   bria_auth        # runs full device flow; sets BRIA_ACCESS_TOKEN, BRIA_API_KEY
        #   bria_introspect  # verifies existing token; sets BRIA_API_KEY; prints BILLING_ERROR or TOKEN_EXPIRED
        
        BRIA_AUTH_BASE="${BRIA_AUTH_BASE:-https://engine.prod.bria-api.com}"
        
        bria_auth() {
          # Step 2a: request device code
          DEVICE_RESPONSE=$(curl -s -X POST "${BRIA_AUTH_BASE}/v2/auth/device/authorize" \
            -H "Content-Type: application/json")
          DEVICE_CODE=$(printf '%s' "$DEVICE_RESPONSE" | sed -n 's/.*"device_code" *: *"\([^"]*\)".*/\1/p')
          USER_CODE=$(printf '%s' "$DEVICE_RESPONSE" | sed -n 's/.*"user_code" *: *"\([^"]*\)".*/\1/p')
          INTERVAL=$(printf '%s' "$DEVICE_RESPONSE" | sed -n 's/.*"interval" *: *\([0-9]*\).*/\1/p')
          INTERVAL="${INTERVAL:-5}"
        
          if [ -z "$DEVICE_CODE" ] || [ -z "$USER_CODE" ]; then
            echo "ERROR: Failed to get device code. Response: $DEVICE_RESPONSE" >&2
            return 1
          fi
        
          # Step 2b: show user the sign-in link (caller should display this)
          echo "SIGN_IN_URL=https://platform.bria.ai/device/verify?user_code=${USER_CODE}"
          echo "USER_CODE=${USER_CODE}"
        
          # Step 2c: poll for token
          local i=0
          while [ "$i" -lt 60 ]; do
            sleep "$INTERVAL"
            TOKEN_RESPONSE=$(curl -s -X POST "${BRIA_AUTH_BASE}/v2/auth/token" \
              -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
              -d "device_code=$DEVICE_CODE")
            BRIA_ACCESS_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | sed -n 's/.*"access_token" *: *"\([^"]*\)".*/\1/p')
            if [ -n "$BRIA_ACCESS_TOKEN" ]; then
              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"
              bria_introspect
              return 0
            fi
            i=$((i + 1))
          done
        
          echo "ERROR: Authentication timed out. Code expired — run bria_auth again." >&2
          return 1
        }
        
        bria_introspect() {
          if [ -z "$BRIA_ACCESS_TOKEN" ] && [ -f "$HOME/.bria/credentials" ]; then
            BRIA_ACCESS_TOKEN=$(grep '^access_token=' "$HOME/.bria/credentials" | cut -d= -f2-)
          fi
          [ -z "$BRIA_ACCESS_TOKEN" ] && { echo "NO_CREDENTIALS"; return 1; }
        
          INTROSPECT=$(curl -s -X POST "${BRIA_AUTH_BASE}/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"
            return 1
          fi
        
          ACTIVE=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"active" *: *\([^,}]*\).*/\1/p' | tr -d ' ')
          if [ "$ACTIVE" = "false" ]; then
            printf '' > "$HOME/.bria/credentials"
            echo "TOKEN_EXPIRED"
            return 1
          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
          echo "READY"
        }
        
      • bria_client.sh 5.2 KB
        #!/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"')
        #   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"')
        #
        # Each extra --image adds the next reference image, in order: the positional image is "image 1",
        # the first --image is "image 2", and so on. Only the images array (--key images) takes references.
        #
        # 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.7"
        
        bria_call() {
          local endpoint image key extra payload result http_code body url status_url poll i img
          local references=()
          endpoint="$1"; image="$2"; shift 2
        
          key="image"; extra=""
          while [ $# -gt 0 ]; do
            case "$1" in
              --key) key="$2"; shift 2 ;;
              --image) references+=("$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 [ "$key" = "images" ]; then
            # Written one entry at a time, in argument order: the array position is how the instruction
            # addresses each image ("image 1", "image 2"), so nothing here may reorder them.
            printf '{"images": [' > "$payload"
            i=0
            # ${arr[@]+"${arr[@]}"} expands to nothing for an empty array instead of failing under `set -u`.
            for img in "$image" ${references[@]+"${references[@]}"}; do
              [ "$i" -gt 0 ] && printf ', ' >> "$payload"
              if printf '%s' "$img" | grep -qE '^https?://'; then
                printf '"%s"' "$img" >> "$payload"
              else
                [ ! -f "$img" ] && { echo "ERROR: File not found: $img" >&2; return 1; }
                printf '"' >> "$payload"
                base64 < "$img" | tr -d '\n' >> "$payload"
                printf '"' >> "$payload"
              fi
              i=$((i + 1))
            done
            printf ']' >> "$payload"
          elif printf '%s' "$image" | grep -qE '^https?://'; then
            printf '{"%s": "%s"' "$key" "$image" > "$payload"
          else
            [ ! -f "$image" ] && { echo "ERROR: File not found: $image" >&2; return 1; }
            printf '{"%s": "' "$key" > "$payload"
            base64 < "$image" | tr -d '\n' >> "$payload"
            printf '"' >> "$payload"
          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"
        }
        
    • api-endpoints.md 21.8 KB
      # 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.7`) 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",
        "seed": null,
        "style_id": "default"
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Default | Description |
      |-----------|------|---------|-------------|
      | `prompt` | string | required* | Image description (* or use `structured_prompt`) |
      | `aspect_ratio` | string | "1:1" | "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9" |
      | `resolution` | string | "1MP" | Output image resolution. "1MP" or "4MP". "4MP" improves image details, especially for photorealism, but increases latency by ~30 seconds. |
      | `negative_prompt` | string | - | What to exclude |
      | `seed` | int | random | For reproducibility |
      | `style_id` | string | "default" | Named prompt style that shapes how the prompt becomes the image. `"default"` (standard) or `"photoreal"` (tuned for photorealistic results). Optional — omit for the standard style. |
      | `structured_prompt` | string | - | JSON from previous generation (for refinement). Use with `prompt` to refine, or alone with `seed` to recreate. |
      | `images` | array | - | Reference image for inspire mode: an array holding one image URL or base64 string |
      
      **Input Combinations** — at least one of `prompt`, `images` or `structured_prompt` is required:
      - `prompt` — Generate from text
      - `images` — Generate inspired by a reference image
      - `images` + `prompt` — Generate inspired by image, guided by text
      - `structured_prompt` + `seed` — Recreate a previous image exactly
      - `structured_prompt` + `prompt` + `seed` — Refine a previous image with new instructions
      
      All combinations support `aspect_ratio`, `negative_prompt`, `seed`, and `style_id`. Note that `"sync": true`
      cannot be combined with `"resolution": "4MP"` — that pairing is rejected.
      
      **Response:**
      ```json
      {
        "request_id": "uuid",
        "status_url": "https://engine.prod.bria-api.com/v2/status/uuid"
      }
      ```
      
      **Completed Result:**
      ```json
      {
        "status": "COMPLETED",
        "result": {
          "image_url": "https://...",
          "structured_prompt": "{...}",
          "seed": 12345
        }
      }
      ```
      
      ---
      
      ## RMBG-2.0 - Background Removal
      
      ### POST /v2/image/edit/remove_background
      
      Remove background from image. Returns PNG with transparency.
      
      **Request:**
      ```json
      {
        "image": "https://publicly-accessible-image-url"
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Description |
      |-----------|------|-------------|
      | `image` | string | Source image URL (JPEG, PNG, WEBP) |
      
      **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 with a natural language instruction — no mask required. Send one image to change it,
      or 2–4 images to combine them: the subject from one with an outfit, product, style, or background
      from another.
      
      **Request:**
      ```json
      {
        "images": ["https://source-image-url"],
        "instruction": "change the mug color to red"
      }
      ```
      
      **Multi-reference request.** `images` is ordered, and the instruction addresses each entry by its
      position — the first is "image 1", the second "image 2", and so on:
      ```json
      {
        "images": ["https://man-image-url", "https://santa-outfit-image-url"],
        "instruction": "dress the man in image 1 in the santa outfit from image 2",
        "seed": 1234
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Default | Description |
      |-----------|------|---------|-------------|
      | `images` | array | required | 1–4 image URLs or base64 data URLs. **Order matters** — the instruction refers to them as "image 1", "image 2", … in the order they are sent |
      | `instruction` | string | required | Edit instruction in natural language. Refer to additional images by position |
      | `seed` | int | random | For reproducibility — the same images, instruction and seed reproduce the same result |
      | `aspect_ratio` | string | - | Output ratio: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9". Honored only with 2 or more images. Do not send it on a single-image request — the output follows that image regardless and the response carries a `warning`; to change one image's ratio, use `/v2/image/edit/expand` |
      | `model_version` | string | - | Deprecated and ignored — the service picks the edit model from the request contents. A value that is sent comes back with a notice in `warning`; omit it |
      
      **Writing a multi-reference instruction:**
      - Put the image being edited first and the references after it.
      - Say what each reference contributes ("the outfit from image 2", "the background of image 3"), not
        just that it exists.
      - Plain prose, plain words — "image 1", "image 2". No brackets, tags, or markup.
      
      This endpoint is asynchronous: it answers with `request_id` and `status_url`, which you poll. Do
      not send `"sync": true` here — an instruction edit takes longer than a single response is allowed to
      take, so a synchronous request fails with a gateway timeout even though the job itself is fine.
      
      **Constraints** — each returns 422 with a readable message:
      - More than 4 images. Trim the set before sending; the request is refused, not truncated.
      - A `mask` together with 2 or more images (masked edits are single-image only).
      - 2 or more images together with a tailored `model_id` or `model_version: FIBO_BBQ` — both of those
        run on the single-reference model.
      
      **Completed Result:**
      ```json
      {
        "status": "COMPLETED",
        "result": {
          "image_url": "https://...",
          "seed": 1234,
          "structured_prompt": "{...}",
          "warning": null
        }
      }
      ```
      
      The result also carries the structured instruction the edit was rendered from — named
      `structured_prompt` on a polled result and `structured_instruction` on an inline `"sync": true`
      response. Read whichever is present.
      
      `warning` is set when a parameter was accepted but not honored — `aspect_ratio` on a single-image
      request, a supplied `model_version`, or a tuning parameter the serving model does not read. Relay it
      to the user rather than dropping it.
      
      ### POST /v2/image/edit/gen_fill
      
      Generate content in a masked region (inpainting).
      
      **Request:**
      ```json
      {
        "image": "https://source-image-url",
        "mask": "https://mask-image-url",
        "prompt": "what to generate",
        "mask_type": "manual"
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Default | Description |
      |-----------|------|---------|-------------|
      | `image` | string | required | Source image URL |
      | `mask` | string | required | Mask URL (white=edit, black=keep) |
      | `prompt` | string | required | What to generate in masked area |
      | `mask_type` | string | "manual" | "manual" or "automatic" |
      
      **Mask Requirements:**
      - White pixels (255) = area to edit
      - Black pixels (0) = area to preserve
      - Same aspect ratio as source image
      
      ### POST /v2/image/edit/erase
      
      Remove objects defined by mask.
      
      **Request:**
      ```json
      {
        "image": "https://source-image-url",
        "mask": "https://mask-image-url"
      }
      ```
      
      ### POST /v2/image/edit/erase_foreground
      
      Remove primary subject and fill with background.
      
      **Request:**
      ```json
      {
        "image": "https://source-image-url"
      }
      ```
      
      ### POST /v2/image/edit/replace_background
      
      Replace background with AI-generated content.
      
      **Request:**
      ```json
      {
        "image": "https://source-image-url",
        "prompt": "new background description"
      }
      ```
      
      ### POST /v2/image/edit/blur_background
      
      Apply blur effect to image background.
      
      **Request:**
      ```json
      {
        "image": "https://source-image-url"
      }
      ```
      
      ### POST /v2/image/edit/expand
      
      Expand/outpaint an image to extend its boundaries.
      
      **Request:**
      ```json
      {
        "image": "base64-string-or-url",
        "aspect_ratio": "16:9",
        "prompt": "optional description for new content"
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Default | Description |
      |-----------|------|---------|-------------|
      | `image` | string | required | Source image URL or base64 string |
      | `aspect_ratio` | string \| float | - | Target ratio: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", or a float. Omit it and pass `canvas_size` instead |
      | `prompt` | string | - | Optional - describe content to generate |
      
      ### POST /v2/image/edit/enhance
      
      Enhance image quality (lighting, colors, details).
      
      **Request:**
      ```json
      {
        "image": "https://source-image-url"
      }
      ```
      
      ### POST /v2/image/edit/increase_resolution
      
      Upscale image resolution.
      
      **Request:**
      ```json
      {
        "image": "https://source-image-url",
        "desired_increase": 4,
        "preserve_alpha": true
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Default | Description |
      |-----------|------|---------|-------------|
      | `image` | string | required | Source image URL |
      | `desired_increase` | int | 2 | Upscale factor: 2 or 4 |
      | `preserve_alpha` | bool | true | Preserve transparency. Set `true` when input has an alpha channel — the API upscales and recombines the alpha server-side, so you don't need to handle it client-side. |
      
      ### POST /v1/product/cutout
      
      Remove the background from a product photo → clean transparent PNG. The `/v1/product/*` endpoints take `image_url` (URL) or `file` (base64).
      
      **Request:**
      ```json
      { "image_url": "https://…/raw.jpg" }
      ```
      Response: `{ "result_url": "https://…png" }` (synchronous).
      
      ### POST /v1/product/packshot
      
      Standardized 2000×2000 packshot on a solid/clean background.
      
      | Parameter | Type | Notes |
      |-----------|------|-------|
      | `image_url` / `file` | string | Product image (a cutout is recommended) |
      | `background_color` | string | Hex like `#FFFFFF`, or `transparent` |
      | `sku` | string | Optional label/id |
      
      Response: `{ "result_url": "…" }` (synchronous).
      
      ### POST /v1/product/shadow
      
      Add a realistic shadow to a product cutout.
      
      | Parameter | Type | Notes |
      |-----------|------|-------|
      | `image_url` / `file` | string | Product cutout |
      | `type` | string | `regular` (drop) or `float` (elliptical) |
      | `background_color` | string | Hex or `transparent` |
      | `shadow_intensity` | int | 0–100 (approx) |
      
      Response: `{ "result_url": "…" }` (synchronous).
      
      ### POST /v1/product/lifestyle_shot_by_text
      
      Place a product in a lifestyle scene using text description.
      
      **Request:**
      ```json
      {
        "file": "BASE64_ENCODED_IMAGE",
        "scene_description": "modern kitchen countertop, natural lighting",
        "placement_type": "automatic"
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Notes |
      |-----------|------|-------|
      | `image_url` / `file` | string | Product (cutout recommended) |
      | `scene_description` | string | Environment + lighting + mood |
      | `mode` | string | `base`, `high_control` (recommended), `fast` |
      | `placement_type` | string | `automatic`, `automatic_aspect_ratio`, `manual_placement`, `custom_coordinates`, `manual_padding`, `original` |
      | `aspect_ratio` | string | e.g. `1:1`, `4:5`, `16:9` (with `automatic_aspect_ratio`) |
      | `num_results` | int | Number of variations |
      | `sync` | bool | `true` returns results inline |
      | `optimize_description` | bool | Let Bria refine the prompt |
      
      Response: `{ "result": [[ "image_url", "seed", "session_id" ], …] }` — extract `result[0][0]`.
      
      ### POST /v1/product/lifestyle_shot_by_image
      
      Same as `lifestyle_shot_by_text`, but the scene comes from a reference background image instead of a text description.
      
      | Parameter | Type | Notes |
      |-----------|------|-------|
      | `image_url` / `file` | string | Product |
      | `ref_image_urls` | array | One or more background reference URLs |
      | `placement_type` | string | see above |
      | `num_results` | int | variations |
      
      Response: `{ "result": [[ "image_url", … ], …] }`.
      
      ### POST /v2/image/edit/product/integrate
      
      Integrate and embed one or more products into a predefined scene at precise user-defined coordinates. The product is automatically matched to the scene's lighting, perspective, and aesthetics. Products are automatically cut out from their background as part of the pipeline.
      
      **Request:**
      ```json
      {
        "scene": "https://scene-image-url",
        "products": [
          {
            "image": "https://product-image-url",
            "coordinates": {
              "x": 100,
              "y": 200,
              "width": 300,
              "height": 400
            }
          }
        ],
        "seed": 42
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Default | Description |
      |-----------|------|---------|-------------|
      | `scene` | string | required | Scene image URL or base64. Accepted formats: jpeg, jpg, png, webp |
      | `products` | array | required | Array of product objects (1 to N products) |
      | `products[].image` | string | required | Product image URL or base64. If it has an alpha channel, no cutout is applied; otherwise automatic cutout is applied |
      | `products[].coordinates` | object | required | Placement and scaling of the product within the scene |
      | `products[].coordinates.x` | int | required | X-coordinate of the product's top-left corner (pixels) |
      | `products[].coordinates.y` | int | required | Y-coordinate of the product's top-left corner (pixels) |
      | `products[].coordinates.width` | int | required | Desired product width in pixels (must not exceed scene dimensions) |
      | `products[].coordinates.height` | int | required | Desired product height in pixels (must not exceed scene dimensions) |
      | `seed` | int | random | Seed for deterministic generation |
      
      **Response:**
      ```json
      {
        "request_id": "uuid",
        "result": {
          "image_url": "https://..."
        }
      }
      ```
      
      **Async Response (202):**
      ```json
      {
        "request_id": "uuid",
        "status_url": "https://..."
      }
      ```
      
      ### POST /v2/image/edit/product/generate/dimensions
      
      Render a marketplace-ready dimension image from a product photo. (The older
      `/v2/image/edit/product_dimensions` path still works but is deprecated — use this one.)
      
      How it works: the background is removed automatically, then measurement callout lines + labels are drawn around the product, with an optional title and optional weight/capacity text. Three visual styles. Useful for e-commerce listings (Amazon-style "dimensions" images).
      
      **Request:**
      ```json
      {
        "image": "https://product-image-url",
        "style": "default",
        "dimensions": [
          {"name": "height", "value": 12, "unit": "cm", "position": "left"},
          {"name": "width_bottom", "value": 6, "unit": "cm", "position": "bottom"}
        ],
        "title": "Gummies Bottle",
        "weight": {"value": 250, "unit": "g", "label": "Net Weight"},
        "capacity": {"value": 500, "unit": "ml"},
        "background": "white",
        "output_format": "png"
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Default | Description |
      |-----------|------|---------|-------------|
      | `image` | string | required | Product photo URL or base64. Background is removed automatically — no pre-cutout needed |
      | `dimensions` | array | required | One or more dimension callouts (min 1) |
      | `dimensions[].name` | string | required | `height`, `width_bottom`, or `width_top` (`length`/`depth` not currently enabled) |
      | `dimensions[].value` | float | required | Physical measurement value (must be > 0) |
      | `dimensions[].unit` | string | required | `mm`, `cm`, `m`, `in`, `"` (inches), `ft`, `'` (feet) |
      | `dimensions[].position` | string | per-name | Callout side: `top`, `bottom`, `left`, `right`. Defaults: height→`left`, width_bottom→`bottom`, width_top→`top` |
      | `style` | string | required | `default`, `childlike`, or `elegant` |
      | `units_display` | string | "single" | `single`, `dual_bullet`, `dual_slash`, `dual_parens`. For dual modes, supply two `dimensions` entries with the same `name`+`position` but different `unit` (e.g. `in` and `cm`) — they merge into one dual-unit label |
      | `background` | string | "white" | `white`, `cream`, `charcoal`, or a hex color (e.g. `#f5f0e8`) |
      | `title` | string | - | Optional headline above the product (max 80 chars) |
      | `title_position` | string | "top_center" | `top_left`, `top_center`, `top_right` |
      | `weight` | object | - | Optional weight callout below the product |
      | `weight.value` | float | required* | Weight value (> 0) *if `weight` is provided |
      | `weight.unit` | string | required* | `lb`, `oz`, `g`, `kg` |
      | `weight.label` | string | "Weight" | `Weight` or `Net Weight` |
      | `capacity` | object | - | Optional capacity callout below the product |
      | `capacity.value` | float | required* | Capacity value (> 0) *if `capacity` is provided |
      | `capacity.unit` | string | required* | `fl_oz`, `ml`, `l`, `qt`, `gal`, `cups` |
      | `output_format` | string | "png" | `png`, `jpeg`, or `dual` (composite PNG + a transparent overlay-only PNG, returned as two images) |
      | `output_size` | int | 2200 | Square output edge length in px (256–2200) |
      | `proportional_lines` | bool | true | Scale each dimension line's length to its measurement (the largest per axis spans the product) |
      
      **Async Response (202):**
      ```json
      {
        "request_id": "uuid",
        "status_url": "https://..."
      }
      ```
      
      Poll `status_url` for the result. `dual` output returns two images: `[composite, overlay]`.
      
      ---
      
      ## Text-Based Object Editing
      
      ### POST /v2/image/edit/add_object_by_text
      
      Add a new object to an image using natural language.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url",
        "instruction": "Place a red vase with flowers on the table"
      }
      ```
      
      ### POST /v2/image/edit/replace_object_by_text
      
      Replace an existing object with a new one.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url",
        "instruction": "Replace the red apple with a green pear"
      }
      ```
      
      ### POST /v2/image/edit/erase_by_text
      
      Remove a specific object by name.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url",
        "object_name": "table"
      }
      ```
      
      ---
      
      ## Image Transformation
      
      ### POST /v2/image/edit/blend
      
      Blend/merge images or apply textures.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url",
        "instruction": "Place the art from this image on the shirt, keep the art exactly the same"
      }
      ```
      
      ### POST /v2/image/edit/reseason
      
      Change the season or weather of an image.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url",
        "season": "winter"
      }
      ```
      
      **Seasons:** `spring`, `summer`, `autumn`, `winter`
      
      ### POST /v2/image/edit/restyle
      
      Transform the artistic style of an image.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url",
        "style": "oil_painting"
      }
      ```
      
      **Style IDs:** `render_3d`, `cubism`, `oil_painting`, `anime`, `cartoon`, `coloring_book`, `retro_ad`, `pop_art_halftone`, `vector_art`, `story_board`, `art_nouveau`, `cross_etching`, `wood_cut`
      
      ### POST /v2/image/edit/relight
      
      Modify the lighting setup of an image.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url",
        "light_type": "sunrise light",
        "light_direction": "front"
      }
      ```
      
      **Parameters:**
      
      | Parameter | Type | Default | Description |
      |-----------|------|---------|-------------|
      | `image` | string | required | Source image URL or base64 |
      | `light_type` | string | "soft overcast daylight lighting" | Lighting preset (see values below) |
      | `light_direction` | string | required | `front`, `side`, `bottom`, `top-down` |
      
      **Light Types:** `midday`, `blue hour light`, `low-angle sunlight`, `sunrise light`, `spotlight on subject`, `overcast light`, `soft overcast daylight lighting`, `cloud-filtered lighting`, `fog-diffused lighting`, `side lighting`, `moonlight lighting`, `starlight nighttime`, `soft bokeh lighting`, `harsh studio lighting`
      
      ---
      
      ## Image Restoration & Conversion
      
      ### POST /v2/image/edit/sketch_to_colored_image
      
      Convert a sketch or line drawing to a photorealistic image.
      
      **Request:**
      ```json
      {
        "image": "sketch-base64-or-url"
      }
      ```
      
      ### POST /v2/image/edit/restore
      
      Restore old/damaged photos by removing noise, scratches, and blur.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url"
      }
      ```
      
      ### POST /v2/image/edit/colorize
      
      Add color to B&W photos or convert to B&W.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url",
        "color": "contemporary color"
      }
      ```
      
      **Colors:** `contemporary color`, `vivid color`, `black and white colors`, `sepia vintage`
      
      ### POST /v2/image/edit/crop_foreground
      
      Remove background and crop tightly around the foreground.
      
      **Request:**
      ```json
      {
        "image": "base64-or-url"
      }
      ```
      
      ---
      
      ## Structured Instructions
      
      ### POST /v2/structured_instruction/generate
      
      Generate a structured JSON instruction from natural language (no image generated).
      
      **Request:**
      ```json
      {
        "images": ["base64-or-url"],
        "instruction": "change to golden hour lighting",
        "mask": "optional-mask-url"
      }
      ```
      
      **Returns:** `structured_instruction` JSON that can be passed to `/v2/image/edit`
      
      ---
      
      ## Status Polling
      
      ### GET /v2/status/{request_id}
      
      Check async request status.
      
      **Response:**
      ```json
      {
        "status": "IN_PROGRESS | COMPLETED | ERROR",
        "result": {
          "image_url": "https://..."
        },
        "request_id": "uuid"
      }
      ```
      
      **Status Values:**
      - `IN_PROGRESS` - Still processing
      - `COMPLETED` - Success, result available
      - `ERROR` - The request failed (this is the literal value; there is no `FAILED`)
      - `UNKNOWN` - No such request id
      
      **Polling Pattern:**
      ```python
      import requests, time
      
      def poll(status_url, api_key, timeout=120):
          headers = {"api_token": api_key, "User-Agent": "BriaSkills/1.3.7"}
          for _ in range(timeout // 2):
              r = requests.get(status_url, headers=headers)
              data = r.json()
              if data["status"] == "COMPLETED":
                  return data["result"]["image_url"]
              if data["status"] in ("ERROR", "UNKNOWN"):
                  raise Exception(data.get("error"))
              time.sleep(2)
          raise TimeoutError()
      ```
      
      ---
      
      ## Error Handling
      
      ### HTTP Status Codes
      
      | Code | Description |
      |------|-------------|
      | 200 | Success |
      | 400 | Bad request |
      | 401 | Unauthorized - invalid API key |
      | 415 | Unsupported media type |
      | 422 | Validation failed / Content moderation blocked |
      | 429 | Rate limited |
      | 500 | Server error |
      
      ### Supported Image Formats
      
      - **Input:** JPEG, JPG, PNG, WEBP (RGB, RGBA, CMYK)
      - **Output:** PNG (with transparency where applicable)
      
    • capabilities.md 4.1 KB
      # Bria Capabilities Reference
      
      ## 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
      
      ---
      
      ## Full Capabilities Table
      
      | Need | Capability | Endpoint |
      |------|------------|----------|
      | Generate images from text | FIBO Generate | `/v2/image/generate` |
      | Edit images by text instruction | FIBO-Edit | `/v2/image/edit` |
      | Combine 2-4 images in one edit | FIBO-Edit multi-reference | `/v2/image/edit` (ordered `images` array) |
      | Edit image region with mask | GenFill/Erase | `/v2/image/edit/gen_fill` |
      | Add/Replace/Remove objects | Text-based editing | `/v2/image/edit` |
      | Remove background (transparent PNG) | RMBG-2.0 | `/v2/image/edit/remove_background` |
      | Replace/blur/erase background | Background ops | `/v2/image/edit/replace_background` |
      | Expand/outpaint images | Outpainting | `/v2/image/edit/expand` |
      | Upscale image resolution | Super Resolution | `/v2/image/edit/increase_resolution` |
      | Enhance image quality | Enhancement | `/v2/image/edit/enhance` |
      | Restyle images | Restyle | `/v2/image/edit/restyle` |
      | Change lighting | Relight | `/v2/image/edit/relight` |
      | Change season | Reseason | `/v2/image/edit/reseason` |
      | Composite/blend images | Image Blending | `/v2/image/edit/blend` |
      | Restore old photos | Restoration | `/v2/image/edit/restore` |
      | Colorize images | Colorization | `/v2/image/edit/colorize` |
      | Sketch to photo | Sketch2Image | `/v2/image/edit/sketch_to_colored_image` |
      | Create product lifestyle shots | Lifestyle Shot | `/v1/product/lifestyle_shot_by_text` |
      | Integrate products into scenes | Product Integrate | `/v2/image/edit/product/integrate` |
      
      ---
      
      ## 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"`
      
  • LICENSE.txt 1.3 KB
    MIT License
    
    Copyright (c) 2025
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    
    ---
    
    Note: This skill integrates with Bria.ai's API. Usage of the Bria.ai API is
    subject to Bria.ai's Terms of Service and API usage policies. The Bria.ai
    API and associated models are commercial products - please refer to
    https://bria.ai for licensing and pricing information.
    
  • SKILL.md 8.2 KB
    ---
    name: bria-ai
    description: >
      Bria.ai image API — generate from text prompts, edit with natural language,
      remove backgrounds for transparent PNGs, and create product lifestyle shots.
      Authenticates via OAuth device flow, caches credentials in ~/.bria/credentials,
      calls 20+ endpoints. Commercially safe, royalty-free.
      Triggers on: remove background, transparent PNG, cutout, generate image, create banner,
      edit photo, product photography, upscale, restyle, inpainting, outpainting,
      lifestyle shot, background replacement, object removal, photo restoration.
    license: MIT
    homepage: https://bria.ai
    metadata:
      author: Bria AI
      version: "1.3.7"
      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.
    
    For additional endpoint details, see the [Bria API reference for agents](https://docs.bria.ai/llms.txt).
    
    ## When to Use This Skill
    
    - **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"
    
    ---
    
    ## Setup — Authentication
    
    ### 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
    ```
    
    - `READY` → skip to making API calls
    - `CREDENTIALS_FOUND` → skip to Step 3
    - `NO_CREDENTIALS` → proceed to Step 2
    
    ### Step 2: Authenticate via device flow
    
    Source the auth helper and run `bria_auth`:
    
    ```bash
    source ~/.agents/skills/bria-ai/references/code-examples/bria_auth.sh
    bria_auth
    ```
    
    `bria_auth` will print `SIGN_IN_URL=...` and `USER_CODE=...`. Show the user exactly this — nothing more:
    
    > **Connect your Bria account:** [Click here to sign in]({SIGN_IN_URL})
    > Your code is **{USER_CODE}** — it's already filled in.
    
    Then wait; `bria_auth` polls automatically and prints `AUTHENTICATED` when done.
    
    If it prints an error, the code expired — run `bria_auth` again.
    
    **Do not proceed with any API call until authentication is confirmed.**
    
    ### Step 3: Verify billing status and resolve API key
    
    ```bash
    source ~/.agents/skills/bria-ai/references/code-examples/bria_auth.sh
    bria_introspect
    ```
    
    Interpret output:
    - `BILLING_ERROR: ...` — relay the message to the user verbatim and **stop**. Do not make any API calls.
    - `TOKEN_EXPIRED` — tell the user their session expired and restart from Step 2.
    - `READY` — `BRIA_API_KEY` is now cached in `~/.bria/credentials`. Proceed.
    
    ---
    
    ## Decision Tree — Which Endpoint to Use
    
    ```
    Transparent PNG / cutout / remove background?
      → /v2/image/edit/remove_background
    
    Generate image from scratch (text → image)?
      → /v2/image/generate
    
    Edit existing image with text instruction?
      → /v2/image/edit  (use --key images)
    
    Combine 2-4 images — outfit, product, logo, style, or background from one into another?
      → /v2/image/edit  (--key images, then one --image per extra reference)
    
    Change / replace / blur background?
      → /v2/image/edit/replace_background  (prompt: "blur" or describe new bg)
    
    Place product in a lifestyle scene?
      → /v1/product/lifestyle_shot_by_text
    
    Upscale / increase resolution?
      → /v2/image/edit/increase_resolution  (scale: 2 or 4)
    
    Anything else (restyle, relight, reseason, restore, colorize, sketch, blend, outpaint)?
      → See references/capabilities.md for the full endpoint list
    ```
    
    ---
    
    ## How to Call Any Endpoint
    
    ```bash
    source ~/.agents/skills/bria-ai/references/code-examples/bria_client.sh
    
    # Generate (no image input)
    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"')
    
    # 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
    RESULT=$(bria_call /v2/image/edit/increase_resolution "https://example.com/img.jpg" '"desired_increase": 4')
    
    # Lifestyle shot
    RESULT=$(bria_call /v1/product/lifestyle_shot_by_text "/path/to/product.png" '"scene_description": "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 `""` 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", …
    - Returns the result image URL on success, or prints an error to stderr
    
    **Editing with several images (2-4):** put the image being edited first, references after it, and
    address them by position — *"dress the man in image 1 in the santa outfit from image 2"*. Say what
    each reference contributes, in plain prose. Single-image edits need no positional wording.
    
    **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 a single generated image. Editing endpoints are the other way round —
    they answer with a `status_url` you poll, and `"sync": true` on an edit fails with a gateway
    timeout.
    
    > **Advanced**: For precise control over generation, use the **vgl** skill for structured VGL JSON prompts.
    
    ---
    
    ## Common Failures
    
    - **`bria_call` returns empty / no URL** → `BRIA_API_KEY` was not set. Run Step 3 (`bria_introspect`) to cache it.
    - **Async job times out** → Some endpoints take 60–90s. If `bria_call` reports a timeout, retry once; the job may have been queued.
    - **ERROR 401** → API key is stale. Delete `~/.bria/credentials` and re-authenticate from Step 2.
    - **`BILLING_ERROR`** → Relay message to user verbatim, do not retry API calls.
    - **Local file not found** → Pass the absolute path; `bria_client.sh` handles base64 encoding automatically.
    - **`/v2/image/edit` returns wrong result** → Confirm `--key images` flag is present; this endpoint requires the images array format.
    
    ---
    
    ## Resources
    
    - **[Capabilities & Prompt Recipes](references/capabilities.md)** — Full endpoint table, use-case recipes, and prompt engineering tips
    - **[API Endpoints Reference](references/api-endpoints.md)** — Complete parameter documentation for all 20+ endpoints
    - **[Shell Client (bria_client.sh)](references/code-examples/bria_client.sh)** — `bria_call` helper: auth, base64, JSON, polling
    - **[Auth Helper (bria_auth.sh)](references/code-examples/bria_auth.sh)** — `bria_auth` and `bria_introspect` functions
    - **[Full API docs for agents (llms.txt)](https://docs.bria.ai/llms.txt)** — Agent-ready Bria API reference
    
    ## Related Skills
    
    - **vgl** — Structured VGL JSON prompts for precise, deterministic control over FIBO image generation
    - **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.

Related