Docs

Documentação de API

Referência completa para todas as APIs Brainiall.

Autenticação

Todos os endpoints aceitam qualquer um destes cabeçalhos (use um):

Authorization: Bearer YOUR_KEYOcp-Apim-Subscription-Key: YOUR_KEYapi-key: YOUR_KEY

URL basehttps://api.brainiall.com

Detalhes de autenticação

Obtenha uma chave de API gratuita em app.brainiall.com (100 créditos de imagem / 10 minutos de áudio / 10k eventos de memória por mês). A chave é um único token Bearer compartilhado entre os 48 endpoints — sem credenciais por produto.

Limites de taxa

Plano	Chamadas / minuto	Competição	Quota mensal
Grátis	10	2	100 imagens / 10 min de áudio / 10k eventos
Pague conforme o uso	120	10	Ilimitado (cobrado por uso)
Enterprise	Personalizado	Personalizado	Personalizado (uso comprometido)

Atingir o limite por minuto retorna HTTP 429 com os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, e Retry-After.

Códigos de erro

HTTP	Causa	Correção
`401`	Token Bearer ausente / malformado	Verificar `Authorization: Bearer brnl-...` O cabeçalho está presente e não revogado.
`403`	Token sem escopo para este endpoint ou cota excedida	Verificação /usage para cota; para escopo, contate support.
`422`	Falha de validação (ex.: tier="ultra" não está no enum)	Inspecionar `error.details` JSON; verificação cruzada com OpenAPI.
`429`	Limite de taxa excedido	Respeitar `Retry-After` cabeçalho; faça back-off e tente novamente. Atualize o plano se for frequente.
`500-599`	Erro de backend transitório	Retry idempotente com backoff exponencial. Verifique /status para os incidentes.

Todas as respostas de erro seguem o OpenAPI Erro envelope: {"error":{"code":N,"message":"...","details":{}}}.

Rotação de Token

Gerencie tokens em /api-tokens — crie tokens estilo OAuth de curta duração (expiração de 24h a 90d), nomeie-os por projeto e revogue qualquer um sem afetar os demais. Chaves de longa duração são rotacionadas automaticamente a cada 90 dias; você recebe um e-mail aos 14 e aos 7 dias do vencimento.

Para fluxos máquina-a-máquina que não podem rotacionar, use um token de conta de serviço de /team (Plano Enterprise).

NLP Suite Endpoints

Detect toxic, offensive, or harmful content in text.

curl -X POST https://api.brainiall.com/v1/nlp/toxicity \
 -H "Authorization: Bearer YOUR_KEY" \
 -H "Content-Type: application/json" \
 -d '{"text":"This product is absolutely amazing"}'

SDK e Ferramentas

Use qualquer formato de cliente — todos permanecem sincronizados com a especificação OpenAPI ao vivo.

Abrir o explorador interativo →OpenAPI 3.1 JSON OpenAPI 3.1 YAML Postman Collection v2.1 Ambiente do Postman SDK TypeScript (.tar.gz)Python SDK (.tar.gz)Ficha de dados PDF (sample)

Gere um cliente tipado: npx @openapitools/openapi-generator-cli generate -i https://app.brainiall.com/openapi.json -g typescript-fetch -o ./brainiall-sdk

Webhooks

Brainiall envia dois tipos de webhooks: Marketplace SaaS Fulfillment v2 eventos (ciclo de vida da assinatura do Microsoft Azure Marketplace) e Eventos de Uso (medição por chamada enviada ao seu endpoint, opcional, planos Pay-as-you-go e Enterprise).

Marketplace SaaS Fulfillment v2

Microsoft Azure Marketplace envia eventos de ciclo de vida de assinatura para o nosso operador de webhook https://app.brainiall.com/api/marketplace/webhook. Você não implementa isso — está documentado aqui para que equipes de segurança corporativa possam auditar a integração durante a contratação.

Tipos de ação: Assinar, Cancelar assinatura, SuspendSubscription, ReinstateSubscription, ChangePlan, ChangeQuantity, Renovar, Transfer.

Formato do payload (campos-chave):

{
  "id":              "uuid",
  "activityId":      "uuid",
  "subscriptionId":  "uuid",
  "publisherId":     "brainiall-publisher-id",
  "offerId":         "specialist-ai-apis",
  "planId":          "s1-background-removal-fast",
  "quantity":        1,
  "action":          "Subscribe",
  "timeStamp":       "2026-04-29T08:30:00.0000000Z",
  "status":          "InProgress",
  "operationRequestSource": "Azure",
  "subscription": { ...full subscription object ... }
}

Validação de assinatura

Todo webhook entrega um Bearer token assinado no Autorização cabeçalho. Validamos:

Algoritmo = RS256
Emissor = https://sts.windows.net/{tenantId}/
Audience = ID da nossa aplicação AAD
JWKS obtido e armazenado em cache de https://login.microsoftonline.com/common/discovery/keys
exp claim com tolerância de 10 minutos no relógio

Defesa contra ataques de replay

Cada um activityId é processado no máximo uma vez. Repetições do mesmo activityId com diferentes action são rejeitados com 409 Conflito. O timeStamp campo deve estar dentro de 5 minutos do relógio do servidor; requisições mais antigas são rejeitadas com 401.

Eventos de utilização (opt-in)

Nos planos Pay-as-you-go e Enterprise, você pode optar por receber um evento de uso para cada chamada de API bem-sucedida, enviado para sua URL. Configure em /webhooks.

{
  "event":      "api.call",
  "id":         "evt_2K9...",
  "created":    "2026-04-29T08:30:00.123Z",
  "endpoint":   "/v1/image/remove-background/base64",
  "sku":        "s1-background-removal",
  "tier":       "hd",
  "tokens_in":  null,
  "tokens_out": null,
  "units":      1,
  "unit_kind":  "image",
  "duration_ms": 3142,
  "status":     200,
  "request_id": "req_8c3..."
}

Assinado com HMAC-SHA256 sobre o corpo bruto usando um segredo por tenant que você configura ao habilitar. Envie a assinatura em X-Brainiall-Signature; verifique antes de processar.