Bria , AI Image Generation, Editing & Background Removal

Commercially safe, royalty-free image generation and editing through 20+ API endpoints. Generate images from text, edit existing images with natural language, remove or replace backgrounds, upscale resolution, and create product lifestyle shots.

intent

Use this skill to generate, edit, and transform images via Bria's API. Reach for it when a user asks to create an image from scratch ("make me a banner"), edit an existing image ("remove the person"), remove or replace backgrounds ("make it transparent", "put it in a kitchen"), upscale or enhance photos, restyle images, or create product lifestyle shots. The skill handles OAuth authentication, credential caching, and wraps 20+ API endpoints with a simple call interface. All outputs are commercially safe and royalty-free.

inputs

• BRIA_API_KEY (env var) , Primary credential for API calls. Cached in ~/.bria/credentials after first auth. Required to proceed past Step 3.
• ~/.bria/credentials (file) , Local cache storing access_token= and api_token= lines. Created during device flow auth. Delete to force re-authentication.
• curl (binary) , Required for HTTP requests. Check with which curl.
• Image file or URL , For edit endpoints: either a local file path (base64 encoded by bria_client.sh) or an absolute HTTPS URL. Not needed for /v2/image/generate.
• Device flow web browser , During Step 2 (bria_auth), user must visit the sign-in URL and confirm the user code in their Bria account dashboard. No OAuth tokens needed upfront.
• Internet connectivity , All calls are synchronous or async to Bria's servers. Network timeouts (default 60s) will fail the call.

procedure

Step 1: Check for existing credentials

Run this check to avoid unnecessary re-auth:

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

Output interpretation:

• READY → Both tokens cached. Skip to Step 4 (make API calls).
• CREDENTIALS_FOUND → Access token found but API key missing. Jump to Step 3 (bria_introspect).
• NO_CREDENTIALS → No cached tokens. Proceed to Step 2 (device flow auth).

Step 2: Authenticate via OAuth device flow

Source the auth helper and trigger device flow:

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

What bria_auth does:

1. Prints SIGN_IN_URL=<url> and USER_CODE=<6-char code>.
2. Show the user exactly this (nothing more):

   Connect your Bria account: Click here to sign in Your code is {USER_CODE} , it's already filled in.

3. Polls Bria's device endpoint every 5 seconds (internal loop).
4. On success, prints AUTHENTICATED and exits 0. Credentials are now in ~/.bria/credentials.
5. On failure or expiry, prints error message and exits non-zero.

Do not proceed to Step 3 until bria_auth prints AUTHENTICATED and exits cleanly (code 0).

If the device code expires (typically 15 minutes), re-run bria_auth to get a new code.

Step 3: Verify billing status and resolve API key

Run the introspection helper:

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

Output interpretation:

• BILLING_ERROR: <message> → Relay the message to the user verbatim. Do not proceed to Step 4. Do not retry.
• TOKEN_EXPIRED → Tell the user: "Your Bria session expired. Reconnecting..." and go back to Step 2.
• READY → Billing confirmed. BRIA_API_KEY is now cached in ~/.bria/credentials. Proceed to Step 4.

Step 4: Call the appropriate endpoint

Source the client helper and invoke bria_call:

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

# Example: Generate image from text
RESULT=$(bria_call /v2/image/generate "" '"prompt": "your description", "aspect_ratio": "16:9", "sync": true')

# Example: Remove background
RESULT=$(bria_call /v2/image/edit/remove_background "/path/to/local/image.png")

# Example: Replace background
RESULT=$(bria_call /v2/image/edit/replace_background "https://example.com/img.jpg" '"prompt": "sunset beach"')

# Example: Edit image (note --key images flag)
RESULT=$(bria_call /v2/image/edit "/path/to/image.png" --key images '"instruction": "make it look warmer"')

# Example: Upscale
RESULT=$(bria_call /v2/image/edit/increase_resolution "https://example.com/img.jpg" '"scale": 4')

# Example: 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...]

• , Start with "/" (e.g., /v2/image/generate, /v2/image/edit/remove_background).
• , Pass a local file path, absolute HTTPS URL, or empty string "" for generation-only endpoints. bria_client.sh auto-detects and base64-encodes local files.
• [--key ] , Use --key images only for /v2/image/edit (wraps image in an images array). Omit for other endpoints.
• [extra JSON fields...] , Pass any additional parameters as quoted JSON (e.g., '"scale": 4', '"prompt": "..."').

Returns: On success, prints the result image URL to stdout. On failure, prints error message to stderr and returns empty.

Step 5: Handle the response

Check the output:

if [ -z "$RESULT" ]; then
  # bria_call printed an error to stderr
  echo "Image generation failed. Check the error above."
  exit 1
else
  # $RESULT is the image URL (expires in 24 hours)
  echo "Image ready: $RESULT"
fi

Important: All generated/edited image URLs expire after 24 hours. Download and store locally if you need to keep them.

decision points

Which endpoint do I use?

