Developer · 3D Icon API — Realistic Icon

Overview

Three integration surfaces, one platform.

The Bluweo API gives third-party apps and AI agents programmatic access to everything the studio web UI can do — search the 3D-icon library, generate new variants from prompts, manage downloads, and listen for async events.

REST API — synchronous calls for any HTTP client.
MCP server — drop-in tool for Claude, Cursor, and any MCP-capable agent.
Webhooks — async push for long-running generations + billing events.

Heads up: API access is part of theStudio plan. Free and Designer plans use the web UI only — see Rate limits below.

REST, MCP, and webhooks — three integration surfaces fanning out from the Bluweo platform.

Quick start

Your first call in under 60 seconds.

Create an account and upgrade to Studio.
Generate an API key at /dashboard/billing → API keys. Keys start with blu_live_.
Send it as a Bearer token on every request.
Hit GET /v1/icons/search?q=fox to confirm the key works.

Base URL: https://api.bluweo.com. All requests must be HTTPS — the API will reject plain HTTP.

# 1. Search the icon catalogue
curl https://api.bluweo.com/v1/icons/search?q=fox \
  -H "Authorization: Bearer blu_live_..."

Authentication

Bearer keys, workspace-scoped.

Every API request must include an Authorization: Bearer <key> header. Keys are issued from your dashboard and tied to one workspace; the key's tier determines the rate limit.

Key format: blu_live_* (production) or blu_test_* (sandbox — no billing, watermarked output).
Shown once: we hash keys server-side. If you lose one, rotate it.
Rotation: a key can be rolled with POST /v1/keys/:id/roll; the old key keeps working for 24h to ease migration.
Revocation: DELETE /v1/keys/:id takes effect immediately.

API key authentication — Bearer header on every call.

REST API

Search, generate, download, manage.

All endpoints live under /v1/. JSON in, JSON out. Snake-case fields. ISO-8601 timestamps in UTC.

Method	Path	Purpose
GET	`/v1/icons`	List icons; filter by tag, style, color.
GET	`/v1/icons/search`	Full-text search the catalogue.
GET	`/v1/icons/:id`	Single icon detail + variants.
POST	`/v1/icons/generate`	Start an AI generation. Returns 202.
GET	`/v1/generations/:id`	Poll a generation's status / outputs.
POST	`/v1/icons/:id/variants`	Spawn a style / color variant from an existing icon.
GET	`/v1/collections`	List curated collections.
POST	`/v1/downloads`	Record a download (spends 1 credit).
GET	`/v1/me`	Workspace info + credit balance.
POST	`/v1/keys`	Mint a new API key.
DELETE	`/v1/keys/:id`	Revoke a key.

Generations are async — the POST returns 202 with a job id; the actual rendering takes 5–30s. Poll /v1/generations/:id or subscribe to generation.completed webhooks instead of blocking.

Async generation flow — POST enqueues, worker processes, webhook notifies.

# Generate a 3D icon
curl https://api.bluweo.com/v1/icons/generate \
  -X POST \
  -H "Authorization: Bearer blu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "cute 3D fox character, studio lighting",
    "kind": "icon",
    "aspect": "1:1",
    "outputs": 4
  }'

# → 202 { "id": "gen_01H...", "status": "queued" }

# Poll until done
curl https://api.bluweo.com/v1/generations/gen_01H... \
  -H "Authorization: Bearer blu_live_..."

MCP server

Let AI agents use Bluweo as a tool.

The Model Context Protocol (MCP) is Anthropic's open standard for letting AI agents call external tools. We ship bluweo-icons-mcp — drop it into Claude Desktop, Cursor, Zed, or any MCP-capable client and the agent can search and generate icons mid-conversation.

The MCP server exposes four tools:

search_icons — find icons by keyword / tag.
get_icon — fetch metadata + download URL for one icon.
generate_icon — async-aware: returns a job id, status, or completed outputs.
list_collections — browse curated bundles.

Same Bearer key as the REST API — set BLUWEO_API_KEY in the MCP server's env block. Tool calls are tier-rate-limited just like REST.

MCP flow — agent calls tool, MCP server translates to REST, results return to agent.

# Install the MCP server (Node-based, NPX)
npx -y @bluweo/icons-mcp@latest --version

Webhooks

Push notifications for async work.

Configure a webhook URL in your dashboard. We POST a signed JSON payload whenever something noteworthy happens — primarily so you don't have to poll generation status.

Events we emit:

generation.completed — outputs are ready to download.
generation.failed — credits auto-refunded; payload includes the error reason.
credits.low — your balance dropped below 20% of the plan allowance.
subscription.updated — plan changed / renewed / canceled.

Every payload includes a Bluweo-Signature header — an HMAC-SHA256 of the body using your webhook secret. Always verify before trusting the payload; an unsigned POST could be a forged request.

