Skip to main content
Brainiall
Se connecterCommencer
Docs

Documentation API

Une référence complète pour toutes les API Brainiall.

Authentification

Tous les endpoints acceptent l'un de ces en-têtes (utilisez-en un) :

Authorization: Bearer YOUR_KEYOcp-Apim-Subscription-Key: YOUR_KEYapi-key: YOUR_KEY
URL de basehttps://api.brainiall.com

Détails d’authentification

Obtenez une clé API gratuite sur app.brainiall.com (100 crédits image / 10 minutes d'audio / 10 000 événements mémoire par mois). La clé est un unique token Bearer partagé sur les 48 endpoints — pas d'identifiants par produit.

Limites de débit

PlanAppels / minuteSimultanéQuota mensuel
Gratuit102100 images / 10 min audio / 10k événements
Paiement à l'usage12010Illimité (facturé à l'usage)
EntreprisePersonnaliséPersonnaliséPersonnalisé (engagement d'usage)

Atteindre la limite par minute renvoie un HTTP 429 avec les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, et Retry-After.

Codes d'erreur

HTTPCauseFixé
401Jeton Bearer manquant / mal forméVérifier Authorization: Bearer brnl-... l'en-tête est présent et non révoqué.
403Le jeton n'a pas la portée requise pour ce point de terminaison ou le quota est dépasséVérifier /usage pour le quota ; pour la portée, contactez support.
422Échec de la validation (par exemple tier="ultra" absent de l'enum)Inspecter error.details JSON ; cross-check avec OpenAPI.
429Limite de débit dépasséeRespecter Retry-After en-tête ; temporisez puis réessayez. Passez à un plan supérieur si fréquent.
500-599Erreur backend transitoireNouvelle tentative idempotente avec backoff exponentiel. Vérifiez /status pour les incidents.

Toutes les réponses d'erreur suivent l' Erreur Enveloppe : {"error":{"code":N,"message":"...","details":{}}}.

Rotation des jetons

Gérer les tokens à /api-tokens — créez des tokens éphémères de type OAuth (expiration 24h à 90j), nommez-les par projet et révoquez-en un sans affecter les autres. Les clés longue durée sont renouvelées automatiquement tous les 90 jours ; vous recevez un e-mail à J-14 et J-7.

Pour les flux machine-to-machine qui ne peuvent pas effectuer de rotation, utilisez un jeton de compte de service depuis /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 et outils

Utilisez n'importe quel format client — tout reste synchronisé avec la spec OpenAPI en direct.

Essayer l'explorateur interactif →OpenAPI 3.1 JSONOpenAPI 3.1 YAMLPostman v2.1 CollectionEnvironnement PostmanTypeScript SDK (.tar.gz)SDK Python (.tar.gz)Fiche technique PDF (exemple)

Générer un client typé : npx @openapitools/openapi-generator-cli generate -i https://app.brainiall.com/openapi.json -g typescript-fetch -o ./brainiall-sdk

Webhooks

Brainiall envoie deux types de webhooks : Marketplace SaaS Fulfillment v2 événements (cycle de vie de l'abonnement depuis Microsoft Azure Marketplace) et Événements d'utilisation (comptage par appel transmis à votre endpoint, optionnel, plans Pay-as-you-go et Enterprise).

Marketplace SaaS Fulfillment v2

Microsoft Azure Marketplace envoie des événements du cycle de vie de l'abonnement à notre serveur webhook à https://app.brainiall.com/api/marketplace/webhook. Vous ne l'implémentez pas — il est documenté ici pour que les équipes sécurité puissent auditer l'intégration lors de l'achat.

Types d’action : S'abonner, Se désabonner, SuspendSubscription, ReinstateSubscription, ChangePlan, ChangeQuantity, Renouveler, Transfert.

Structure du payload (champs clés) :

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

Validation de la signature

Chaque webhook fournit un jeton Bearer signé dans le Autorisation en-tête. Nous validons :

  • Algorithme = RS256
  • Émetteur = https://sts.windows.net/{tenantId}/
  • Audience = notre ID d'application AAD
  • JWKS récupéré et mis en cache depuis https://login.microsoftonline.com/common/discovery/keys
  • exp claim valide avec une dérive d'horloge de 10 minutes max

Défense contre les attaques par rejeu

Chacun activityId est traité au plus une fois. Les répétitions du même activityId avec différents action sont rejetés avec 409 Conflict. Le timeStamp le champ doit être à moins de 5 minutes de l'horloge du serveur ; les requêtes plus anciennes sont rejetées avec 401.

Événements d’utilisation (opt-in)

Sur les plans Pay-as-you-go et Enterprise, vous pouvez activer la réception d'un événement d'usage pour chaque appel API réussi, envoyé à votre URL. Configuration sur /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..."
}

Signé en HMAC-SHA256 sur le corps brut avec un secret par tenant que vous configurez lors de l'activation. Envoyez la signature dans X-Brainiall-Signature ; vérifier avant traitement.

Portail développeur Brainiall