API roadmap — Desenvolvedores

Visão geral

Três formas de integrar, uma plataforma.

A API da Bluweo dá a apps de terceiros e agentes de IA acesso programático a tudo o que a interface web do estúdio faz: buscar na biblioteca de ícones 3D, gerar variantes novas a partir de prompts, gerenciar downloads e ouvir eventos assíncronos.

REST API — chamadas síncronas para qualquer cliente HTTP.
MCP server — ferramenta pronta para usar no Claude, no Cursor e em qualquer agente compatível com MCP.
Webhooks — envio assíncrono para gerações demoradas e eventos de cobrança.

Atenção: O acesso à API faz parte do plano Studio. Os planos Free e Designer usam só a interface web — veja os limites de uso abaixo.

REST, MCP e webhooks: três formas de integrar que partem da plataforma Bluweo.

Início rápido

Sua primeira chamada em menos de 60 segundos.

Crie uma conta e suba para o Studio.
Gere uma chave de API em /dashboard/billing → API keys. As chaves começam com blu_live_.
Envie como token Bearer em toda requisição.
Chame GET /v1/icons/search?q=fox para confirmar que a chave funciona.

URL base: https://api.bluweo.com. Todas as requisições precisam usar HTTPS — a API recusa HTTP puro.

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

Autenticação

Chaves Bearer, ligadas a um espaço de trabalho.

Toda requisição à API precisa incluir um cabeçalho Authorization: Bearer <key> . As chaves saem do seu painel e ficam ligadas a um único espaço de trabalho; o nível da chave define o limite de uso.

Formato da chave: blu_live_* (produção) ou blu_test_* (sandbox — sem cobrança, resultados com marca d’água).
Aparece uma vez só: guardamos as chaves com hash no servidor. Se você perder uma, troque por outra.
Troca: dá para trocar uma chave com POST /v1/keys/:id/roll; a antiga continua funcionando por 24 h para facilitar a migração.
Revogação: DELETE /v1/keys/:id vale na hora.

Autenticação por chave de API — cabeçalho Bearer em toda chamada.

API REST

Buscar, gerar, baixar, gerenciar.

Todos os endpoints ficam abaixo de /v1/. JSON na entrada, JSON na saída. Campos em snake_case. Horários em ISO-8601 e UTC.

Método	Caminho	Para que serve
GET	`/v1/icons`	Listar ícones; filtrar por tag, estilo e cor.
GET	`/v1/icons/search`	Busca de texto completo no catálogo.
GET	`/v1/icons/:id`	Detalhe de um ícone e suas variantes.
POST	`/v1/icons/generate`	Inicia uma geração com IA. Devolve 202.
GET	`/v1/generations/:id`	Consulta o estado e os resultados de uma geração.
POST	`/v1/icons/:id/variants`	Cria uma variante de estilo ou cor a partir de um ícone existente.
GET	`/v1/collections`	Lista as coleções selecionadas.
POST	`/v1/downloads`	Registra um download (gasta 1 crédito).
GET	`/v1/me`	Informações do espaço de trabalho e saldo de créditos.
POST	`/v1/keys`	Emite uma chave de API nova.
DELETE	`/v1/keys/:id`	Revoga uma chave.

As gerações são assíncronas — o POST devolve 202 com um identificador do trabalho; a renderização de fato leva de 5 a 30 s. Em vez de travar, consulte /v1/generations/:id ou assine os generation.completed webhooks.

Fluxo de geração assíncrona: o POST coloca na fila, um worker processa, um 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

Deixe os agentes de IA usarem a Bluweo como ferramenta.

O Model Context Protocol (MCP) é o padrão aberto da Anthropic que permite a agentes de IA chamar ferramentas externas. Nosso servidor fica hospedado em /api/mcp (Streamable HTTP): adicione essa URL ao Claude Code, ao Claude Desktop, ao Cursor ou a qualquer cliente compatível com MCP e o agente vai poder buscar, pré-visualizar, baixar e gerar ícones no meio da conversa. Não há nada para instalar.

O servidor MCP oferece sete ferramentas:

search_icons — busca por palavra-chave / categoria / estilo / coleção.
get_icon — detalhes mais uma prévia de 128 px que o agente consegue ver.
list_collections — navegar pelos pacotes selecionados.
get_account — plano, créditos e limite de downloads.
download_icon — arquivos de 512 px ou originais, cobrados exatamente como no site.
generate_icon — geração no Studio a partir de um prompt.
list_generations — execuções recentes do Studio com as URLs das imagens.

search_icons funciona sem chave (100 chamadas por dia). As demais ferramentas exigem uma chave de API pessoal de um plano Studio, enviada como Authorization: Bearer blu_live_… — criada em Configurações → Chaves de API. Ler o guia do MCP →

Fluxo MCP: o agente chama uma ferramenta, o servidor MCP traduz para REST, os resultados voltam para o 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

Notificações push para o trabalho assíncrono.

Configure uma URL de webhook no seu painel. A gente envia por POST um JSON assinado sempre que acontece algo relevante — principalmente para você não precisar ficar consultando o estado das gerações.

Os eventos que enviamos:

