Utilise ta clé API
Reçois-la de l’administrateur de l’espace et envoie-la dans l’en-tête X-Bambou-Extension-Key. Pour un assistant IA, crée plutôt une clé dédiée (voir plus bas).
Connecte tes outils
à ton espace.
Génère des réponses avec tes presets, retrouve tes médias et gère tes réglages. Chaque exemple utilise l’adresse de l’espace ouvert.
URL de base
Récupère tes identifiants
Lis /api/extension/config pour choisir un preset et un Media Vault.
Appelle la génération
Transmets le preset et l’historique à /api/extension/generate.
La génération nécessite un moteur IA configuré dans le studio : fournisseur, URL, modèle et délai dans le menu Moteur IA ; clé du fournisseur dans Settings API Key (une clé par fournisseur). Ces réglages ne contiennent pas la clé BambouAI : elle ne fournit aucun crédit IA. Sans URL ou sans clé de moteur, la génération répond une erreur (500 pour les extensions, 503 pour un assistant).
Premier appel
Exemple cURL pour Bash, zsh ou WSL. Remplace la valeur de démonstration par ta clé. Pour chaque réponse, renvoie tout l’historique de la conversation : le serveur ne le garde pas. Les exemples utilisent --fail-with-body (curl 7.76 ou plus récent ; vérifie avec curl --version) ; avec un curl plus ancien, remplace-le par --fail (le corps de l’erreur n’est alors pas affiché). Dans les exemples de génération, remplace REMPLACER_PAR_ID_DU_PRESET par un id lu dans /api/extension/config.
PowerShell : utilise Invoke-RestMethod.
$env:BAMBOU_API_KEY = "VOTRE_CLE_API"
$h = @{ "X-Bambou-Extension-Key" = $env:BAMBOU_API_KEY }
Invoke-RestMethod "/api/extension/config" -Headers $h
$corps = @{ presetId = "REMPLACER_PAR_ID_DU_PRESET"; messages = @(@{ role = "user"; content = "Bonjour, comment vas-tu ?" }) } | ConvertTo-Json -Depth 5
try { Invoke-RestMethod "/api/extension/generate" -Method Post -Headers $h -ContentType "application/json; charset=utf-8" -Body ([Text.Encoding]::UTF8.GetBytes($corps)) -TimeoutSec 180 } catch { $_.ErrorDetails.Message }Trois accès, selon l’opération
Intégrations et extensions
Clé de l’espace (une seule, partagée par les extensions et les workers), envoyée dans X-Bambou-Extension-Key. Elle permet de lister les presets et de générer des réponses, mais ouvre aussi des routes internes non documentées : ne la confie pas à un assistant (voir « Accès pour un assistant IA »).
Authorization: Bearer n’est pas reconnu par ces routes.
Assistants IA
Clé bbk_… propre à chaque assistant, créée par le propriétaire dans Settings → API Keys, envoyée dans Authorization: Bearer. Elle ne sert qu’à lister les presets autorisés et à générer des réponses, avec ses propres limites ; elle se met en pause ou se révoque à tout moment.
Gestion de l’espace
Envoie ta clé de connexion à POST /api/login, puis conserve le cookie bambou_session. Il donne accès à toute l’administration du studio (presets, médias, archives, clés fournisseur, comptes, flotte, réglages) : toutes les routes /api/ qui ne sont ni publiques ni à clé API l’exigent. Ne le confie pas à un assistant.
Durée du cookie : 12 heures. Un redémarrage du serveur demande une nouvelle connexion.
Ouvrir une session avec cURL
Les exemples Python et JavaScript de gestion ouvrent leur propre session avec la variable d’environnement BAMBOU_LOGIN_KEY. Les exemples d’extension utilisent BAMBOU_API_KEY et ceux d’assistant BAMBOU_ASSISTANT_KEY. JavaScript s’exécute avec Node.js 18 ou plus récent ; Python utilise le paquet requests.
Les clés de chaque espace s’utilisent sur son propre domaine ; le fichier OpenAPI téléchargé renvoie à ce même domaine. Les extraits sont prévus pour une intégration côté serveur ; cette API ne fournit pas d’accès CORS pour un site web d’un autre domaine.
Accès pour un assistant IA
Un assistant (agent IA, script, outil tiers) utilise sa propre clé, distincte de celle des extensions : elle se coupe ou se remplace sans toucher à la flotte, et elle n’ouvre que deux routes.
Le propriétaire crée la clé
Dans le studio : Settings → API Keys → Clés pour assistants → Nouvelle clé. Il choisit un nom, les presets autorisés et les limites. La clé bbk_… n’est affichée qu’une fois ; le serveur n’en garde que l’empreinte.
L’assistant lit les presets
GET /api/assistant/presets renvoie les presets que la clé peut utiliser, avec leur identifiant.
L’assistant génère
POST /api/assistant/generate avec un presetId et l’historique ; la réponse est la prochaine réplique du personnage.
La clé s’envoie dans Authorization: Bearer bbk_… (ou dans X-Bambou-Api-Key). Elle n’est jamais acceptée sur les autres routes, et la clé des extensions n’est jamais acceptée sur celles-ci.
Ce que fait la génération
- Elle joue le personnage du preset choisi : ce n’est pas un chat généraliste. Le prompt, le ton et la langue viennent du preset ; il n’y a pas de prompt système à fournir.
- Les réponses sont courtes. Un filtre remplace par une réplique du personnage les phrases qui avouent être une IA, un bot ou un robot, ou ne pas avoir de photo ; sa liste de formulations est fixe et ne donne aucune garantie (« assistant virtuel », « modèle de langage », « chatbot »… passent). Relis la réponse si ce point compte.
- La réponse peut contenir le lien du preset et un ordre d’arrêt (
stopConversation: true: envoyer le contenu s’il y en a, puis cesser de répondre ; le contenu peut être vide).convertedvauttrueseulement quand l’interlocuteur dit avoir rejoint après avoir reçu le lien : la réponse porte alors aussistopConversation: true. - Texte seul : ni image ni pièce jointe en entrée, aucun média en sortie.
- Rien n’est mémorisé : renvoie tout l’historique (jusqu’à 40 messages) à chaque appel, en terminant par le message
userauquel répondre. Rien n’est archivé, aucun contact n’est réservé, aucun compteur de la flotte n’est touché. - Aucun nouvel essai après une erreur du moteur IA :
502ou504avec un message générique, réessaie plus tard (une réponse vide du moteur donne aussi502). Une même génération peut demander jusqu’à deux appels au moteur, sous le même délai.
Limites
| Limite | Valeur | Réglage |
|---|---|---|
| Générations par minute | 20 par défaut | 1 à 600, par clé |
| Générations simultanées | 2 par défaut | 1 à 8, par clé |
| Générations par jour (UTC) | 1 000 par défaut | 1 à 100 000, par clé ; remis à zéro à minuit UTC et au redémarrage du serveur |
| Presets utilisables | tous par défaut | liste choisie par clé |
| Lecture des presets | 120 appels par minute et par clé | fixe ; ne consomme pas le quota de génération |
| Corps de la requête | 256 Kio | fixe |
| Historique | 40 messages, 2 000 caractères par message, 30 000 au total | fixe ; caractères comptés en unités UTF-16 (un emoji en vaut 2) ; rôles user et assistant seulement, dernier message user |
| Clés invalides | 30 en 10 minutes par adresse | fixe ; au-delà, 429 pour cette adresse |
Chaque requête de génération acceptée compte dans la limite par minute. Le crédit du jour est rendu quand la requête est refusée avant toute génération (400, 403, 413), pour un preset inconnu (404) ou un moteur non configuré (503) ; il reste consommé après un échec du moteur (502, 504). Les compteurs d’usage affichés dans le studio sont remis à zéro à chaque redémarrage du serveur.
Réponses d’erreur
| Code | Message | Que faire |
|---|---|---|
| 400 | Champ non pris en charge, historique ou message invalide… | Corriger la requête : seuls presetId et messages sont admis. |
| 401 | Cle API invalide, revoquee ou absente. | Clé absente, fausse, mal copiée ou révoquée : en demander une nouvelle au propriétaire. |
| 403 | Cette cle est en pause. ou preset non autorisé | Le propriétaire a coupé la clé ou limité ses presets (une clé limitée reçoit 403, jamais 404, pour un identifiant qu’elle n’a pas le droit d’utiliser) ; réessayer quand il l’a reprise. |
| 404 | Preset inconnu. | Clé ayant accès à tous les presets, ou preset supprimé : relire /api/assistant/presets. |
| 413 | Corps trop grand | Réduire l’historique. |
| 429 | Limite atteinte | Attendre Retry-After secondes. |
| 502 / 503 / 504 | Moteur IA indisponible, non configuré ou trop lent ; 503 avec Retry-After: 5 : service momentanément indisponible | Réessayer plus tard avec un délai croissant ; prévoir un délai client supérieur à celui du moteur (120 s par défaut). Aucune erreur du moteur n’est rejouée côté serveur. |
Contrôle par le propriétaire
Dans Settings → API Keys : créer une clé par assistant, modifier son nom, ses limites et ses presets (effet immédiat), la mettre en pause puis la reprendre, ou la révoquer (définitif). Les mêmes opérations existent en API avec la session studio : GET/POST /api/studio/api-keys et PATCH/DELETE /api/studio/api-keys/{keyId} (catégorie « Clés API » de la référence).
Usage côté serveur uniquement : cette API n’autorise pas les appels depuis un navigateur d’un autre domaine (pas de CORS). Ne place jamais une clé dans une page publique.
Référence des routes
Chargement de la référence…
Archiver et restaurer un preset
Lis la configuration complète, modifie archivedAt sur le preset voulu, puis renvoie la configuration. Une date ISO archive le preset ; null le restaure.
Le preset garde son contenu et son identifiant. Il disparaît de la liste du studio, mais reste disponible aux intégrations et aux comptes déjà associés. La route PUT enregistre tout le document : conserve les autres champs du GET le plus récent.
Comprendre les réponses
| Code | Signification | À vérifier |
|---|---|---|
| 200 | Requête traitée | Pour une génération, lire aussi stopConversation et contentText. |
| 201 | Clé créée | La clé en clair n’est renvoyée que par cette réponse. |
| 400 | Paramètre refusé par certaines routes | Le message JSON error précise le problème. |
| 401 | Authentification refusée | Routes à clé API : « Cle extension invalide. » ou « Cle API invalide, revoquee ou absente. » (clé absente, fausse, révoquée ou en-tête mal nommé). Routes studio : « Authentification requise. » (cookie absent ou expiré). Sans session, un chemin /api/ inexistant, une mauvaise méthode HTTP (par exemple GET sur une route POST) ou une requête OPTIONS répondent aussi 401 « Authentification requise. » : ni 404 ni 405 ; vérifie chemin et méthode avant la clé. Un 401 d’un autre texte sur /api/extension/generate vient du fournisseur IA (clé du moteur invalide). |
| 402 | Crédit du fournisseur IA épuisé | Statut du fournisseur renvoyé tel quel par la génération des extensions ; recharger le compte fournisseur. |
| 403 | Clé en pause ou preset non autorisé | Routes d’assistant : le propriétaire a coupé la clé ou limité ses presets. |
| 404 | Ressource introuvable | Preset, conversation ou média inexistant, ou route inconnue avec une session ouverte. URL et identifiants exacts, encodés dans les segments de chemin. |
| 413 | Corps trop grand | Routes d’assistant : plus de 256 Kio. Routes de gestion des clés (session studio) : plus de 8 Kio. |
| 429 | Limite atteinte | Sur /api/login : 5 échecs en 10 minutes pour une même adresse, respecter Retry-After (600 s). Sur /api/assistant/* : quota de la clé, respecter Retry-After. Sur /api/extension/generate : limite du fournisseur IA, sans Retry-After ; réessayer avec un délai croissant. |
| 500 | Erreur de traitement, de configuration ou de validation | Lire error. Génération des extensions : « Preset inconnu. », « Historique Playground invalide. », « Message Playground invalide. », « Media Vault invalide. », « Aucun opener actif dans ce preset. », « Configure d’abord l’URL du PC IA dans Comptes. » ou « Configure d’abord la cle privee du PC IA. » (moteur non configuré), « Corps de requete trop grand. » (plus de 8 Mio), message d’analyse JSON (corps invalide). Ces erreurs de validation ne sont pas des 400. |
| 502 / 503 / 504 | Fournisseur en erreur, non configuré ou délai dépassé | 504 « Le service a mis trop de temps. » : délai du moteur dépassé. Avec un fournisseur compatible OpenAI (DeepSeek, OpenAI), son statut (401, 402, 403, 404, 429, 5xx) est renvoyé tel quel avec son message par les extensions ; si un moteur de secours est configuré, il prend d’abord le relais pour 402, 408, 409, 425, 429, 5xx et les délais dépassés. Les routes d’assistant ne renvoient que 502, 503 ou 504 avec un message générique. Éviter de répéter aveuglément une génération. |
Les erreurs du dashboard utilisent {"error":"Explication"}. Le proxy peut retourner du HTML en cas de panne : vérifie le statut et le type de contenu avant de décoder du JSON.
Génération : 8 Mio de JSON, historique limité aux 250 derniers messages. Configuration : 1 Mio. Import de preset : 4 Mio. Le délai du moteur (« Délai maximum », menu Moteur IA : 120 secondes par défaut, de 5 à 600) couvre l’ensemble des tentatives du moteur principal ; si un moteur de secours est configuré, il dispose ensuite de son propre délai, de sorte que la durée totale peut approcher le double du réglage. Prévois un délai client d’au moins le double du réglage plus 10 secondes, ou accepte de couper à 180 secondes et de ne pas rejouer automatiquement. Un proxy intermédiaire peut couper plus tôt et répondre en HTML (statut 5xx).
Le champ content d’une génération est une liste d’éléments, avec notamment type, content et delayMs. Pour du texte simple, utilise contentText. Une réponse vide accompagnée de stopConversation: true est un résultat à respecter.