Generate images

Every image generation is scoped to a ready Brand. Bloom applies the Brand’s active Skill; the request describes the subject, composition, and medium needed for this particular image.

Prepare the Brand and prompt

Use an existing Brand whose status is ready, or create a Brand and wait for it. The stable Brand ID is called brandSessionId in the API and brand_session_id in MCP. Describe what should appear in the image:

the subject and important objects;
the composition or framing;
the medium, such as a photograph, illustration, 3D render, mockup, or poster; and
any text or product detail that must be present.

Bloom already applies the Brand’s visual guidance. Avoid generic aesthetic filler such as “professional,” “stunning,” or “premium.”

Start generation

Send POST /images/generations:

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": "<brand_id>",
    "prompt": "Product shot of a coffee bag on a marble counter in soft morning light.",
    "aspectRatio": "16:9",
    "imageSize": "2K",
    "model": "pro",
    "variantCount": 1
  }'

Bloom returns 202 Accepted with one or more image IDs:

{
  "data": {
    "ids": ["a1b2c3d4-140f-4491-8a24-b215616ed34a"],
    "variantGroupId": null,
    "status": "pending"
  }
}

Name the Brand and describe the image:

Using my Acme Brand, generate a 16:9 product shot of a coffee bag on a marble
counter in soft morning light.

An integration calling bloom_generate_image directly can pass:

{
  "brand_session_id": "<brand_id>",
  "prompt": "Product shot of a coffee bag on a marble counter in soft morning light.",
  "aspect_ratio": "16:9",
  "image_size": "2K",
  "model": "pro",
  "variant_count": 1
}

Both interfaces return image IDs before generation finishes.

Retrieve the result

Retrieve one image with GET /images/{id}?wait=true:

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

For several image IDs, use GET /images?ids=...&wait=true to collect them together.

For one image, call bloom_get_image with wait: true. For several IDs, call bloom_list_images once with image_ids and wait: true.

A bounded wait can return a non-terminal status. Repeat the same request until every image is completed or failed, and present only completed results with an image URL. The generated API reference and the live MCP schema returned by tools/list define the exact contracts.

Use reference images

References can ground the generation in a specific product, person, composition, or visual example. With the API, pass up to ten uploaded or generated image IDs as referenceImageIds. Use the image upload or Brand Library search endpoints to obtain those IDs. With MCP, use bloom_search_user_images to search the Brand Library or bloom_upload_image to add an image by URL. Pass the selected IDs as reference_image_ids to bloom_generate_image. For each generation, include only the references relevant to that image and describe how each should be used. Refer to a reference by its content, not its position in the input list.

Use reference ads

MCP can search Bloom’s curated reference-ad library with bloom_find_reference_ads. After the user or agent selects a result, pass its ID to bloom_generate_image as recreate_ad_id to adapt that composition to the Brand.

Find reference ads built around a product-launch announcement. Show me the
results before recreating one for Acme.

The normal prompt is optional when recreate_ad_id is present and can provide extra instructions. The reference ad determines the aspect ratio. This workflow is currently exposed through MCP, not the public REST generation schema.

Choose a model

Model	Use it for
`pro`	Default; highest-quality final work
`standard`	A balance of quality and speed
`fast`	Faster exploration and drafts

Model availability and exact behavior are defined by the live API or MCP schema. Avoid building orchestration around estimated completion times.

Choose size, ratio, and variants

2K is the default and costs 1 credit per image.
4K costs 2 credits per image and may depend on plan entitlement.
Supported aspect ratios are 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, and 21:9.
One request can create 1–5 variants. Each variant costs the normal per-image amount.

Handle failures

A Brand that is not ready returns BRAND_NOT_READY; wait on the Brand before retrying.
Missing or inaccessible references return a reference-image error; remove or replace the invalid ID.
A 402 billing response distinguishes exhausted credits from a paused subscription by its error code.
An accepted operation can still return an image with status: "failed"; inspect its failure information before retrying.

See Credits and limits for costs and rate-limit behavior. Once an image is complete, continue with Edit and adapt images.

Getting started

Guides

MCP

Generate images

Prepare the Brand and prompt

Start generation

Retrieve the result

Use reference images

Use reference ads

Choose a model

Choose size, ratio, and variants

Handle failures

​Prepare the Brand and prompt

​Start generation

​Retrieve the result

​Use reference images

​Use reference ads

​Choose a model

​Choose size, ratio, and variants

​Handle failures

Prepare the Brand and prompt

Start generation

Retrieve the result

Use reference images

Use reference ads

Choose a model

Choose size, ratio, and variants

Handle failures