API quickstart

Generate your first brand-aware image through Bloom’s REST API: authenticate, select or create a brand, wait until it is ready, then generate and retrieve an image. Bloom applies the brand’s guidance automatically.

1. Authenticate

For server-side automations, open your account settings and generate an API key. Store it as BLOOM_API_KEY in your environment or secret manager before running the examples below. Treat it as a secret — never commit it or expose it client-side. App integrations can use Bloom OAuth instead and call the API with Authorization: Bearer <access_token>. See API authentication for the OAuth endpoints and PKCE requirements.

2. Get a Brand ID

Image generations are scoped to a brand. You need a brandSessionId: pick an existing brand or create one from your sources.

Existing brand
Create a brand

List your brands and copy any id:

curl https://www.trybloom.ai/api/v1/brands \
  -H "x-api-key: $BLOOM_API_KEY"

Pick a brand whose status is ready. Its id is the brandSessionId you’ll use next. If the brand is still analyzing, continue to step 3.

This example combines a website and brand guide, then requests imagery guidance:

curl -X POST https://www.trybloom.ai/api/v1/brands \
  -H "x-api-key: $BLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      { "kind": "website", "url": "https://acme.com" },
      {
        "kind": "file",
        "url": "https://uploads.acme.com/temporary-brand-guide.pdf",
        "filename": "brand-guide.pdf"
      }
    ],
    "instructions": "Create an imagery.md file that explains how image-heavy this brand is and what imagery it uses."
  }'

File URLs must use HTTPS and remain publicly reachable while the request runs.Save data.id from the response as the Brand ID. Creation continues while you check progress in step 3.See Create a brand to choose sources and recover from a failed attempt.

3. Wait for the brand

Pass wait=true to wait for the current brand analysis:

curl "https://www.trybloom.ai/api/v1/brands/<brand_id>?wait=true" \
  -H "x-api-key: $BLOOM_API_KEY"

Each call waits for a bounded period. If the response still has status: "analyzing", call the same endpoint again with the same Brand ID. Continue only when the brand is ready. If the brand is failed, show failure.message and follow Handle failures for retries.

4. Start a generation

Start generation using the ready Brand ID:

curl -X POST https://www.trybloom.ai/api/v1/images/generations \
  -H "x-api-key: $BLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandSessionId": "<id from step 2>",
    "prompt": "Hero image for a spring product launch."
  }'

Save the image IDs from data.ids. Generation continues while you retrieve the result in the next step. If Bloom reports that the brand is not ready, return to step 3 before retrying.

5. Retrieve the image

Call GET /images/{id} to check the status. Pass wait=true to hold the connection open while the generation runs:

curl "https://www.trybloom.ai/api/v1/images/<image_id>?wait=true" \
  -H "x-api-key: $BLOOM_API_KEY"

A completed image is available at data.imageUrl. If data.status is still pending or generating, call the same endpoint again. If it is failed, read the returned failure information before retrying. Continue with Generate images, Edit a brand, or Retrieve and use a Brand Skill. The API reference defines the complete public contract.

Getting started

Guides

Use cases

MCP

API quickstart

1. Authenticate

2. Get a Brand ID

3. Wait for the brand

4. Start a generation

5. Retrieve the image

​1. Authenticate

​2. Get a Brand ID

​3. Wait for the brand

​4. Start a generation

​5. Retrieve the image

1. Authenticate

2. Get a Brand ID

3. Wait for the brand

4. Start a generation

5. Retrieve the image