Costruisci con l’API di icone 3D.

Panoramica

Tre modi per integrarsi, una piattaforma.

L’API di Bluweo dà ad app di terze parti e agenti IA accesso programmatico a tutto ciò che fa l’interfaccia web dello studio: cercare nella libreria di icone 3D, generare nuove varianti a partire da un prompt, gestire i download e restare in ascolto degli eventi asincroni.

• REST API — chiamate sincrone per qualsiasi client HTTP.
• MCP server — strumento pronto all’uso per Claude, Cursor e qualsiasi agente compatibile con MCP.
• Webhooks — invio asincrono per generazioni lunghe ed eventi di fatturazione.

Attenzione: L’accesso all’API fa parte del piano Studio. I piani Free e Designer usano solo l’interfaccia web — vedi i limiti di utilizzo più sotto.

Avvio rapido

La tua prima chiamata in meno di 60 secondi.

1. Crea un account e passa a Studio.
2. Genera una chiave API in /dashboard/billing → API keys. Le chiavi iniziano con blu_live_.
3. Inviala come token Bearer a ogni richiesta.
4. Chiama GET /v1/icons/search?q=fox per verificare che la chiave funzioni.

URL di base: https://api.bluweo.com. Tutte le richieste devono usare HTTPS — l’API rifiuta l’HTTP in chiaro.

Autenticazione

Chiavi Bearer, legate a uno spazio di lavoro.

Ogni richiesta all’API deve includere un’intestazione Authorization: Bearer <key> . Le chiavi vengono emesse dalla tua dashboard e sono legate a un solo spazio di lavoro; il livello della chiave determina il limite di utilizzo.

• Formato della chiave: blu_live_* (produzione) oppure blu_test_* (sandbox — nessun addebito, risultati con filigrana).
• Mostrata una sola volta: conserviamo le chiavi sotto forma di hash lato server. Se ne perdi una, sostituiscila.
• Sostituzione: una chiave si può sostituire con POST /v1/keys/:id/roll; quella vecchia continua a funzionare per 24 ore, così la migrazione è più semplice.
• Revoca: DELETE /v1/keys/:id ha effetto immediato.

API REST

Cercare, generare, scaricare, gestire.

Tutti gli endpoint si trovano sotto /v1/. JSON in entrata, JSON in uscita. Campi in snake_case. Marche temporali ISO-8601 in UTC.

Le generazioni sono asincrone — il POST restituisce 202 con un identificativo del lavoro; il rendering vero e proprio richiede 5-30 s. Invece di bloccarti, interroga /v1/generations/:id oppure iscriviti ai generation.completed webhook.

Server MCP

Lascia che gli agenti IA usino Bluweo come strumento.

Il Model Context Protocol (MCP) è lo standard aperto di Anthropic che consente agli agenti IA di chiamare strumenti esterni. Il nostro server è ospitato su /api/mcp (Streamable HTTP): aggiungi l’URL a Claude Code, Claude Desktop, Cursor o a qualsiasi client compatibile con MCP e l’agente potrà cercare, vedere in anteprima, scaricare e generare icone in piena conversazione. Non c’è nulla da installare.

Il server MCP mette a disposizione sette strumenti:

• search_icons — ricerca per parola chiave / categoria / stile / collezione.
• get_icon — dettagli più un’anteprima da 128 px che l’agente può vedere.
• list_collections — sfoglia i pacchetti selezionati.
• get_account — piano, crediti, tetto di download.
• download_icon — file da 512 px o originali, addebitati esattamente come sul sito.
• generate_icon — generazione nello Studio a partire da un prompt.
• list_generations — esecuzioni recenti dello Studio con gli URL delle immagini.

search_icons funziona senza chiave (100 chiamate al giorno). Ogni altro strumento richiede una chiave API personale di un piano Studio, inviata come Authorization: Bearer blu_live_… — creata in Impostazioni → Chiavi API. Leggi la guida MCP →

Webhook

Notifiche push per il lavoro asincrono.

