Automation

Integrate Bloom into your automation stack so your workflows can generate on-brand images on demand and drop them into the rest of your tools. Whether you’re building in Zapier, n8n, Make, Gumloop, or anything else with an HTTP request step, the integration follows the same pattern below.

What you need before you start

A Bloom API key. Create one and keep it nearby — you’ll paste it into your tool’s credential vault. App integrations can use Bloom OAuth instead.
A brand session ID. Every image you generate is scoped to a brand:
- If you already have brands, hit GET /brands and copy any id.
- If you don’t, create one in the Bloom app by onboarding from a URL, or via POST /brands from your workflow.
An HTTP tool in your workflow — every automation platform has one (sometimes called “HTTP request”, “API call”, or similar). That’s the only primitive you need.

The three-call pattern

Start a generation. Returns 202 Accepted immediately with an image ID — the actual generation runs in the background.
Get the image. Either pass ?wait=true and let Bloom hold the connection open until it’s ready, or poll on a short interval if your tool can’t keep a connection alive.
Use the URL. The completed image’s CDN URL is in the response — pipe it into Slack, a Google Sheet, Drive, Webflow, whatever.

When your workflow creates the brand

Brand creation is also asynchronous. Add this sequence before the image-generation pattern:

POST /brands validates the request, creates a provisional brand, durably queues initialization, and returns 202 Accepted with status: "analyzing".
GET /brands/{id}?wait=true waits through the website or Instagram analysis and visual DNA extraction.
Continue only when status is ready. Handle logo_required by providing a logo, and handle failed by showing failure.message or submitting a new brand request.

If the wait times out, Bloom returns the current analyzing resource rather than an error. Fields such as logoUrl and summary can be null until initialization finishes. collectImages: false on POST /brands skips only background image-library collection. Bloom still crawls the source and builds the brand’s visual DNA.

Authentication

For most automation tools, send your API key as the x-api-key header:

x-api-key: bloom_sk_...

Store the key once in your tool’s credential vault and reference it as a variable in each step — don’t paste it directly into the workflow JSON. (Zapier calls this an “auth connection”, n8n calls them “credentials”, Make calls them “connections”, Gumloop calls them “secrets” — same primitive.) The API also accepts Authorization: Bearer bloom_sk_... for API keys and Authorization: Bearer <bloom_oauth_access_token> for app integrations using Bloom OAuth access tokens.

Step 1 — Start a generation

POST https://www.trybloom.ai/api/v1/images/generations

{
  "brandSessionId": "f7e319aa-2a7f-4f2a-853a-eb5a5798659e",
  "prompt": "Hero image for a spring product launch.",
  "aspectRatio": "16:9",
  "imageSize": "2K",
  "model": "pro"
}

Required: brandSessionId, prompt. Everything else is optional. Common optional fields:

Field	Values	Notes
`aspectRatio`	`1:1`, `16:9`, `9:16`, `4:5`, `3:2`, `2:3`, `3:4`, `4:3`, `5:4`, `21:9`	Defaults to a Bloom-chosen ratio if omitted.
`imageSize`	`2K`, `4K`	`2K` = 1 credit (default). `4K` = 2 credits (Plus/Pro plans).
`model`	`fast`, `standard`, `pro`	`pro` is the default. `fast` is cheaper and quicker.
`variantCount`	`1`–`5`	One image by default. Each variant costs the same as one generation.
`referenceImageIds`	array of image IDs	Use uploaded or previously generated images as style/content references.

Response (202 Accepted):

{
  "data": {
    "imageIds": ["a1b2c3d4-..."],
    "creditsUsed": 1
  }
}

Store data.imageIds[0] — that’s what the next step needs.

Step 2 — Get the image

You have two ways to retrieve the finished image. Pick based on your tool’s request timeout.

Option A — `wait=true` (recommended)

GET https://www.trybloom.ai/api/v1/images/{id}?wait=true Holds the connection open until the generation reaches a terminal state. One call, no polling loop, no scheduling. Returns the same shape whether the image was already done or just finished.

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

Use this whenever the tool can keep an HTTP request alive long enough. Most generations complete in well under a minute.

Option B — Polling

GET https://www.trybloom.ai/api/v1/images/{id} If your tool has a hard per-step timeout (Zapier in particular), fire the GET on a loop with a short delay until status is terminal.

loop:
  GET /images/{id}
  if status == "completed" → break
  if status == "failed"    → break with error
  wait 3 seconds
end

Most workflow tools have a built-in “wait + retry” or “delay then continue” primitive — n8n’s Wait node, Make’s Sleep module, Gumloop’s loop primitive. Zapier requires a multi-step zap with a Delay step.

Step 3 — Use the URL

A completed image response includes the CDN URL inside the data envelope:

{
  "data": {
    "id": "a1b2c3d4-...",
    "status": "completed",
    "imageUrl": "https://storage.trybloom.ai/...",
    "aspectRatio": "16:9",
    "imageSize": "2K"
  }
}

Pull data.imageUrl and pipe it into whatever downstream step the workflow needs — upload to Drive, post to Slack, write into a Sheet cell, attach to an email.

Batching

If you fire many generations at once (e.g. one per row in a spreadsheet), you don’t have to poll each ID individually. The list endpoint accepts ids=id1,id2,...&wait=true and holds open until every referenced image reaches a terminal state. One call collects the whole batch.

curl "https://www.trybloom.ai/api/v1/images?ids=id1,id2,id3&wait=true" \
  -H "x-api-key: $BLOOM_API_KEY"

Errors

Failed responses use a consistent envelope:

{
  "error": {
    "code": "BRAND_NOT_FOUND",
    "status": 422,
    "message": "Brand session not found"
  }
}

Branch on code, not on message. Common codes you’ll see while integrating:

Code	Meaning
`UNAUTHORIZED` (401)	Missing or invalid API key or OAuth access token.
`BRAND_NOT_FOUND` (422)	The `brandSessionId` doesn’t exist or belongs to a different account.
`BRAND_NOT_READY` (409)	The brand is still analyzing, needs a logo, or failed. Inspect `GET /brands/{id}` before retrying.
`INSUFFICIENT_CREDITS` (402)	Your workspace ran out of credits — top up at trybloom.ai/#pricing.
`PAYMENT_REQUIRED` (402)	Subscription paused (failed or pending payment). Blocks generation even with a positive credit balance — follow the `data.action_url` to resolve.
`TOO_MANY_REQUESTS` (429)	Too many requests too fast — back off and retry.

Bloom API

Guides

API Reference

What you need before you start

The three-call pattern

When your workflow creates the brand

Authentication

Step 1 — Start a generation

Step 2 — Get the image

Option A — `wait=true` (recommended)

Option B — Polling

Step 3 — Use the URL

Batching

Errors

​What you need before you start

​The three-call pattern

​When your workflow creates the brand

​Authentication

​Step 1 — Start a generation

​Step 2 — Get the image

​Option A — wait=true (recommended)

​Option B — Polling

​Step 3 — Use the URL

​Batching

​Errors

What you need before you start

The three-call pattern

When your workflow creates the brand

Authentication

Step 1 — Start a generation

Step 2 — Get the image

Option A — `wait=true` (recommended)

Option B — Polling

Step 3 — Use the URL

Batching

Errors