Guide d’intégration
Construire
Une conversation locale pour la boutique fictive Atelier Lagune. L’API classe la question dans une rubrique ; le serveur restitue uniquement un texte de `faq.json`. Une rubrique inconnue produit un refus explicite. La FAQ reste l’unique source.
Prérequis et installation
Node.js 22 ou supérieur ; aucune dépendance npm.
cp .env.example .env
# Renseigner les variables, puis :
npm startOuvrez http://127.0.0.1:3001. `npm test` lance les tests mock sans clé.
Personnalisation
Modifiez `faq.json` et la liste des rubriques du message système ensemble. Le serveur refuse les rôles système fournis par le client. Les sorties sont une sélection de textes autorisés, affichés avec `textContent`. Une injection peut encore provoquer une mauvaise sélection de rubrique : aucun outil ni action métier n’est disponible. Les questions multiples ou ambiguës peuvent être refusées.
Protections locales
8 messages de 1 000 caractères, corps de 16 Ko, 128 tokens de sortie, timeout API de 15 s, 5 appels/minute, un appel simultané, 20 appels par démarrage. Les compteurs sont globaux au processus et remis à zéro au redémarrage ; ce n’est pas un plafond de dépense public. Le serveur écoute exclusivement sur 127.0.0.1. Nouvelle conversation efface l’historique de l’interface, sans remettre les quotas à zéro.
Compte et clé
Ouvrez `/signup` dans la console déployée, créez votre projet, puis une clé dans `/app/api-keys`. Ajoutez des crédits si nécessaire. Conservez la clé côté serveur. Les domaines sont centralisés dans `apps/web/lib/domains.ts` : site https://todou.dev, console https://console.todou.dev, documentation https://docs.todou.dev, API https://api.todou.dev. Site, console et documentation partagent le même frontend Next.js. En local, utilisez l’URL de votre backend, par défaut http://127.0.0.1:8000. Le champ TODOU_API_BASE_URL inclut toujours `/v1`.
Variables d’environnement
Copiez `.env.example` vers `.env`. Renseignez `TODOU_API_KEY`, `TODOU_API_BASE_URL` (URL terminée par `/v1`) et `TODOU_MODEL`. `todou-fast` est un identifiant initialisé par la migration du 23 août 2026 ; vérifiez sa disponibilité avec `GET /v1/models` et le même Bearer. Ne commitez jamais `.env`. Aucun SDK Todou n’est nécessaire.
Appel API
`POST /v1/chat/completions`, `Authorization: Bearer <clé>`, JSON avec `model`, `messages`, `max_tokens`, `temperature` et `stream: false`. Le contenu se trouve dans `choices[0].message.content` et la consommation dans `usage.prompt_tokens`, `usage.completion_tokens`, `usage.total_tokens`. Le backend relaie le streaming SSE du fournisseur lorsqu’il est activé pour le modèle. Ces exemples utilisent `stream: false` pour valider une réponse complète. `response_format` est relayé au fournisseur ; l’exemple Python transmet un schéma JSON strict. Vérifiez la capacité `structured_outputs` dans GET /v1/models. Une capacité refusée ou un fournisseur incompatible produit une erreur : le validateur Python reste obligatoire même avec une sortie structurée.
Consommation
Consultez `/app/usage` et `/app/billing`. Calcul en USD : `tokens_entrée / 1 000 000 × prix_entrée + tokens_sortie / 1 000 000 × prix_sortie`. Contrat examiné le 9 septembre 2026, modèle proposé `todou-fast`, un appel sans relance automatique. Les prix de migration sont modifiables ; les tarifs effectifs doivent être vérifiés dans la console au moment du test. Aucun montant de production n’est garanti ici. Le backend réserve le coût maximal avant génération puis libère la part inutilisée. Un timeout client ne garantit pas l’annulation de la facturation.
Erreurs et limites communes
401 : clé absente/invalide ; 402 : crédit insuffisant ; 404 : modèle indisponible ; 422 : requête invalide ; 429 : fréquence dépassée ; 502/503 : fournisseur indisponible. Les limites API sont configurables et utilisent le mécanisme Redis existant. Un refus HTTP 429 indique une limite atteinte ; suivez les informations renvoyées par le backend et consultez la configuration de votre déploiement. Ne relancez pas automatiquement un appel facturable. Ne transmettez pas de données personnelles réelles dans ces démonstrations. Les tests locaux utilisent des mocks, ne prouvent pas la qualité d’un modèle réel et ne consomment aucun crédit.
Publication et licence
Dossier autonome, prêt à être copié dans un dépôt après revue. Aucun dépôt public n’a été créé. Aucune licence applicable explicitement aux exemples n’a été trouvée : choisir une licence avant publication. Ne déployez pas ces scripts comme service public sans authentification, quotas persistants et plafond monétaire.