API roadmap — Entwickler

Überblick

Drei Integrationswege, eine Plattform.

Die Bluweo-API gibt Drittanbieter-Apps und KI-Agenten programmatischen Zugriff auf alles, was das Studio-Web-UI kann — die 3D-Icon-Bibliothek durchsuchen, aus Prompts neue Varianten erzeugen, Downloads verwalten und auf asynchrone Ereignisse hören.

REST API — synchrone Aufrufe für jeden HTTP-Client.
MCP server — sofort einsetzbares Werkzeug für Claude, Cursor und jeden MCP-fähigen Agenten.
Webhooks — asynchroner Push für langlaufende Generierungen und Abrechnungsereignisse.

Hinweis: Der API-Zugriff gehört zum Studio-Tarif. Free und Designer nutzen ausschließlich das Web-UI — siehe Ratenlimits weiter unten.

REST, MCP und Webhooks — drei Integrationswege, die von der Bluweo-Plattform ausgehen.

Schnellstart

Dein erster Aufruf in unter 60 Sekunden.

Konto anlegen und auf Studio upgraden.
API-Schlüssel erzeugen unter /dashboard/billing → API keys. Schlüssel beginnen mit blu_live_.
Schick ihn bei jeder Anfrage als Bearer-Token mit.
Ruf GET /v1/icons/search?q=fox auf, um zu prüfen, ob der Schlüssel funktioniert.

Basis-URL: https://api.bluweo.com. Alle Anfragen müssen über HTTPS laufen — die API weist einfaches HTTP ab.

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

Authentifizierung

Bearer-Schlüssel, auf einen Workspace begrenzt.

Jede API-Anfrage braucht einen Authorization: Bearer <key> Header. Schlüssel werden im Dashboard ausgestellt und gehören zu genau einem Workspace; die Tarifstufe des Schlüssels bestimmt das Ratenlimit.

Schlüsselformat: blu_live_* (Produktion) oder blu_test_* (Sandbox — keine Abrechnung, Ausgabe mit Wasserzeichen).
Nur einmal sichtbar: Wir speichern Schlüssel serverseitig nur als Hash. Wenn du einen verlierst, tausch ihn aus.
Austausch: Ein Schlüssel lässt sich austauschen mit POST /v1/keys/:id/roll; der alte Schlüssel funktioniert noch 24 Std. weiter, damit die Umstellung leichter fällt.
Widerruf: DELETE /v1/keys/:id wirkt sofort.

API-Schlüssel-Authentifizierung — Bearer-Header bei jedem Aufruf.

REST-API

Suchen, erzeugen, herunterladen, verwalten.

Alle Endpunkte liegen unter /v1/. JSON rein, JSON raus. Felder in Snake Case. Zeitstempel als ISO-8601 in UTC.

Methode	Pfad	Zweck
GET	`/v1/icons`	Icons auflisten; nach Tag, Stil und Farbe filtern.
GET	`/v1/icons/search`	Volltextsuche im Katalog.
GET	`/v1/icons/:id`	Details zu einem Icon plus Varianten.
POST	`/v1/icons/generate`	Eine KI-Generierung starten. Gibt 202 zurück.
GET	`/v1/generations/:id`	Status/Ergebnisse einer Generierung abfragen.
POST	`/v1/icons/:id/variants`	Aus einem vorhandenen Icon eine Stil-/Farbvariante erzeugen.
GET	`/v1/collections`	Kuratierte Kollektionen auflisten.
POST	`/v1/downloads`	Einen Download erfassen (kostet 1 Credit).
GET	`/v1/me`	Workspace-Infos und Credit-Guthaben.
POST	`/v1/keys`	Einen neuen API-Schlüssel ausstellen.
DELETE	`/v1/keys/:id`	Einen Schlüssel widerrufen.

Generierungen laufen asynchron — der POST liefert 202 mit einer Job-ID zurück; das eigentliche Rendering dauert 5–30 s. Frag statt zu blockieren /v1/generations/:id ab oder abonniere generation.completed Webhooks.

Asynchroner Generierungsablauf — POST stellt in die Warteschlange, ein Worker verarbeitet, ein Webhook meldet sich.

# 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

