Bloom

Get details of any image — generated, uploaded, or scraped. Looks up the image across every workspace the caller can access. Works with IDs from bloom_generate_image, bloom_upload_image, or bloom_list_images. For generated images, use wait=true to hold the connection until generation completes. Args: - image_id (string): Image ID (any source) - wait (boolean, optional): Hold connection until terminal status. Only applies to generated images. Recommended: true. - timeout (number, optional): Max seconds to wait (1-300, default 120) - include_url (boolean, optional): Ignored — the URL is always included in the response because this tool has an attached UI widget that requires it. Kept for backward compatibility. Returns: { "id": string, "source": "generated" | "uploaded" | "scraped", "status": "pending" | "generating" | "completed" | "failed" | null, // null for uploads/scraped "failure_reason": "content_safety" | "rate_limited" | null, // why a failed generation failed "prompt": string | null, "description": string | null, "image_url": string | null, "aspect_ratio": string | null, "width": number | null, "height": number | null, "action_type": string | null, "workspace_id": string | null, "workspace_name": string, "created_at": string }

bloom_get_image

List brand sessions across every workspace the caller can access, with pagination. Returns brand IDs needed for image generation. Each brand represents a website or Instagram profile that has been onboarded to Bloom with its visual identity extracted. Args: - workspace_id (string, optional): Scope results to one workspace by id (from bloom_list_workspaces). Omit to span every workspace the caller can see; each result is labeled with its workspace. - url (string, optional): Filter brands by website URL (partial match, e.g. "gumroad.com") - limit (number, optional): Results per page (1-100, default 50) - cursor (string, optional): Pagination cursor from previous response Returns: { "brands": [ { "id": string, "brand_url": string, "name": string, "url": string, "status": string, "image_count": number, "workspace_id": string | null, "workspace_name": string, "created_at": string } ], "next_cursor": string | null, "has_more": boolean } Use the returned "id" as the brand_session_id parameter in bloom_generate_image.

bloom_list_brands

List images — generated, uploaded, and scraped — across every workspace the caller can access, with pagination and optional filters. Also the single-call way to fetch a specific set of images (pass `image_ids`), which is preferred over calling bloom_get_image per image. Returns images sorted newest-first with cursor-based pagination. Includes scraped website images from brand onboarding — use these as reference images for generation. **Batch collect pattern**: after firing N parallel bloom_generate_image calls, collect the results in one shot via `bloom_list_images({ image_ids: [...] })`. `wait` defaults to true whenever `image_ids` is provided, so the call holds open until every referenced image reaches a terminal status — no per-image polling, no stuck loading tiles in the gallery widget. Pass `wait: false` only if you want to peek at in-flight statuses. Args: - image_ids (string[], optional): Fetch multiple specific images in one call (e.g., to display a gallery of newly-generated results). Max 50 IDs. - workspace_id (string, optional): Scope results to one workspace by id (from bloom_list_workspaces). Omit to span every workspace the caller can see; each result is labeled with its workspace. - brand_session_id (string, optional): Brand session UUID (from bloom_list_brands). Omit to list across all brands. - source (string, optional): Filter by source — "generated", "uploaded", "scraped" - limit (number, optional): Results per page (1-100, default 50) - status (string, optional): Filter by generation status — "pending", "generating", "completed", "failed". Only applies to generated images; uploaded/scraped are excluded when this filter is active. - action_type (string, optional): Filter by type — "generation", "edit", "resize", "variant", "recreate", "remove-background", "vectorize". Only applies to generated images. - include_urls (boolean, optional): Ignored — image URLs are always included because this tool has an attached UI widget that requires them. Kept for backward compatibility. - wait (boolean, optional): Hold the connection until every image referenced by `image_ids` reaches a terminal status. Defaults to true when `image_ids` is provided, false otherwise. No-op when `image_ids` is omitted. - timeout (number, optional): Max seconds to wait (1-295, default 120). Only meaningful when `wait` is on. - cursor (string, optional): Pagination cursor from previous response Returns: { "images": [ { "id": string, "source": "generated" | "uploaded" | "scraped", "brand_session_id": string | undefined, "prompt": string | null, // null for uploads/scraped "description": string | null, "aspect_ratio": string | null, "width": number | null, "height": number | null, "action_type": string | null, // null for uploads/scraped "status": string | null, // null for uploads/scraped "failure_reason": "content_safety" | "rate_limited" | null, "image_url"?: string, "workspace_id": string | null, "workspace_name": string, "created_at": string } ], "next_cursor": string | null, "has_more": boolean, "brand_name": string | undefined // present only when scoped to a single brand } Every returned image has an id. For generated images: - completed: image_url is present. - failed: image_url is absent; inspect failure_reason. - pending or generating: image_url is absent because processing has not finished. These states can still appear when wait is false or the wait times out. Use next_cursor in a follow-up call to get the next page.

bloom_list_images

List workspaces the caller can access. The personal workspace (is_personal: true) is listed first and is the caller's default: create tools with an optional workspace_id (bloom_onboard_brand, bloom_check_credits) act on it when workspace_id is omitted. Pass a workspace_id from this list to target a specific workspace; each tool's own docs describe how it scopes. Args: (none) Returns: { "workspaces": [ { "workspace_id": string | null, "workspace_name": string, "is_personal": boolean } ] } The caller's personal workspace (auto-created at signup) is listed first and tagged "is_personal": true.

bloom_list_workspaces

Onboard a new brand by analyzing a website or Instagram URL. Queues website or Instagram analysis and returns immediately with the brand ID. Bloom then pulls in the logo, fonts, screenshot/collage, and business summary before starting visual DNA extraction. After calling this tool, use bloom_get_brand to check status and wait for completion. Defaults to the caller's personal workspace; pass `workspace_id` to onboard into a team workspace. Recommended when the caller belongs to multiple workspaces — naming the target explicitly avoids onboarding into the wrong account. Args: - url (string): Website or Instagram profile URL to analyze (e.g., "https://stripe.com" or "https://instagram.com/nike") - workspace_id (string, optional): Workspace ID. Omit to default to the caller's personal workspace. - logo_url (string, optional): Explicit logo URL. If provided, skips automatic logo extraction from the website or Instagram profile. - collect_images (boolean, optional): Whether to collect background images from the website or Instagram profile into the brand's image library. Defaults to true. Setting false does not skip source analysis, crawling, or visual DNA. Returns: { "id": string, "brand_url": string, "status": "analyzing" } Logo problems are discovered asynchronously. bloom_get_brand returns "logo_required" when a replacement logo is needed. Examples: - "Create images for my company at stripe.com" → call with url="https://stripe.com" - "Onboard my Instagram brand" → call with url="https://instagram.com/nike" - "Onboard this brand with our logo" → call with url and logo_url - "Onboard this for the Acme team" → call with url and workspace_id of the Acme workspace - Don't use if the brand already exists — call bloom_list_brands to check first Workflow: 1. Call this tool with a website or Instagram URL 2. Call bloom_get_brand with wait=true to wait for completion (~60s) 3. Once status is "ready", use the brand ID with bloom_generate_image

bloom_onboard_brand

Open an inline file picker so the user can upload one or more local images to a brand session in a single batch. The user picks files in the widget and the bytes are uploaded directly to Bloom — they never enter the conversation. The resulting image ids and metadata are written to the widget's model context, exposed via the host's "read widget context" tool; read that before referencing the uploads in subsequent tool calls. Two surfaces exist for getting local file bytes into a brand session; pick by what the client can do: - bloom_open_upload_ui (this tool) renders a multi-file picker inline. Use it when the client is an MCP App-capable host. If the client doesn't render UI, this tool returns a fallback message pointing at the shell path. - bloom_create_image_upload_url returns one or more signed URLs the client POSTs bytes to itself. Use it when the client has filesystem + HTTP access but cannot render UI. Does NOT change the brand's logo. Logo replacement goes through bloom_open_logo_upload_ui (UI hosts) or bloom_create_logo_upload_url (shell hosts); only use those when the user explicitly says the image is the logo. If unclear, ask the user before calling either tool. Args: - brand_session_id (string): Brand session UUID (from bloom_list_brands) Returns: { "brandSessionId": string } Supported formats: PNG, JPEG, WebP, AVIF Max file size: 10MB

bloom_open_upload_ui

Open an inline file picker so the user can upload a local file as a brand's primary logo. The user picks a file in the widget and the bytes are uploaded directly to Bloom — they never enter the conversation. After upload, the brand re-enters "analyzing" status while a fresh visual DNA extraction runs. The result is written to the widget's model context, exposed via the host's "read widget context" tool; read that before referencing the upload in subsequent tool calls. Two surfaces exist for getting local logo bytes onto a brand; pick by what the client can do: - bloom_open_logo_upload_ui (this tool) renders a file picker inline. Use it when the client is an MCP App-capable host. If the client doesn't render UI, this tool returns a fallback message pointing at the shell path. - bloom_create_logo_upload_url returns a signed URL the client PUTs bytes to itself. Use it when the client has filesystem + HTTP access but cannot render UI. Use this when the user explicitly indicates the image is meant to be the brand's logo. A bare "upload this image to brand X" is not a trigger — that's a reference-image upload, use bloom_open_upload_ui. If the user's intent is ambiguous, ask them whether the image is meant to be the brand's logo before calling either tool. Args: - brand_session_id (string): Brand session UUID (from bloom_list_brands) Returns: { "brandSessionId": string } Supported formats: PNG, JPEG, WebP, SVG, AVIF Max file size: 10MB

bloom_open_logo_upload_ui

Remove the background from an image, returning a transparent PNG. Works on completed generated images and on uploaded/scraped images (from bloom_upload_image, bloom_search_user_images, or bloom_list_images). Returns immediately with a new image ID. The cutout typically completes in under 10 seconds. After calling this tool, use bloom_get_image to check status and retrieve the resulting transparent PNG when ready. Args: - image_id (string): ID of a completed or uploaded image to process - brand_session_id (string): Brand session UUID the image belongs to Returns: { "image_id": string, "status": "pending" } Workflow: 1. Generate or pick an existing completed image 2. Call this tool with the image's ID 3. Call bloom_get_image with the returned image_id to poll for results 4. When status is "completed", the transparent PNG is at image_url

bloom_remove_background

Resize (reflow) an existing image to a different aspect ratio using AI. Submits a resize request and returns immediately with a new image ID. The resize typically takes 30-60 seconds. After calling this tool, use bloom_get_image to check the status and retrieve the result when ready. The source image's resolution (2K/4K) is preserved in the output. The source aspect ratio is read automatically from the image metadata. Args: - image_id (string): ID of a completed image to resize - target_aspect_ratio (string): One of "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" - brand_session_id (string): Brand session UUID the image belongs to Returns: { "image_id": string, "status": "pending" } Workflow: 1. Generate an image first using bloom_generate_image 2. Call this tool with the completed image's ID and a new aspect ratio 3. Call bloom_get_image with the returned image_id to poll for results 4. When status is "completed", the resized image_url will be available

bloom_resize_image

Semantic search over a brand's image library — the brand's actual photos (products, design assets, user uploads, images obtained from the onboarding source, etc...). Using these as references measurably improves generation outputs. Search for what would actually appear in the picture, not the format word. For "a billboard for our drone company", search for "drone product shot" or "drone in flight," not just "billboard" — pick what kind of imagery would go on it. Call this multiple times with different concepts to gather a varied set of references for one brief. This tool has two modes — pick deliberately: - "select" (default): you are asking the user to pick references. After calling, on your next turn read the widget's model context to see what the user picked, then generate. - "display": you fetched these to use as references yourself, with no need for user input. Pick the matches that fit, then pass their ids as reference image id(s) to the respective image generation tool calls. Use only when it's clear the user does not need to weigh in. Args: - brand_session_id (string): Brand session UUID (from bloom_list_brands) - query (string): Visual concept to search for. Plain noun phrases work best — e.g., "drone in flight," "team working at desks," "product on white background." - top_k (number, optional): Max results to return (1-20, default 10). - mode ("display" | "select", optional): See modes above. Default "select". Returns: { "mode": "display" | "select", "query": string, "candidates": [ { "id": string, "url": string, "description": string, "width": number, "height": number, "aspect_ratio": string | null } ] } Returns at most top_k candidates whose embeddings sit within the relevance threshold; weak matches are dropped. Empty array means nothing in the library fits — generate without references in that case.

bloom_search_user_images

Update the logo for an existing brand session. Use this when bloom_get_brand returns status "logo_required" — the logo couldn't be extracted from the website or Instagram profile. After updating, the logo is validated and visual DNA extraction starts automatically. Call bloom_get_brand with wait=true to wait for the brand to reach "ready" status. This tool accepts a publicly hosted logo URL. For local logo files (PNG, SVG, etc. on the user's machine), do NOT load the bytes into this conversation — use one of the HTTP paths below. Args: - id (string): The brand ID from bloom_onboard_brand - logo_url (string): Direct URL to the logo image (PNG, JPG, SVG, WEBP) Returns: { "id": string, "brand_url": string, "status": "analyzing" } For local logo files (filesystem / shell access), use one of these HTTP paths — both keep bytes out of conversation context and trigger the same validation + DNA pipeline. A. When you can access a Bloom API key directly (e.g. it's in your shell environment), PUT to the Bearer-authenticated endpoint: curl -X PUT https://www.trybloom.ai/api/v1/brands/<brand_id>/logo/file \ -H "Authorization: Bearer $BLOOM_API_KEY" \ -F "file=@./logo.png;type=image/png" B. When you cannot access a Bloom API key directly (common when the key lives in an MCP client config rather than your shell), first call bloom_create_logo_upload_url to mint a short-lived signed URL, then PUT the bytes with no Authorization header: curl -X PUT "$upload_url" -F "file=@./logo.png;type=image/png" Both HTTP paths return: { "data": { "id": string, "status": "analyzing" } } Supported formats: PNG, JPEG, WEBP, SVG, AVIF (not ICO or GIF) Max file size: 10MB

bloom_update_brand_logo

Upload an image by URL for use as a reference or edit subject. The server downloads and validates the image, then reuses an exact match in the brand session or stores a new one. Returns an image ID that you can use with other Bloom tools: - As a reference in bloom_generate_image (reference_image_ids) - As a reference in bloom_edit_image (reference_image_ids) - As an edit subject in bloom_edit_image (image_id) Args: - image_url (string): Public URL of the image to upload (PNG, JPEG, WebP, AVIF) - brand_session_id (string): Brand session UUID to scope the upload to. Returns: { "id": string, "width": number, "height": number, "mime_type": string, "existing": boolean } Supported formats: PNG, JPEG, WebP, AVIF Max file size: 10MB For local image files (when you have filesystem / shell access), do NOT load the bytes into this conversation. Use one of these HTTP paths — both keep bytes out of conversation context and return the same shape. A. When you can access a Bloom API key directly (e.g. it's in your shell environment), POST to the Bearer-authenticated endpoint: curl -X POST https://www.trybloom.ai/api/v1/images/uploads/file \ -H "Authorization: Bearer $BLOOM_API_KEY" \ -F "file=@./photo.png;type=image/png" \ -F "brandSessionId=<uuid>" B. When you cannot access a Bloom API key directly (common when the key lives in an MCP client config rather than your shell), first call bloom_create_image_upload_url to mint a short-lived signed URL, then POST the bytes with no Authorization header: curl -X POST "$upload_url" -F "file=@./photo.png;type=image/png" Response: { "data": { "id": string, "imageUrl": string, "width": number, "height": number, "mimeType": string, "existing": boolean } } Use the returned "id" anywhere this tool's "id" is accepted.

bloom_upload_image

Convert an image to a scalable SVG. Best for logos, icons, and flat illustrations; not recommended for photos or soft-shaded artwork. Works on completed generated images and on uploaded/scraped images (from bloom_upload_image, bloom_search_user_images, or bloom_list_images). Returns immediately with a new image ID. Vectorization typically completes in under 30 seconds. After calling this tool, use bloom_get_image to check status and retrieve the resulting SVG when ready. Args: - image_id (string): ID of a completed generated image, or an uploaded/scraped image, to vectorize - brand_session_id (string): Brand session UUID (from bloom_list_brands) Returns: { "image_id": string, "status": "pending" } Workflow: 1. Generate or pick an existing completed image (ideally a logo or icon) 2. Call this tool with the image's ID 3. Call bloom_get_image with the returned image_id to poll for results 4. When status is "completed", the SVG is at image_url

bloom_vectorize_image