Configura un URL di webhook nella tua dashboard. Inviamo con POST un JSON firmato ogni volta che succede qualcosa di rilevante, soprattutto per evitarti di dover controllare in continuazione lo stato delle generazioni.

Gli eventi che inviamo:

• generation.completed — i risultati sono pronti da scaricare.
• generation.failed — i crediti vengono restituiti automaticamente; il payload contiene il motivo dell’errore.
• credits.low — il tuo saldo è sceso sotto il 20% della quota del piano.
• subscription.updated — piano cambiato / rinnovato / disdetto.

Ogni payload include un’intestazione Bluweo-Signature — un HMAC-SHA256 del corpo calcolato con il tuo segreto del webhook. Verifica sempre prima di fidarti del payload; un POST non firmato potrebbe essere una richiesta contraffatta.

Limiti di utilizzo e quote

Per chiave e per mese — e al secondo, perché sia equo per tutti.

A ogni chiave si applicano due limiti: volume mensile (quota del livello di piano) e picchi brevi (10 richieste al secondo, per proteggere le risorse condivise). Entrambi vengono restituiti a ogni risposta tramite le consuete intestazioni X-RateLimit-* .

Generazioni e download consumano anche crediti dalla quota del piano — vedi Prezzi. Ricaricare con un pacchetto di crediti non amplia la quota API; copre solo il costo della generazione.

Superare il limite restituisce 429 Too Many Requests insieme a un’intestazione Retry-After . Ferma il traffico per quel tempo e riprova — rallentare non comporta alcuna penalità.

Errori

Codici HTTP consueti più un corpo JSON strutturato.

Codici di stato più comuni:

Ogni corpo di errore è in JSON: { "error": { "code", "message", "request_id" } }. Quando scrivi all’assistenza, includi il request_id — così possiamo risalire alla traccia.

Limitazioni

Cosa l’API non sa fare oggi — meglio dirlo subito.

• Niente uso offline né installazione in locale. Le generazioni girano sempre sulla nostra infrastruttura. La libreria di icone si può mettere in cache lato client; la generazione con IA no.
• Niente generazione in blocco con una sola chiamata. Ogni POST /v1/icons/generate gestisce un prompt × massimo 4 risultati. Per lotti più grandi distribuisci tu le chiamate; il limite sui picchi resta valido.
• Lunghezza massima del prompt: 1.000 caratteri. I prompt più lunghi vengono rifiutati con un 400.
• Politica sui contenuti. Blocchiamo i prompt che chiedono persone reali, personaggi protetti da copyright, contenuti per adulti o d’odio. In quei casi rispondiamo con 400 e con code: "policy_violation".
• Risoluzione dei risultati limitata a 2048 × 2048. Oltre serve un contratto su misura.
• Tempo di generazione: 5-30 s. Nel caso peggiore (coda satura): fino a 2 minuti. Progetta in ottica asincrona — usa i webhook, non cicli di controllo serrati.
• Trasporto MCP: solo Streamable HTTP. Non esiste ancora un pacchetto stdio (npx) locale: collegati all’URL ospitato.
• Nessun SLA nel livello Studio. I contratti Enterprise includono il 99,9% di disponibilità e un referente dedicato. Scrivici.

Versionamento

v1 è la versione attuale. Le modifiche che rompono la compatibilità escono come v2.

La versione sta nel percorso dell’URL: /v1/.... All’interno di una versione facciamo solo modifiche additive — nuovi campi, nuovi endpoint, nuovi tipi di evento. Non rimuoveremo mai un campo né ne cambieremo il tipo all’interno della stessa versione.

Quando pubblichiamo v2, v1 la versione precedente resta attiva per almeno 12 mesi e annunciamo la data di dismissione tramite l’endpoint changelog e via email a tutti gli utenti dell’API.

• Registro delle modifiche: GET /v1/changelog restituisce tutte le modifiche dal lancio, dalla più recente.
• Pagina di stato: status.bluweo.com per la disponibilità in tempo reale e lo storico dei disservizi.
• Aggiornamenti via email: si attivano dalla dashboard. Scriviamo solo per annunciare modifiche che rompono la compatibilità e per i disservizi gravi.