# Example payload Bluweo POSTs to your endpoint
{
  "event": "generation.completed",
  "data": {
    "id": "gen_01H...",
    "status": "done",
    "outputs": [
      { "url": "https://cdn.bluweo.com/g/.../0.png", "width": 1024, "height": 1024 }
    ],
    "credits_used": 5
  },
  "created_at": "2026-05-16T17:42:11Z"
}

# Header attached:
# Bluweo-Signature: t=1715882531,v1=<hmac>

Rate limits & quotas

Per-key, per-month — and per-second to keep things fair.

Two limits apply to every key: monthly volume (plan-tier quota) and short-burst (10 req/s, to protect shared resources). Both are returned on every response via standard X-RateLimit-* headers.

Plan	API access	Monthly quota	Burst
Free	— (web UI only)	—	—
Designer	— (web UI only)	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

Generations and downloads also spend credits from the plan allowance — see Pricing. Credit-pack top-ups don't extend the API quota; they only fund the generation cost.

Exceeding the limit returns 429 Too Many Requests with a Retry-After header. Drop traffic for that long and retry — no penalty for backing off.

Plan-tier API access — Free and Designer use the web UI only; Studio unlocks the API.

# Every response includes:
X-RateLimit-Limit:        10000
X-RateLimit-Remaining:    9847
X-RateLimit-Reset:        1715958000   # unix epoch
X-RateLimit-Burst-Limit:  10
X-RateLimit-Burst-Remaining: 7

# On 429:
Retry-After: 3            # seconds

Errors

Conventional HTTP codes + structured JSON body.

Common status codes:

Code	Meaning
`200`	OK — synchronous success.
`202`	Accepted — async job queued.
`400`	Invalid request body or query params.
`401`	Missing or invalid API key.
`402`	Out of credits — top up to retry.
`403`	Key valid but plan tier doesn't grant API access.
`404`	Resource not found.
`409`	State conflict (e.g. revoking an already-revoked key).
`429`	Rate limit hit — see `Retry-After`.
`5xx`	Our problem. We auto-retry idempotent requests; safe to retry yourself.

Every error body is JSON: { "error": { "code", "message", "request_id" } }. Include the request_id when you contact support — we can pull the trace.

# 402 — out of credits
{
  "error": {
    "code": "insufficient_credits",
    "message": "Account has 3 credits; generate(outputs=4) requires 20.",
    "request_id": "req_01H9R..."
  }
}

# 429 — rate limit
{
  "error": {
    "code": "rate_limited",
    "message": "Burst limit of 10 req/s exceeded.",
    "request_id": "req_01H9R..."
  }
}

Limitations

What the API can't do today — set expectations up-front.

No offline / on-prem. Generations always run on our infrastructure. The icon library can be cached client-side; AI generation cannot.
No batch generation in a single call. Each POST /v1/icons/generate handles one prompt × up to 4 outputs. Fan out yourself for larger batches; the burst limit still applies.
Maximum prompt length: 1,000 chars. Longer prompts are rejected with 400.
Content policy. We block prompts that solicit real people, copyrighted characters, NSFW, or hateful content. Failures return 400 with code: "policy_violation".
Output resolution capped at 2048 × 2048. Higher resolutions require a custom contract.
Generation latency: 5–30s. Worst case (queue saturation): up to 2 min. Plan for async — use webhooks, not polling tight loops.
MCP support: stdio transport only. HTTP/SSE transport is on the roadmap.
No SLA at Studio tier. Enterprise contracts include 99.9% uptime + named support. Contact us.

Need something this list can't give you?

Enterprise plans unlock:

Custom resolution + style fine-tunes on your own brand assets.
Dedicated capacity (no shared queue).
VPC / on-prem deployment.
Named support + 99.9% SLA.
Volume pricing past 10k req / mo.

Talk to sales →

Versioning

v1 is current. Breaking changes ship as v2.

The version is in the URL path: /v1/.... Within a version we only make additive changes — new fields, new endpoints, new event types. We will never remove a field or change its type within a version.

When we ship v2, v1 stays live for at least 12 months with a deprecation date announced via the changelog endpoint and email to all API users.

Changelog: GET /v1/changelog returns every change since launch, newest first.
Status page: status.bluweo.com for live uptime + incident history.
Email updates: opt-in from the dashboard. We only send for breaking-change notice + major incidents.

# Read the changelog (no auth needed)
curl https://api.bluweo.com/v1/changelog | jq

# Sample entry:
{
  "version": "1.4.0",
  "released_at": "2026-04-22",
  "title": "MCP tools: list_collections + variant generation",
  "highlights": [
    "New MCP tool: list_collections",
    "Variant generation now supports color hex shorthand",
    "Webhook signatures use t=...,v1=... format (v0 deprecated 2026-10-22)"
  ]
}

Ready to build?

Generate your first API key from the dashboard, or talk to us if you need a custom contract.

Upgrade to Studio Talk to sales

Build with the 3D Icon API.