> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybloom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate images

> Generate brand-aware images through the API or an MCP-connected agent.

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](/guides/create-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

<Tabs>
  <Tab title="API">
    Send `POST /images/generations`:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "data": {
        "ids": ["a1b2c3d4-140f-4491-8a24-b215616ed34a"],
        "variantGroupId": null,
        "status": "pending"
      }
    }
    ```
  </Tab>

  <Tab title="MCP">
    Name the brand and describe the image:

    ```text theme={null}
    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:

    ```json theme={null}
    {
      "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
    }
    ```
  </Tab>
</Tabs>

Both interfaces return image IDs before generation finishes.

## Retrieve the result

<Tabs>
  <Tab title="API">
    Retrieve one image with `GET /images/{id}?wait=true`:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="MCP">
    For one image, call `bloom_get_image` with `wait: true`. For several IDs, call `bloom_list_images` once with `image_ids` and `wait: true`.
  </Tab>
</Tabs>

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](/api/openapi) 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.

```text theme={null}
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](/api/usage-limits) for costs and rate-limit behavior. Once an image is complete, continue with [Edit and adapt images](/guides/edit-adapt-images).