generation.completed — os resultados estão prontos para baixar.
generation.failed — os créditos voltam automaticamente; o payload traz o motivo do erro.
credits.low — seu saldo caiu abaixo de 20% da cota do plano.
subscription.updated — plano alterado / renovado / cancelado.

Todo payload traz um cabeçalho Bluweo-Signature — um HMAC-SHA256 do corpo calculado com o seu segredo de webhook. Sempre verifique antes de confiar no payload; um POST sem assinatura pode ser uma requisição forjada.

# 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 uso e cotas

Por chave e por mês — e por segundo, para ficar justo com todo mundo.

Toda chave tem dois limites: volume mensal (cota do nível do plano) e picos curtos (10 requisições por segundo, para proteger os recursos compartilhados). Os dois voltam em toda resposta pelos cabeçalhos X-RateLimit-* padrão.

Plano	Acesso à API	Cota mensal	Picos
Free	— (só interface web)	—	—
Designer	— (só interface web)	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

Gerações e downloads também gastam créditos da cota do plano — veja Preços. Recarregar com pacote de créditos não aumenta a cota da API; só cobre o custo da geração.

Passar do limite devolve 429 Too Many Requests junto com um cabeçalho Retry-After . Pare o tráfego por esse tempo e tente de novo — segurar o ritmo não tem penalidade nenhuma.

Acesso à API por nível de plano: Free e Designer usam só a interface web; o Studio libera a 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

Erros

Códigos HTTP comuns e um corpo JSON estruturado.

Códigos de status mais comuns:

Código	Significado
`200`	OK — sucesso síncrono.
`202`	Accepted — trabalho assíncrono na fila.
`400`	Corpo da requisição ou parâmetros inválidos.
`401`	Chave de API ausente ou inválida.
`402`	Sem créditos — recarregue e tente de novo.
`403`	Chave válida, mas o nível do plano não dá acesso à API.
`404`	Recurso não encontrado.
`409`	Conflito de estado (por exemplo, revogar uma chave já revogada).
`429`	Limite de uso atingido — veja `Retry-After`.
`5xx`	O problema é nosso. A gente repete automaticamente as requisições idempotentes; você também pode tentar de novo sem risco.

Todo corpo de erro vem em JSON: { "error": { "code", "message", "request_id" } }. Inclua o request_id quando falar com o suporte — assim conseguimos puxar o rastro.

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

Limitações

O que a API não faz hoje — melhor já deixar claro.

Sem uso offline nem instalação própria. As gerações sempre rodam na nossa infraestrutura. A biblioteca de ícones pode ficar em cache no cliente; a geração com IA, não.
Sem geração em lote numa única chamada. Cada POST /v1/icons/generate trata um prompt × até 4 resultados. Para lotes maiores, divida você mesmo as chamadas; o limite de picos continua valendo.
Tamanho máximo do prompt: 1.000 caracteres. Prompts maiores são recusados com 400.
Política de conteúdo. A gente bloqueia prompts que pedem pessoas reais, personagens protegidos por direitos autorais, conteúdo adulto ou de ódio. Nesses casos a resposta é 400 junto com code: "policy_violation".
Resolução de saída limitada a 2048 × 2048. Acima disso é preciso um contrato sob medida.
Tempo de geração: de 5 a 30 s. No pior caso (fila cheia): até 2 min. Planeje de forma assíncrona — use webhooks, não laços de consulta apertados.
Transporte MCP: só Streamable HTTP. Ainda não há pacote stdio (npx) local — conecte-se à URL hospedada.
Sem SLA no nível Studio. Os contratos Enterprise incluem 99,9% de disponibilidade e suporte com contato dedicado. Fale com a gente.

Precisa de algo que esta lista não cobre?

Os planos Enterprise liberam:

Resoluções sob medida e ajuste fino de estilo com os materiais da sua marca.
Capacidade dedicada (sem fila compartilhada).
Instalação em VPC ou nos seus servidores.
Suporte com contato dedicado e SLA de 99,9%.
Preço por volume acima de 10 mil requisições por mês.

Falar com vendas →

Versionamento

v1 é a versão atual. Mudanças que quebram compatibilidade saem como v2.

A versão fica no caminho da URL: /v1/.... Dentro de uma versão a gente só faz mudanças aditivas — campos novos, endpoints novos, tipos de evento novos. Nunca vamos remover um campo nem mudar o tipo dele dentro da mesma versão.

Quando lançarmos v2, v1 a versão anterior continua no ar por pelo menos 12 meses com a data de encerramento anunciada pelo endpoint changelog e por e-mail para todos os usuários da API.

Registro de mudanças: GET /v1/changelog devolve todas as mudanças desde o lançamento, das mais novas para as mais antigas.
Página de status: status.bluweo.com para ver a disponibilidade ao vivo e o histórico de incidentes.
Avisos por e-mail: dá para ativar pelo painel. A gente só escreve para avisar de mudanças que quebram compatibilidade e de incidentes 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)"
  ]
}

Pronto para construir?

Gere sua primeira chave de API pelo painel, ou fale com a gente se precisar de um contrato sob medida.

Subir para o Studio Falar com vendas