API roadmap — Desarrolladores

Visión general

Tres formas de integrarse, una plataforma.

La API de Bluweo da a las apps de terceros y a los agentes de IA acceso programático a todo lo que hace la interfaz web del estudio: buscar en la biblioteca de iconos 3D, generar variantes nuevas a partir de prompts, gestionar descargas y escuchar eventos asíncronos.

REST API — llamadas síncronas para cualquier cliente HTTP.
MCP server — herramienta lista para usar en Claude, Cursor y cualquier agente compatible con MCP.
Webhooks — envío asíncrono para generaciones largas y eventos de facturación.

Ojo: El acceso a la API forma parte del plan Studio. Los planes Free y Designer solo usan la interfaz web — consulta los límites de uso más abajo.

REST, MCP y webhooks: tres formas de integrarse que parten de la plataforma Bluweo.

Inicio rápido

Tu primera llamada en menos de 60 segundos.

Crea una cuenta y sube al plan Studio.
Genera una clave de API en /dashboard/billing → API keys. Las claves empiezan por blu_live_.
Envíala como token Bearer en cada solicitud.
Llama a GET /v1/icons/search?q=fox para confirmar que la clave funciona.

URL base: https://api.bluweo.com. Todas las solicitudes deben ir por HTTPS — la API rechaza el HTTP sin cifrar.

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

Autenticación

Claves Bearer, con alcance de espacio de trabajo.

Toda solicitud a la API debe incluir una cabecera Authorization: Bearer <key> . Las claves se emiten desde tu panel y quedan ligadas a un único espacio de trabajo; el nivel de la clave determina el límite de uso.

Formato de la clave: blu_live_* (producción) o blu_test_* (sandbox — sin cobros, resultados con marca de agua).
Se muestra una sola vez: guardamos las claves con hash en el servidor. Si pierdes una, sustitúyela.
Sustitución: una clave se puede sustituir con POST /v1/keys/:id/roll; la clave anterior sigue funcionando 24 h para facilitar la migración.
Revocación: DELETE /v1/keys/:id surte efecto de inmediato.

Autenticación con clave de API — cabecera Bearer en cada llamada.

API REST

Buscar, generar, descargar, gestionar.

Todos los endpoints están bajo /v1/. JSON de entrada, JSON de salida. Campos en snake_case. Marcas de tiempo en ISO-8601 y UTC.

Método	Ruta	Para qué sirve
GET	`/v1/icons`	Listar iconos; filtrar por etiqueta, estilo y color.
GET	`/v1/icons/search`	Búsqueda de texto completo en el catálogo.
GET	`/v1/icons/:id`	Detalle de un icono y sus variantes.
POST	`/v1/icons/generate`	Iniciar una generación con IA. Devuelve 202.
GET	`/v1/generations/:id`	Consultar el estado o los resultados de una generación.
POST	`/v1/icons/:id/variants`	Crear una variante de estilo o color a partir de un icono existente.
GET	`/v1/collections`	Listar las colecciones seleccionadas.
POST	`/v1/downloads`	Registrar una descarga (gasta 1 crédito).
GET	`/v1/me`	Información del espacio de trabajo y saldo de créditos.
POST	`/v1/keys`	Emitir una clave de API nueva.
DELETE	`/v1/keys/:id`	Revocar una clave.

Las generaciones son asíncronas — el POST devuelve 202 con un identificador de trabajo; el renderizado real tarda entre 5 y 30 s. En lugar de bloquear, consulta /v1/generations/:id o suscríbete a los generation.completed webhooks.

Flujo de generación asíncrona: el POST encola, un worker procesa, un webhook avisa.

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

Servidor MCP

Deja que los agentes de IA usen Bluweo como herramienta.

El Model Context Protocol (MCP) es el estándar abierto de Anthropic que permite a los agentes de IA llamar a herramientas externas. Nuestro servidor está alojado en /api/mcp (Streamable HTTP): añade la URL a Claude Code, Claude Desktop, Cursor o cualquier cliente compatible con MCP y el agente podrá buscar, previsualizar, descargar y generar iconos en plena conversación. No hay nada que instalar.

El servidor MCP expone siete herramientas:

search_icons — búsqueda por palabra clave / categoría / estilo / colección.
get_icon — detalles más una previsualización de 128 px que el agente puede ver.
list_collections — explorar los conjuntos seleccionados.
get_account — plan, créditos y límite de descargas.
download_icon — archivos de 512 px u originales, cobrados igual que en el sitio web.
generate_icon — generación en Studio a partir de un prompt.
list_generations — ejecuciones recientes de Studio con las URL de sus imágenes.

search_icons funciona sin clave (100 llamadas al día). Las demás herramientas necesitan una clave de API personal de un plan Studio, enviada como Authorization: Bearer blu_live_… — creada en Ajustes → Claves de API. Leer la guía de MCP →

Flujo MCP: el agente llama a una herramienta, el servidor MCP lo traduce a REST y los resultados vuelven al agente.

# 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

Notificaciones push para el trabajo asíncrono.

Configura una URL de webhook en tu panel. Enviamos por POST un JSON firmado cada vez que ocurre algo relevante, sobre todo para que no tengas que ir consultando el estado de las generaciones.

Eventos que emitimos:

generation.completed — los resultados están listos para descargar.
generation.failed — los créditos se devuelven automáticamente; el payload incluye el motivo del error.
credits.low — tu saldo ha bajado del 20 % de la cuota del plan.
subscription.updated — plan cambiado / renovado / cancelado.

Todos los payloads llevan una cabecera Bluweo-Signature — un HMAC-SHA256 del cuerpo calculado con tu secreto de webhook. Verifica siempre antes de fiarte del payload; un POST sin firmar podría ser una solicitud falsificada.

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

Límites de uso y cuotas

Por clave y por mes — y por segundo, para que sea justo para todos.

A cada clave se le aplican dos límites: volumen mensual (cuota según el nivel del plan) y picos cortos (10 solicitudes/s, para proteger los recursos compartidos). Ambos se devuelven en cada respuesta mediante las cabeceras X-RateLimit-* estándar.

Plan	Acceso a la API	Cuota mensual	Picos
Free	— (solo interfaz web)	—	—
Designer	— (solo interfaz web)	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

Las generaciones y las descargas además gastan créditos de la cuota del plan — consulta Precios. Recargar con packs de créditos no amplía la cuota de la API; solo cubre el coste de la generación.

Superar el límite devuelve 429 Too Many Requests junto con una cabecera Retry-After . Corta el tráfico ese tiempo y vuelve a intentarlo — esperar no tiene ninguna penalización.

Acceso a la API por nivel de plan: Free y Designer solo usan la interfaz web; Studio desbloquea la 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

Errores

Códigos HTTP convencionales y un cuerpo JSON estructurado.

Códigos de estado habituales:

Código	Significado
`200`	OK — éxito síncrono.
`202`	Accepted — trabajo asíncrono en cola.
`400`	Cuerpo o parámetros de la solicitud no válidos.
`401`	Falta la clave de API o no es válida.
`402`	Sin créditos — recarga y vuelve a intentarlo.
`403`	La clave es válida, pero el nivel del plan no da acceso a la API.
`404`	Recurso no encontrado.
`409`	Conflicto de estado (por ejemplo, revocar una clave ya revocada).
`429`	Límite de uso alcanzado — consulta `Retry-After`.
`5xx`	Es problema nuestro. Reintentamos automáticamente las solicitudes idempotentes; también puedes reintentar tú sin riesgo.

Todos los cuerpos de error son JSON: { "error": { "code", "message", "request_id" } }. Incluye el request_id cuando escribas a soporte — así podremos rastrearlo.

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

Limitaciones

Lo que la API no puede hacer hoy — mejor dejarlo claro desde el principio.

Sin modo sin conexión ni instalación propia. Las generaciones siempre se ejecutan en nuestra infraestructura. La biblioteca de iconos se puede cachear en el cliente; la generación con IA no.
Sin generación por lotes en una sola llamada. Cada POST /v1/icons/generate procesa un prompt × hasta 4 resultados. Para lotes mayores, reparte tú las llamadas; el límite de picos sigue aplicándose.
Longitud máxima del prompt: 1.000 caracteres. Los prompts más largos se rechazan con un 400.
Política de contenido. Bloqueamos los prompts que piden personas reales, personajes con derechos de autor, contenido sexual o de odio. Esos casos devuelven 400 junto con code: "policy_violation".
Resolución de salida limitada a 2048 × 2048. Por encima hace falta un contrato a medida.
Latencia de generación: de 5 a 30 s. En el peor caso (cola saturada): hasta 2 min. Diseña pensando en asíncrono — usa webhooks, no bucles de consulta constantes.
Transporte MCP: solo Streamable HTTP. Aún no hay paquete stdio (npx) local: conéctate a la URL alojada.
Sin SLA en el nivel Studio. Los contratos Enterprise incluyen un 99,9 % de disponibilidad y soporte con persona asignada. Escríbenos.

¿Necesitas algo que esta lista no cubre?

Los planes Enterprise desbloquean:

Resoluciones a medida y ajuste fino de estilos con tus propios recursos de marca.
Capacidad dedicada (sin cola compartida).
Despliegue en VPC o en tus servidores.
Soporte con persona asignada y SLA del 99,9 %.
Precio por volumen a partir de 10.000 solicitudes al mes.

Habla con ventas →

Versionado

v1 es la versión actual. Los cambios que rompen compatibilidad salen como v2.

La versión va en la ruta de la URL: /v1/.... Dentro de una versión solo hacemos cambios aditivos — campos nuevos, endpoints nuevos, tipos de evento nuevos. Nunca eliminaremos un campo ni cambiaremos su tipo dentro de una misma versión.

Cuando publiquemos v2, v1 la versión anterior seguirá activa al menos 12 meses y anunciaremos la fecha de retirada a través del endpoint changelog y por correo a todos los usuarios de la API.

Registro de cambios: GET /v1/changelog devuelve todos los cambios desde el lanzamiento, del más reciente al más antiguo.
Página de estado: status.bluweo.com para ver la disponibilidad en directo y el historial de incidencias.
Avisos por correo: puedes activarlos desde el panel. Solo escribimos para avisar de cambios que rompen compatibilidad y de incidencias graves.

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

¿Listo para construir?

Genera tu primera clave de API desde el panel, o escríbenos si necesitas un contrato a medida.

Subir a Studio Habla con ventas