Lass KI-Agenten Bluweo als Werkzeug nutzen.

Das Model Context Protocol (MCP) ist der offene Standard von Anthropic, mit dem KI-Agenten externe Werkzeuge aufrufen können. Unser Server läuft unter /api/mcp (Streamable HTTP) — trag die URL in Claude Code, Claude Desktop, Cursor oder einen beliebigen MCP-fähigen Client ein, und der Agent kann mitten im Gespräch Icons suchen, ansehen, herunterladen und erzeugen. Nichts zu installieren.

Der MCP-Server stellt sieben Werkzeuge bereit:

search_icons — Suche nach Stichwort / Kategorie / Stil / Kollektion.
get_icon — Details plus eine 128-px-Vorschau, die der Agent sehen kann.
list_collections — kuratierte Bundles durchstöbern.
get_account — Tarif, Credits, Download-Limit.
download_icon — 512-px-/Originaldateien, exakt wie auf der Website abgerechnet.
generate_icon — Studio-Generierung aus einem Prompt.
list_generations — letzte Studio-Durchläufe mit ihren Bild-URLs.

search_icons funktioniert ohne Schlüssel (100 Aufrufe pro Tag). Jedes andere Werkzeug braucht einen persönlichen API-Schlüssel aus einem Studio-Plan, gesendet als Authorization: Bearer blu_live_… — erstellt unter Einstellungen → API-Schlüssel. MCP-Anleitung lesen →

MCP-Ablauf — Agent ruft ein Werkzeug auf, der MCP-Server übersetzt nach REST, die Ergebnisse gehen zurück an den Agenten.

# Claude Code — the Studio-plan key is required
claude mcp add --transport http realisticicon \
  https://realisticicon.com/api/mcp \
  --header "Authorization: Bearer blu_live_..."

Webhooks

Push-Benachrichtigungen für asynchrone Arbeit.

Richte im Dashboard eine Webhook-URL ein. Wir schicken per POST ein signiertes JSON, sobald etwas Erwähnenswertes passiert — vor allem, damit du den Generierungsstatus nicht abfragen musst.

Ereignisse, die wir senden:

generation.completed — die Ergebnisse stehen zum Download bereit.
generation.failed — Credits werden automatisch erstattet; die Payload enthält den Fehlergrund.
credits.low — dein Guthaben ist unter 20 % des Tarifkontingents gefallen.
subscription.updated — Tarif geändert / verlängert / gekündigt.

Jede Payload enthält einen Bluweo-Signature Header — ein HMAC-SHA256 des Bodys mit deinem Webhook-Secret. Prüfe immer, bevor du der Payload vertraust; ein unsignierter POST könnte eine gefälschte Anfrage sein.

# 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>

Ratenlimits und Kontingente

Pro Schlüssel, pro Monat — und pro Sekunde, damit es fair bleibt.

Für jeden Schlüssel gelten zwei Limits: Monatsvolumen (Kontingent der Tarifstufe) und kurzer Burst (10 Anfragen/s, zum Schutz gemeinsam genutzter Ressourcen). Beide werden bei jeder Antwort über die üblichen X-RateLimit-* Header zurückgegeben.

Tarif	API-Zugriff	Monatskontingent	Burst
Free	— (nur Web-UI)	—	—
Designer	— (nur Web-UI)	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

Generierungen und Downloads verbrauchen außerdem Credits aus dem Tarifkontingent — siehe Preise. Aufladungen per Credit-Pack erhöhen das API-Kontingent nicht; sie decken nur die Generierungskosten.

Wird das Limit überschritten, kommt 429 Too Many Requests zurück, zusammen mit einem Retry-After Header. Pausier deinen Traffic so lange und versuch es dann erneut — Zurückhalten wird nicht bestraft.

API-Zugriff nach Tarifstufe — Free und Designer nutzen nur das Web-UI; Studio schaltet die API frei.

# 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

Fehler

Übliche HTTP-Codes plus ein strukturierter JSON-Body.

Häufige Statuscodes:

