Docs

Documentación de API

Referencia completa para todas las APIs de Brainiall.

Autenticación

Todos los endpoints aceptan cualquiera de estos encabezados (usa uno):

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

URL basehttps://api.brainiall.com

Detalles de autenticación

Obtenga una clave de API gratuita en app.brainiall.com (100 créditos de imagen / 10 minutos de audio / 10k eventos de memoria por mes). La clave es un único token Bearer compartido entre los 48 endpoints — sin credenciales por producto.

Límites de tasa

Plan	Llamadas / minuto	Concurrente	Cuota mensual
Gratis	10	2	100 imágenes / 10 min audio / 10k eventos
Pago por uso	120	10	Ilimitado (facturado por uso)
Empresa	Personalizado	Personalizado	Personalizado (uso comprometido)

Alcanzar el límite por minuto devuelve HTTP 429 con los encabezados X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, y Retry-After.

Códigos de error

HTTP	Causa	Corregir
`401`	Token Bearer ausente o mal formado	Verificar `Authorization: Bearer brnl-...` el header está presente y no ha sido revocado.
`403`	El token no tiene alcance para este endpoint o se excedió la cuota	Verificar /usage para cuota; para alcance, contacte a support.
`422`	Validación fallida (p. ej., tier="ultra" no está en el enum)	Inspección `error.details` JSON; verificar con OpenAPI.
`429`	Límite de tasa excedido	Respetar `Retry-After` encabezado; espere y reintente. Actualice el plan si es frecuente.
`500-599`	Error transitorio del backend	Reintento idempotente con backoff exponencial. Verifique /status para incidentes.

Todas las respuestas a errores siguen el OpenAPI Error envelope: {"error":{"code":N,"message":"...","details":{}}}.

Rotación de Token

Gestión de Tokens en /api-tokens — crea tokens estilo OAuth de corta duración (expiración de 24 h a 90 d), nómbralos por proyecto y revoca cualquiera sin afectar a los demás. Las llaves de larga duración se rotan automáticamente cada 90 días; recibes un correo a los 14 y 7 días previos.

Para flujos de trabajo de máquina a máquina que no pueden rotar, use un token de cuenta de servicio desde /team (Plan 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 y herramientas

Use cualquier formato de cliente — todos se mantienen sincronizados con la especificación OpenAPI activa.

Probar el explorador interactivo →OpenAPI 3.1 JSON OpenAPI 3.1 YAML Colección Postman v2.1 Entorno de Postman SDK de TypeScript (.tar.gz)Python SDK (.tar.gz)Ficha técnica PDF (muestra)

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

Webhooks

Brainiall envía dos tipos de webhooks: Marketplace SaaS Fulfillment v2 eventos (ciclo de vida de la suscripción desde Microsoft Azure Marketplace) y Eventos de uso (medición por llamada enviada a tu endpoint, opcional, planes Pay-as-you-go y Enterprise).

Marketplace SaaS Fulfillment v2

Microsoft Azure Marketplace envía eventos de ciclo de vida de suscripción a nuestro manejador de webhook en https://app.brainiall.com/api/marketplace/webhook. No implementas esto — se documenta aquí para que los equipos de seguridad empresarial puedan auditar la integración durante la evaluación de compra.

Tipos de acción: Suscribirse, Cancelar suscripción, SuspendSubscription, ReinstateSubscription, ChangePlan, ChangeQuantity, Renovar, Transferencia.

Estructura del payload (campos clave):

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

Validación de la firma

Cada webhook entrega un token Bearer firmado en el Autorización encabezado. Validamos:

Algoritmo = RS256
Emisor = https://sts.windows.net/{tenantId}/
Audience = ID de aplicación de AAD
JWKS obtenido y almacenado en caché desde https://login.microsoftonline.com/common/discovery/keys
exp claim dentro de un desfase de reloj de 10 minutos

Defensa contra ataques de repetición

Cada uno activityId se procesa como máximo una vez. Las repeticiones del mismo activityId con diferente action se rechazan con 409 Conflict. El timeStamp el campo debe estar dentro de los 5 minutos del reloj del servidor; las solicitudes anteriores se rechazan con 401.

Eventos de uso (opt-in)

En los planes Pay-as-you-go y Enterprise, puede optar por recibir un evento de uso por cada llamada exitosa a la API, enviado a su URL. Configure en /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..."
}

Firmado con HMAC-SHA256 sobre el cuerpo sin procesar usando un secreto por inquilino que configuras al activarlo. Envía la firma en X-Brainiall-Signature; verifique antes de procesar.