Automatisation HTTP : guide d’intégration

Construire

Classer un message fictif avec `category` (delivery, returns, billing, other), `priority` (low, normal, high) et `summary` (1 à 200 caractères). Aucune action métier n’est exécutée et aucune intégration native n8n ou Make n’est annoncée. La réponse de modèle est validée avant affichage.

Prérequis et installation

Shell POSIX, Python 3.10+ et cURL 7.76+ (`--fail-with-body`), aucune dépendance pip.

cp .env.example .env
# Renseigner les variables, puis :
sh classify.sh
python3 -m unittest -v

Commande cURL équivalente

Variables à exporter dans votre terminal ; ne collez pas la clé dans un historique partagé. Cette commande brute retourne l’enveloppe API ; le script fourni ajoute la validation JSON et évite de placer le secret dans les arguments du processus.

curl --fail-with-body --silent --show-error \
  --connect-timeout 5 --max-time 20 \
  "$TODOU_API_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $TODOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

Entrée et résultat illustratifs

Entrée : « Mon colis est arrivé endommagé. Pouvez-vous m’aider ? » Sortie préétablie, pas une génération mesurée : `{"category":"delivery","priority":"normal","summary":"Le client signale un colis endommagé."}`.

Personnalisation et outil d’automatisation

Modifiez le message utilisateur de `request.json` ; le script remplace son modèle par `TODOU_MODEL`. Dans un outil HTTP générique, configurez POST, l’URL complète, un secret Bearer dans le gestionnaire de credentials, Content-Type application/json et le corps de `request.json`. Parsez `choices[0].message.content`, puis validez les champs/énumérations avec les mêmes règles que `validate` dans `run.py`. Routez les erreurs HTTP et de validation vers une étape de revue, sans action automatique ni relance aveugle. Le prompt ne garantit ni JSON valide ni classement correct. Maximum 256 tokens et 20 secondes pour l’appel cURL.

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.