• Remove background / make transparent PNG → /v2/image/edit/remove_background. Pass the image (local or URL).
• Generate image from text scratch → /v2/image/generate. Pass empty string "" as the image argument. Include "sync": true for single images, omit for batch/async jobs.
• Edit existing image with text instruction (warm it up, blur it, etc.) → /v2/image/edit. Pass the image and --key images flag. Include "instruction": "...".
• Change, replace, or blur the background → /v2/image/edit/replace_background. Pass the image and a prompt like "blur" or "sunset beach".
• Place product in a lifestyle scene → /v1/product/lifestyle_shot_by_text. Pass the product image (local or URL) and "scene_description": "...".
• Upscale / increase resolution → /v2/image/edit/increase_resolution. Pass the image and "scale": 2 or "scale": 4. Higher scale takes longer.
• Anything else (restyle, relight, reseason, restore, colorize, sketch, blend, outpaint, inpaint) → Check references/capabilities.md for the full endpoint table and matching use case.

What if the API key is missing after Step 3?

If bria_call returns empty and stderr shows "API_KEY not set", re-run Step 3 (bria_introspect) to ensure the token is cached. If that fails, delete ~/.bria/credentials and restart from Step 2.

What if the image URL is a local file?

bria_client.sh detects local paths (anything not starting with http:// or https://), reads the file, base64-encodes it, and includes it in the request. Pass the absolute path. Relative paths like ./image.png work but absolute (~/... or /home/...) is safer.

What if authentication times out or the device code expires?

The device code is valid for ~15 minutes. If polling times out, re-run bria_auth to get a fresh code. The user will see a new sign-in link. If Step 2 completes but Step 3 (bria_introspect) fails with TOKEN_EXPIRED, the access token has expired; go back to Step 2.

What if the request fails with HTTP 401?

API key is stale or invalid. Delete ~/.bria/credentials and re-authenticate from Step 2.

What if the request times out (60s+)?

Async jobs (especially upscale 4x) can take 60-90s. bria_client.sh has a built-in timeout. If it times out, the job may still be queued on Bria's side. Retry the call once. Do not retry more than twice.

What if the result is empty but no error was printed?

The endpoint may have returned an empty or null result. Check the endpoint docs in references/api-endpoints.md. For generation endpoints, ensure "sync": true is set; otherwise the job is async and you need to poll for the result (advanced).

What if the user has no active Bria subscription?

Step 3 (bria_introspect) will return BILLING_ERROR: <reason>. Relay the message to the user verbatim and stop. Do not attempt API calls.

output contract

Success output: A single image URL (string), valid for 24 hours. Example: https://api.bria.ai/v2/results/abc123def456.jpg.

File location: Not applicable. Images are hosted on Bria's CDN and returned as URLs. To persist, download the image within 24 hours and store locally.

Data format: Image URLs are direct HTTPS links. No JSON wrapper. No pagination. One request = one image (for sync=true).

Error output: Error messages printed to stderr. Examples:

• ERROR 401: Invalid API Key
• ERROR 400: Missing required field "prompt"
• TIMEOUT: Job did not complete within 60 seconds
• BILLING_ERROR: Account suspended

On success, bria_call exits 0 and prints the URL to stdout. On failure, it exits non-zero and prints the error to stderr.

outcome signal

The user knows the skill worked when:

1. bria_auth succeeds , Script prints AUTHENTICATED, exits cleanly, and ~/.bria/credentials now contains both access_token= and api_token= lines.
2. bria_introspect succeeds , Script prints READY and does not raise a BILLING_ERROR.
3. bria_call returns a URL , The call prints a valid HTTPS image URL to stdout, exits 0, and no error appears on stderr. The URL is accessible in a browser.
4. Image is ready in 5-30s , For generation and most edits, the result appears within 5-30 seconds. Upscale 4x may take 60-90s.
5. Image matches the user's request , User visually inspects the returned image and confirms it matches the prompt, instruction, or edit request.

---

troubleshooting common failures

• bria_call returns empty / no URL → BRIA_API_KEY was not set or expired. Run Step 3 (bria_introspect) to cache or refresh it.
• Async job times out → Some endpoints take 60-90s. If bria_call reports timeout, retry once; the job may have been queued server-side.
• ERROR 401 → API key is stale. Delete ~/.bria/credentials and re-authenticate from Step 2.
• BILLING_ERROR → Relay the message to the user verbatim. Do not retry API calls.
• Local file not found → Ensure the path is absolute. bria_client.sh handles base64 encoding; it does not resolve relative symlinks.
• /v2/image/edit returns wrong result → Confirm --key images flag is present. This endpoint requires the images array format.
• Network timeout (no response from Bria) → Check internet connectivity. Retry once. If persistent, Bria's API may be down.
• Invalid JSON in extra fields → Ensure all JSON values are quoted (e.g., '"prompt": "..."', not '"prompt": ...'). The outer single quotes protect the inner double quotes from shell expansion.

---

resources

• Capabilities & Prompt Recipes , Full endpoint table, use-case recipes, and prompt engineering tips
• API Endpoints Reference , Complete parameter documentation for all 20+ endpoints
• Shell Client (bria_client.sh) , bria_call helper: auth, base64, JSON, polling
• Auth Helper (bria_auth.sh) , bria_auth and bria_introspect functions
• Full API docs for agents (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

---

Credits: Original skill authored by Bria AI. Enriched for Implexa quality standards.