Bria Remove Background Guided API Documentation

Bria Remove Background Guided API Documentation

Playground

Bria Guided Remove Background removes image backgrounds with optional text guidance to control what should be preserved, producing clean transparent cutouts while retaining the original foreground pixels for product images, e-commerce assets, portraits, and design workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Bria Guided Remove Background removes image backgrounds with optional text guidance for more controlled cutouts. Provide an image and, when needed, describe which subjects or objects should be kept or removed.

Use it for product cutouts, people, props, catalog assets, advertising composites, and other workflows that need transparent-background images with more control than standard automatic background removal.

Why Choose This?

• Prompt-guided background removal
  Use natural-language instructions to describe which subjects or objects should remain in the cutout.

• Standard background removal
  Leave prompt empty when you want automatic background removal without additional guidance.

• Selective cutouts
  Guide the model toward specific people, products, props, or other visual elements.

• Existing alpha control
  Preserve transparency already present in the source image or make retained regions fully opaque.

• Multiple image input formats
  Supports JPEG, JPG, PNG, and WEBP input images.

Parameters

How to Use

1. Provide an image — Upload the source image or provide a public URL or Base64-encoded image.
2. Add guidance optional — Use prompt when you want to specify which subject, object, or group of elements should remain.
3. Configure transparency optional — Keep preserve_alpha=true to retain existing transparency, or disable it to make retained regions fully opaque.
4. Submit — Generate the background-removed image.
5. Retrieve the result — Access the generated image from the prediction outputs array.

Pricing

Pricing is fixed at $0.03 per image.

prompt and preserve_alpha do not add separate charges.

Best Use Cases

• E-commerce product cutouts — Remove backgrounds from product images for storefronts and catalogs.
• Advertising composites — Isolate people, products, or props for placement into new designs.
• People and portrait cutouts — Keep selected subjects while removing surrounding background content.
• Catalog preparation — Create clean cutouts for product and asset libraries.
• Selective background removal — Use prompt guidance when only specific visual elements should remain.

Pro Tips

• Use a clear prompt when the image contains several people or objects and only some should remain.
• Describe the subject specifically, such as only the chair or the person with the plant.
• Leave prompt empty when standard automatic background removal is sufficient.
• Keep preserve_alpha=true when existing transparency in the source image should remain.
• Set preserve_alpha=false when the retained subject should be fully opaque.

Notes

• image is required.
• prompt is optional.
• When prompt is omitted or left blank, the endpoint performs standard background removal.
• Supported input formats are JPEG, JPG, PNG, and WEBP.

Related Models

• Bria Remove Background — Automatically remove the background from an image without prompt guidance.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "preserve_alpha": true
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/bria/remove-background-guided" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters