API roadmap — Développeurs

Vue d’ensemble

Trois portes d’entrée, une plateforme.

L’API Bluweo donne aux applications tierces et aux agents IA un accès programmatique à tout ce que fait l’interface web du studio — chercher dans la bibliothèque d’icônes 3D, générer de nouvelles variantes à partir de prompts, gérer les téléchargements et écouter les événements asynchrones.

REST API — appels synchrones pour n’importe quel client HTTP.
MCP server — outil prêt à l’emploi pour Claude, Cursor et tout agent compatible MCP.
Webhooks — notifications asynchrones pour les générations longues et les événements de facturation.

À noter : L’accès à l’API fait partie de la formule Studio. Les formules Free et Designer se limitent à l’interface web — voir les limites de débit plus bas.

REST, MCP et webhooks — trois portes d’entrée qui rayonnent depuis la plateforme Bluweo.

Démarrage rapide

Votre premier appel en moins de 60 secondes.

Créez un compte et passez à Studio.
Générez une clé API dans /dashboard/billing → API keys. Les clés commencent par blu_live_.
Envoyez-la comme jeton Bearer à chaque requête.
Appelez GET /v1/icons/search?q=fox pour vérifier que la clé fonctionne.

URL de base : https://api.bluweo.com. Toutes les requêtes doivent passer en HTTPS — l’API rejette le HTTP simple.

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

Authentification

Clés Bearer, limitées à un espace de travail.

Chaque requête API doit inclure un en-tête Authorization: Bearer <key> . Les clés sont émises depuis votre tableau de bord et rattachées à un seul espace de travail ; le palier de la clé détermine la limite de débit.

Format de clé : blu_live_* (production) ou blu_test_* (bac à sable — sans facturation, résultats filigranés).
Affichée une seule fois : nous stockons les clés hachées côté serveur. Si vous en perdez une, remplacez-la.
Rotation : une clé peut être remplacée avec POST /v1/keys/:id/roll; l’ancienne continue de fonctionner 24 h pour faciliter la transition.
Révocation : DELETE /v1/keys/:id prend effet immédiatement.

Authentification par clé API — en-tête Bearer à chaque appel.

API REST

Chercher, générer, télécharger, gérer.

Tous les points d’accès se trouvent sous /v1/. JSON en entrée, JSON en sortie. Champs en snake_case. Horodatages ISO-8601 en UTC.

Méthode	Chemin	Objet
GET	`/v1/icons`	Lister les icônes ; filtrer par tag, style, couleur.
GET	`/v1/icons/search`	Recherche plein texte dans le catalogue.
GET	`/v1/icons/:id`	Détail d’une icône et de ses variantes.
POST	`/v1/icons/generate`	Lancer une génération par IA. Renvoie 202.
GET	`/v1/generations/:id`	Interroger l’état / les résultats d’une génération.
POST	`/v1/icons/:id/variants`	Créer une variante de style ou de couleur depuis une icône existante.
GET	`/v1/collections`	Lister les collections sélectionnées.
POST	`/v1/downloads`	Enregistrer un téléchargement (coûte 1 crédit).
GET	`/v1/me`	Infos de l’espace de travail et solde de crédits.
POST	`/v1/keys`	Émettre une nouvelle clé API.
DELETE	`/v1/keys/:id`	Révoquer une clé.

Les générations sont asynchrones — le POST renvoie 202 avec un identifiant de tâche ; le rendu prend en réalité 5 à 30 s. Plutôt que de bloquer, interrogez /v1/generations/:id ou abonnez-vous aux generation.completed webhooks.

Flux de génération asynchrone — le POST met en file, un worker traite, un webhook prévient.

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

Serveur MCP

Laissez les agents IA utiliser Bluweo comme un outil.

Le Model Context Protocol (MCP) est la norme ouverte d’Anthropic qui permet aux agents IA d’appeler des outils externes. Notre serveur est hébergé sur /api/mcp (Streamable HTTP) — ajoutez cette URL à Claude Code, Claude Desktop, Cursor ou tout client compatible MCP, et l’agent pourra chercher, prévisualiser, télécharger et générer des icônes en pleine conversation. Rien à installer.

Le serveur MCP expose sept outils :

search_icons — recherche par mot-clé / catégorie / style / collection.
get_icon — détails et aperçu 128 px que l’agent peut voir.
list_collections — parcourir les ensembles sélectionnés.
get_account — formule, crédits, plafond de téléchargement.
download_icon — fichiers 512 px / original, facturés exactement comme sur le site.
generate_icon — génération Studio à partir d’un prompt.
list_generations — exécutions Studio récentes avec les URL de leurs images.

search_icons fonctionne sans clé (100 appels par jour). Tous les autres outils exigent une clé API personnelle d’un forfait Studio, envoyée via Authorization: Bearer blu_live_… — créée dans Paramètres → Clés API. Lire le guide MCP →

Flux MCP — l’agent appelle un outil, le serveur MCP traduit en REST, les résultats reviennent à l’agent.

# 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

Notifications push pour le travail asynchrone.

Configurez une URL de webhook dans votre tableau de bord. Nous envoyons en POST une charge utile JSON signée dès qu’il se passe quelque chose de notable — surtout pour vous éviter d’interroger l’état des générations.

Les événements que nous émettons :

generation.completed — les résultats sont prêts à être téléchargés.
generation.failed — les crédits sont remboursés automatiquement ; la charge utile contient la raison de l’échec.
credits.low — votre solde est passé sous 20 % du quota de la formule.
subscription.updated — formule modifiée / renouvelée / annulée.

Chaque charge utile inclut un en-tête Bluweo-Signature — un HMAC-SHA256 du corps calculé avec votre secret de webhook. Vérifiez toujours avant de faire confiance à la charge utile; un POST non signé pourrait être une requête falsifiée.

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

Limites de débit et quotas

Par clé, par mois — et par seconde, pour que ce soit équitable.

Deux limites s’appliquent à chaque clé : le volume mensuel (quota du palier) et les pics courts (10 req/s, pour protéger les ressources partagées). Les deux sont renvoyées à chaque réponse via les en-têtes X-RateLimit-* standard.

Formule	Accès à l’API	Quota mensuel	Pic
Free	— (interface web uniquement)	—	—
Designer	— (interface web uniquement)	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

Les générations et les téléchargements consomment aussi des crédits du quota de la formule — voir Tarifs. Recharger avec un pack de crédits n’augmente pas le quota API ; cela ne finance que le coût de génération.

Dépasser la limite renvoie 429 Too Many Requests avec un en-tête Retry-After . Suspendez le trafic pendant ce délai puis réessayez — lever le pied n’entraîne aucune pénalité.

Accès à l’API par palier — Free et Designer se limitent à l’interface web ; Studio débloque l’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

Erreurs

Codes HTTP classiques et corps JSON structuré.

Codes de statut courants :

Code	Signification
`200`	OK — succès synchrone.
`202`	Accepted — tâche asynchrone mise en file.
`400`	Corps de requête ou paramètres invalides.
`401`	Clé API absente ou invalide.
`402`	Plus de crédits — rechargez puis réessayez.
`403`	Clé valide, mais le palier ne donne pas accès à l’API.
`404`	Ressource introuvable.
`409`	Conflit d’état (par ex. révoquer une clé déjà révoquée).
`429`	Limite de débit atteinte — voir `Retry-After`.
`5xx`	Le problème vient de chez nous. Nous relançons automatiquement les requêtes idempotentes ; vous pouvez réessayer sans risque.

Tous les corps d’erreur sont en JSON : { "error": { "code", "message", "request_id" } }. Indiquez le request_id quand vous contactez l’assistance — nous pourrons retrouver la 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..."
  }
}

Limites

Ce que l’API ne sait pas faire aujourd’hui — autant le dire tout de suite.

Pas de hors-ligne ni d’auto-hébergement. Les générations tournent toujours sur notre infrastructure. La bibliothèque d’icônes peut être mise en cache côté client ; la génération par IA, non.
Pas de génération par lot en un seul appel. Chaque POST /v1/icons/generate traite un prompt × 4 résultats maximum. Pour des lots plus grands, parallélisez vous-même ; la limite de pic reste applicable.
Longueur maximale du prompt : 1 000 caractères. Les prompts plus longs sont rejetés avec un 400.
Politique de contenu. Nous bloquons les prompts qui visent des personnes réelles, des personnages sous droits d’auteur, du contenu pour adultes ou haineux. Les refus renvoient un 400 avec code: "policy_violation".
Résolution de sortie plafonnée à 2048 × 2048. Au-delà, il faut un contrat sur mesure.
Latence de génération : 5 à 30 s. Au pire (file saturée) : jusqu’à 2 min. Prévoyez de l’asynchrone — utilisez les webhooks, pas des boucles d’interrogation serrées.
Transport MCP : Streamable HTTP uniquement. Il n’existe pas encore de paquet stdio (npx) local — connectez-vous à l’URL hébergée.
Pas de SLA au palier Studio. Les contrats Enterprise incluent 99,9 % de disponibilité et un interlocuteur dédié. Contactez-nous.

Il vous faut quelque chose que cette liste ne couvre pas ?

Les formules Enterprise débloquent :

Résolutions sur mesure et affinage de styles sur vos propres éléments de marque.
Capacité dédiée (pas de file partagée).
Déploiement en VPC / sur vos serveurs.
Interlocuteur dédié et SLA à 99,9 %.
Tarifs de volume au-delà de 10 000 requêtes / mois.

Parler au service commercial →

Versionnage

v1 est la version en cours. Les changements incompatibles sortent en v2.

La version figure dans le chemin de l’URL : /v1/.... À l’intérieur d’une version, nous ne faisons que des changements additifs — nouveaux champs, nouveaux points d’accès, nouveaux types d’événements. Nous ne supprimerons jamais un champ ni ne changerons son type à l’intérieur d’une version.

Quand nous publions v2, v1 la version précédente reste en service au moins 12 mois avec une date de retrait annoncée via le point d’accès changelog et par e-mail à tous les utilisateurs de l’API.

Journal des changements : GET /v1/changelog renvoie tous les changements depuis le lancement, du plus récent au plus ancien.
Page de statut : status.bluweo.com pour la disponibilité en direct et l’historique des incidents.
Mises à jour par e-mail : activables depuis le tableau de bord. Nous n’écrivons que pour annoncer un changement incompatible ou un incident majeur.

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

Prêt à construire ?

Générez votre première clé API depuis le tableau de bord, ou écrivez-nous s’il vous faut un contrat sur mesure.

Passer à Studio Parler au service commercial