Code	Bedeutung
`200`	OK — synchron erfolgreich.
`202`	Accepted — asynchroner Job in der Warteschlange.
`400`	Ungültiger Request-Body oder ungültige Query-Parameter.
`401`	API-Schlüssel fehlt oder ist ungültig.
`402`	Keine Credits mehr — aufladen und erneut versuchen.
`403`	Schlüssel gültig, aber die Tarifstufe erlaubt keinen API-Zugriff.
`404`	Ressource nicht gefunden.
`409`	Statuskonflikt (z. B. das Widerrufen eines bereits widerrufenen Schlüssels).
`429`	Ratenlimit erreicht — siehe `Retry-After`.
`5xx`	Unser Problem. Idempotente Anfragen wiederholen wir automatisch; du kannst sie gefahrlos selbst erneut senden.

Jeder Fehler-Body ist JSON: { "error": { "code", "message", "request_id" } }. Gib bei Kontakt mit dem Support die request_id an — dann können wir den Trace nachschlagen.

# 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..."
  }
}

Einschränkungen

Was die API heute nicht kann — damit die Erwartungen von Anfang an stimmen.

Kein Offline-/On-Premise-Betrieb. Generierungen laufen immer auf unserer Infrastruktur. Die Icon-Bibliothek lässt sich clientseitig cachen; die KI-Generierung nicht.
Keine Stapelgenerierung in einem einzigen Aufruf. Jeder POST /v1/icons/generate verarbeitet einen Prompt × bis zu 4 Ergebnisse. Für größere Stapel parallelisiere selbst; das Burst-Limit gilt weiterhin.
Maximale Promptlänge: 1.000 Zeichen. Längere Prompts werden mit 400 abgewiesen.
Inhaltsrichtlinie. Wir blockieren Prompts, die auf reale Personen, urheberrechtlich geschützte Figuren, NSFW- oder hasserfüllte Inhalte abzielen. Solche Fälle liefern 400 zurück, zusammen mit code: "policy_violation".
Ausgabeauflösung auf 2048 × 2048 begrenzt. Höhere Auflösungen erfordern einen individuellen Vertrag.
Generierungsdauer: 5–30 s. Im schlimmsten Fall (volle Warteschlange): bis zu 2 Min. Plan asynchron — nutz Webhooks statt enger Abfrageschleifen.
MCP-Transport: nur Streamable HTTP. Ein lokales stdio-Paket (npx) gibt es noch nicht — verbinde dich mit der gehosteten URL.
Kein SLA in der Studio-Stufe. Enterprise-Verträge enthalten 99,9 % Verfügbarkeit und namentlichen Support. Kontaktiere uns.

Brauchst du etwas, das diese Liste nicht hergibt?

Enterprise-Tarife schalten frei:

Individuelle Auflösungen und Stil-Feintuning auf deinen eigenen Markenassets.
Dedizierte Kapazität (keine gemeinsame Warteschlange).
VPC-/On-Premise-Deployment.
Namentlicher Support plus 99,9 % SLA.
Mengenpreise ab 10.000 Anfragen/Monat.

Mit dem Vertrieb sprechen →

Versionierung

v1 ist aktuell. Breaking Changes erscheinen als v2.

Die Version steht im URL-Pfad: /v1/.... Innerhalb einer Version nehmen wir nur additive Änderungen vor — neue Felder, neue Endpunkte, neue Ereignistypen. Wir entfernen innerhalb einer Version niemals ein Feld und ändern nie dessen Typ.

Wenn wir v2, v1 veröffentlichen, bleibt die Vorgängerversion mindestens 12 Monate aktiv, mit einem Abschaltdatum, das wir über den changelog Endpunkt und per E-Mail an alle API-Nutzer ankündigen.

Changelog: GET /v1/changelog liefert jede Änderung seit dem Start, die neueste zuerst.
Statusseite: status.bluweo.com für Live-Verfügbarkeit und Störungshistorie.
E-Mail-Updates: im Dashboard aktivierbar. Wir schreiben nur bei angekündigten Breaking Changes und größeren Störungen.

# 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)"
  ]
}

Bereit loszulegen?

Erzeug deinen ersten API-Schlüssel im Dashboard, oder sprich uns an, wenn du einen individuellen Vertrag brauchst.

Auf Studio upgraden Mit dem Vertrieb sprechen