Skip to content
/
Quickstart
Last updated

Quickstart

In this guide you will create an API token, generate an image, retrieve the result, and remove the background from an image. It takes about five minutes.

1. Get an API token

Sign in to the Bria Console and create an API token. If you are already signed in, your token appears below. Free accounts can call every endpoint at a reduced rate limit.

Get your API token

Store the token in an environment variable:

export BRIA_API_TOKEN="<your-bria-api-token>"

Every request authenticates with the api_token header. See Authentication for details.

2. Generate an image

Bria's v2 endpoints are asynchronous by default: the API accepts the job and returns a request_id and a status_url right away.

Save this as quickstart.py. uv reads the dependency block below and installs bria-client on first run — no separate install step:

# /// script
# dependencies = ["bria-client"]
# ///
from bria_client import BriaSyncClient

client = BriaSyncClient()  # reads BRIA_API_TOKEN

job = client.submit(
    endpoint="image/generate",
    payload={
        "prompt": "studio product photo of a matte black insulated travel mug on a white seamless background, soft diffused key light from the upper left, crisp edges",
        "aspect_ratio": "1:1",
    },
)
print(job.request_id, job.status_url)
uv run quickstart.py

No uv? pip install bria-client, then run the script normally — the dependency block above is just a comment and is safe to leave in.

Response (202 Accepted):

{
  "request_id": "9d4a1a2f5c7e4b6f8a0c2d3e4f5a6b7c",
  "status_url": "https://engine.prod.bria-api.com/v2/status/9d4a1a2f5c7e4b6f8a0c2d3e4f5a6b7c"
}

3. Get the result

Poll the status_url until status is COMPLETED. Generation usually takes a few seconds; poll every one to two seconds.

result = client.poll(job, interval=2, timeout=120)
print(result.result.image_url)
print(result.result.seed)

client.run(...) does submit and poll in one call when you do not need the job id.

Completed status body:

{
  "request_id": "9d4a1a2f5c7e4b6f8a0c2d3e4f5a6b7c",
  "status": "COMPLETED",
  "result": {
    "image_url": "https://.../result.png",
    "seed": 314159,
    "structured_prompt": "{\"short_description\": \"A matte black insulated travel mug ...\", ...}"
  }
}

Download the image from image_url and store it yourself. Keep the returned seed and structured_prompt: sending them back to /v2/image/generate reproduces the image exactly, and adding a short prompt refines it without changing the composition. That workflow is explained in Image Generation best practices.

Prefer a single blocking call? Add "sync": true to the request body and the endpoint returns the result directly. Prefer push over polling? Pass a webhook_url and Bria POSTs the result to you; see webhooks.

4. Edit an image

Editing endpoints accept a public image URL or a raw base64 string in the image field. Remove the background from a product photo:

from bria_client.toolkit import Image

response = client.run(
    endpoint="image/edit/remove_background",
    payload={"image": Image("https://labs-assets.bria.ai/sandbox-example-inputs/remove_background_example.jpg").as_bria_api_input},
)
print(response.result.image_url)

Image(...) also accepts a local path, a PIL image or a numpy array and encodes it for you.

The result is a PNG with a transparent background. Chain it into a packshot or a lifestyle scene to build a catalog pipeline.

Next steps

Welcome

Authentication