# 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](/getting-started/rate-limits-and-errors).

div
[Get your API token](https://platform.bria.ai/organization-management/api-keys)

Store the token in an environment variable:

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

Every request authenticates with the `api_token` header. See [Authentication](/getting-started/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.

Python SDK
Save this as `quickstart.py`. [uv](https://docs.astral.sh/uv/) reads the dependency block below and installs `bria-client` on first run — no separate install step:

```python
# /// 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)
```

```bash
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.

TypeScript SDK
Install the SDK, save this as `quickstart.ts`, and run it with `npx tsx quickstart.ts` (or plain `node quickstart.ts` on Node.js 22.18 or newer, which runs TypeScript directly):

```bash
npm install @bria-ai/client
```

```typescript
import { BriaClient } from "@bria-ai/client";

const client = new BriaClient(); // reads BRIA_API_TOKEN

const job = await client.submit("image/generate", {
  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",
});
console.log(job.requestId, job.statusUrl);
```

cURL
```bash
curl -X POST https://engine.prod.bria-api.com/v2/image/generate \
  -H "api_token: $BRIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'
```

Response (`202 Accepted`):

```json
{
  "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.

Python SDK
```python
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.

TypeScript SDK
```typescript
const result = await client.poll(job, { interval: 2, timeout: 120 });
console.log(result.result?.image_url);
console.log(result.result?.seed);
```

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

cURL
```bash
curl "https://engine.prod.bria-api.com/v2/status/<request_id>" -H "api_token: $BRIA_API_TOKEN"
```

Completed status body:

```json
{
  "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](/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](/getting-started/async-requests#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:

Python SDK
```python
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.

TypeScript SDK
```typescript
import { Image } from "@bria-ai/client";

const response = await client.run("image/edit/remove_background", {
  image: new Image("https://labs-assets.bria.ai/sandbox-example-inputs/remove_background_example.jpg").asBriaApiInput,
});
console.log(response.result?.image_url);
```

`new Image(...)` also accepts a local path, a `Buffer` or a `Uint8Array` and encodes it for you; `Image.fromBlob()` takes a `Blob`.

cURL
```bash
curl -X POST https://engine.prod.bria-api.com/v2/image/edit/remove_background \
  -H "api_token: $BRIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://labs-assets.bria.ai/sandbox-example-inputs/remove_background_example.jpg", "sync": true}'
```

The result is a PNG with a transparent background. Chain it into a [packshot](/product-shot-editing/products/product-packshot) or a [lifestyle scene](/product-shot-editing/products/product-lifestyle-shot-by-text) to build a catalog pipeline.

## Next steps

- [Async requests and polling](/getting-started/async-requests): statuses, timeouts, sync mode and when to use each.
- [Working with images and video](/getting-started/working-with-images): URLs, base64, formats, masks and video uploads.
- [Rate limits and errors](/getting-started/rate-limits-and-errors): plan limits and the error contract.
- [Image Editing overview](/image-editing-overview): every editing endpoint at a glance.
- Try any endpoint in the browser from its API reference page, or in the [Bria sandbox](https://platform.bria.ai/console).