Construisez avec Todou AI Cloud.

Démarrage rapide

Créez un compte, ajoutez des crédits à votre organisation, générez une clé API puis envoyez votre première requête.

1. 1Créez votre compte
2. 2Ajoutez des crédits
3. 3Générez une clé API
4. 4Appelez un modèle Todou

curl https://api.todou.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-todou-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "todou-fast",
    "messages": [
      { "role": "user", "content": "Bonjour Todou" }
    ]
  }'

Exemple JavaScript / Node.js

const response = await fetch("https://api.todou.dev/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TODOU_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "todou-pro",
    messages: [
      { role: "system", content: "Tu es un assistant concis." },
      { role: "user", content: "Résume cette réunion." },
    ],
  }),
});

if (!response.ok) throw new Error(await response.text());
const completion = await response.json();
console.log(completion.choices[0].message.content);

Authentification

Ajoutez votre clé à chaque requête avec l’en-tête HTTP suivant :

Authorization: Bearer sk-todou-...

Utilisez une clé active du projet concerné, avec les droits nécessaires sur le modèle et des crédits disponibles. La même authentification s’applique aux quatre nouveaux modèles. Les restrictions de compte, de projet, de modèles et les quotas restent applicables.

export TODOU_API_KEY="votre-cle-api"

Modèles Todou

Les slugs publics restent stables même si le moteur d’inférence évolue. Consultez toujours GET /v1/models pour connaître les modèles actifs et leurs capacités certifiées.

curl https://api.todou.dev/v1/models \
  -H "Authorization: Bearer sk-todou-..."

Le catalogue expose les modèles actifs accessibles à votre clé et leurs capabilities. Decision expose modality: "text", limits et price_per_request, sans champ context_length. Embedding, Reranker et Decision ne sont pas des modèles de chat : utilisez leur endpoint dédié. La présence au catalogue ne garantit pas une capacité d’inférence disponible à cet instant.

Tarification

Les tokens d’entrée et de sortie sont comptabilisés séparément. Les prix d’entrée et de sortie du tableau sont exprimés en dollars américains par million de tokens.

Embedding est facturé sur les tokens d’entrée réels ; Reranker sur usage.total_tokens. Leurs tarifs validés sont à consulter dans la console : aucun montant indicatif n’est substitué à un tarif non publié.

Decision : 0,50 $ pour 1 000 décisions réussies, soit 0,0005 $ par requête réussie. Les tokens sont suivis pour l’usage et les quotas, mais ne déterminent pas son prix. Le champ price_per_request du catalogue donne le prix configuré.

Une réservation de crédits précède l’inférence. Après succès, la facturation utilise l’usage réel ou le prix fixe de Decision. En cas d’échec d’inférence, la réservation est libérée ; une tentative admise peut néanmoins compter dans les quotas de requêtes. Prévoyez le solde nécessaire à la réservation, qui peut dépasser le coût final.

Le coût exact de chaque requête apparaît dans votre espace développeur. Les crédits sont détenus par l’organisation et consommés par les projets associés.

Chat Completions

Endpoint principal : POST /v1/chat/completions. Les rôles acceptés sont system, user, assistant et tool.

Structure de la réponse

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "todou-fast",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Bonjour !" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 8, "completion_tokens": 3, "total_tokens": 11 }
}

Embeddings — todou-embedding

POST /v1/embeddings transforme du texte en vecteurs pour la recherche sémantique. Le modèle doit être exactement todou-embedding.

input accepte une chaîne non vide ou une liste de 1 à 32 chaînes, chacune de 32 768 caractères maximum. Le corps JSON complet est limité à 256 Kio (262 144 octets). Les champs supplémentaires, dont dimensions et encoding_format, ne sont pas acceptés.

curl https://api.todou.dev/v1/embeddings \
  -H "Authorization: Bearer $TODOU_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "todou-embedding",
  "input": [
    "Paris est la capitale française.",
    "Berlin est la capitale allemande."
  ]
}'

Pour un seul texte, utilisez "input": "Votre texte". La réponse compatible OpenAI contient object: "list", model et data. Chaque élément contient object: "embedding", son index à partir de zéro et un tableau embedding de exactement 2 560 nombres. L’ordre des inputs est conservé.

const vectors = result.data.map(item => item.embedding);
console.log(vectors[0].length); // 2560
console.log(result.usage.prompt_tokens, result.usage.total_tokens);

Les deux compteurs de tokens retournent l’usage réel et sont égaux. Le contexte en tokens du modèle est consultable via GET /v1/models ; la limite de caractères n’est pas un budget de tokens. Découpez les lots de plus de 32 textes dans votre application.

Reranking — todou-reranker

POST /v1/rerank classe des documents par pertinence pour une question. Envoyez exactement model: "todou-reranker", une query non vide et de 1 à 64 documents textuels non vides.

top_n est un entier de 1 au nombre de documents. S’il est omis, tous les documents sont demandés ; null est refusé. Corps complet : 5 000 000 octets maximum. Contexte opérationnel : 8 192 tokens par paire question/document. Délai d’inférence maximal : 60 secondes, éventuellement réduit par la configuration du service.

curl https://api.todou.dev/v1/rerank \
  -H "Authorization: Bearer $TODOU_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "todou-reranker",
  "query": "Quelle est la capitale de la France ?",
  "documents": [
    "Berlin est la capitale allemande.",
    "Paris est la capitale française."
  ],
  "top_n": 1
}'

{
  "object": "list",
  "model": "todou-reranker",
  "results": [
    {
      "index": 1,
      "relevance_score": 0.96
    }
  ],
  "usage": {
    "documents": 2,
    "total_tokens": 180
  }
}

index désigne la position originale du document, à partir de zéro. L’ordre et les scores du classement sont conservés ; ne renumérotez pas les résultats. Le service peut retourner moins de résultats que top_n. Les scores ne sont pas des probabilités garanties entre 0 et 1.

usage.documents compte tous les documents soumis, même si top_n est inférieur. usage.total_tokens est l’usage réel facturé.

Vision V1.1 — images et OCR

Utilisez POST /v1/chat/completions avec todou-vision pour lire une image, transcrire un document ou extraire son contenu visible. Les messages acceptent les rôles system, user et assistant ; le texte seul est aussi accepté. Pour les images, le message user contient un tableau de blocs text et image_url.

Les images doivent être intégrées sous forme de data URL base64 : data:image/png;base64,…, data:image/jpeg;base64,… ou data:image/webp;base64,…. Les URL HTTP(S), les chemins de fichiers et file:// ne sont pas acceptés dans le payload. L’exemple ci-dessous lit le fichier dans votre application avant de l’encoder.

import base64
import json
import os
import urllib.request
from pathlib import Path

# Utiliser un fichier PNG ; adapter le MIME pour JPEG ou WebP.
image = base64.b64encode(Path("document.png").read_bytes()).decode("ascii")
payload = {
    "model": "todou-vision",
    "messages": [{"role": "user", "content": [
        {"type": "text", "text": "Transcris le texte de ce document."},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64," + image}}
    ]}],
    "max_tokens": 4096,
    "stream": False
}
request = urllib.request.Request(
    "https://api.todou.dev/v1/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Authorization": "Bearer " + os.environ["TODOU_API_KEY"],
             "Content-Type": "application/json"},
)
with urllib.request.urlopen(request, timeout=150) as response:
    result = json.load(response)
print(result["choices"][0]["message"]["content"])

Maximum 4 images par requête, 10 000 000 octets décodés par image et 25 000 000 octets pour le corps HTTP complet. Le base64 augmente la taille : quatre images de taille maximale ne tiennent pas dans ce budget. Le type MIME doit correspondre au contenu réel.

max_tokens : de 1 à 4 096, valeur par défaut 512. stream doit être absent ou false ; le streaming n’est pas disponible. temperature : de 0 à 2. Délai d’inférence maximal : 120 secondes, éventuellement réduit. Le plafond de sortie est distinct du contexte du modèle publié au catalogue.

La réponse suit Chat Completions : choices, finish_reason et usage.prompt_tokens, completion_tokens, total_tokens. Le texte OCR est transmis sans réécriture. Vérifiez finish_reason pour détecter une sortie tronquée. Les outils et les sorties structurées ne sont pas déclarés pour ce modèle.

Décisions — todou-decision

POST /v1/decisions choisit parmi les options textuelles fournies. Le modèle doit être exactement todou-decision. Ce service ne génère pas de réponse libre.

state (32 000 caractères maximum) décrit la situation ; question (4 000 caractères) formule le choix. options contient de 2 à 256 chaînes distinctes, chacune de 512 caractères maximum. Tous ces textes sont obligatoires et non vides. Leur total est limité à 64 000 caractères et le corps à 512 000 octets.

Texte inline uniquement : pas d’images, d’URL, de chemins de fichiers, de messages, de max_tokens ni de champs supplémentaires. Les options sont conservées exactement, avec distinction de la casse. Délai d’inférence maximal : 15 secondes, éventuellement réduit.

curl https://api.todou.dev/v1/decisions \
  -H "Authorization: Bearer $TODOU_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "todou-decision",
  "state": "Le client signale un colis endommagé.",
  "question": "Quel service doit traiter cette demande ?",
  "options": [
    "livraison",
    "facturation",
    "commercial"
  ]
}'

{
  "id": "decision_example",
  "object": "decision",
  "created": 1791122570,
  "model": "todou-decision",
  "decision": "livraison",
  "decision_index": 0,
  "confidence": 0.94,
  "probabilities": {
    "livraison": 0.94,
    "facturation": 0.03,
    "commercial": 0.03
  },
  "usage": {
    "input_tokens": 90,
    "generated_tokens": 0
  },
  "metrics": {
    "latency_ms": 200
  }
}

decision_index est l’index original de l’option, à partir de zéro. confidence et probabilities sont les valeurs du modèle, transmises sans recalcul ni calibration supplémentaire. Votre application décide comment les utiliser ; elles ne garantissent pas la justesse d’une décision.

usage.generated_tokens vaut toujours 0. usage.input_tokens sert au suivi et aux quotas ; le prix reste fixe par décision réussie. metrics.latency_ms est la latence déclarée par le service, distincte du temps réseau total.

Todou Auto — V1 et V2

todou-auto est un orchestrateur logiciel, accessible par POST /v1/chat/completions. Decision choisit un outil parmi Fast, Pro et Vision, puis valide son résultat. Auto peut corriger la consigne ou changer d’outil avant de répondre.

curl https://api.todou.dev/v1/chat/completions \
  -H "Authorization: Bearer $TODOU_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "todou-auto",
  "messages": [
    {
      "role": "user",
      "content": "Explique les avantages et limites de cette proposition."
    }
  ],
  "stream": false
}'

Pour une image, reprenez l’exemple Python Vision ci-dessus en remplaçant uniquement "todou-vision" par "todou-auto". Les protections sont identiques : data URLs PNG/JPEG/WebP, 4 images maximum, 10 000 000 octets décodés par image et 25 000 000 octets pour le corps complet. Vision ne peut pas être appelé sans image.

Une étape correspond à une exécution Fast, Pro ou Vision. Auto s’arrête après 5 étapes au maximum, avec au plus 2 retries consécutifs du même outil. Chaque résultat, y compris le cinquième, est validé. Les appels Decision ne comptent pas comme étapes ; tout le workflow dispose d’un budget de 180 secondes.

La V1 accepte les messages textuels et multimodaux du contrat Vision, une consigne textuelle obligatoire de 16 000 caractères maximum au total (rôles inclus), max_tokens de 1 à 4 096 (512 par défaut), et temperature de 0 à 2. Aucun streaming, outil utilisateur, sortie structurée, Embedding, Reranker ni RAG n’est intégré. Un résultat incomplet ou supérieur à 12 000 caractères provoque un échec contrôlé.

Après ACCEPT, la réponse Chat Completions contient le résultat accepté et model: "todou-auto". Après FAIL, délai dépassé ou cinq étapes sans acceptation, la réponse chat contient : « Nous n'avons pas pu produire une réponse suffisamment fiable après plusieurs tentatives. Veuillez reformuler votre demande ou fournir davantage de contexte. » Elle ne contient jamais le dernier résultat non validé ni les décisions internes.

usage additionne les tokens vérifiés des appels internes, y compris Decision. Après ACCEPT, le prix public est la somme exacte des coûts catalogue des sous-appels réussis multipliée par 1 + orchestration_markup, arrondie à huit décimales. Par exemple, 0,008 $ de coût et un markup de 0,25 donnent 0,01000000 $. Le backend effectue un seul règlement Auto. En cas d’échec ou d’usage inconnu, la réservation est restituée ; un usage inconnu nécessite une réconciliation. Les droits du compte sur Auto et sur les modèles internes utilisés sont vérifiés. Les quotas de la requête Auto portent sur l’usage agrégé.

V2 : tools dynamiques et reprise

Ajoutez tools pour activer V2 ; une liste vide active les capacités internes V2. Chaque définition contient name, description et input_schema. Maximum : 16 tools, noms uniques de 64 caractères, descriptions de 512 caractères et définitions de 32 Kio. Les schémas sont fermés et bornés, sans références externes ni code. Votre application autorise et exécute ses tools ; Todou ne contacte aucune URL cliente.

{
  "model": "todou-auto",
  "messages": [
    {
      "role": "user",
      "content": "Retrouve le passage pertinent dans mes sources."
    }
  ],
  "tools": [
    {
      "name": "lookup_text",
      "description": "Read authorized source text",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          }
        },
        "required": [
          "query"
        ],
        "additionalProperties": false
      }
    }
  ]
}

Un appel externe retourne finish_reason: "tool_calls", content: null, un workflow_id, une date expires_at et un tool call de type function. Ses arguments sont une chaîne JSON validée contre votre schéma. Après exécution côté client, reprenez sur le même endpoint, avec la même clé API :

{
  "model": "todou-auto",
  "workflow_id": "auto-0123456789abcdef0123456789abcdef",
  "messages": [
    {
      "role": "tool",
      "tool_call_id": "toolcall_0123456789abcdef0123456789abcdef",
      "name": "lookup_text",
      "content": "Passage trouvé dans la source autorisée."
    }
  ]
}

Un résultat de tool est toujours intermédiaire : à la reprise, Fast ou Pro le transforme en réponse, puis le Final Challenger Decision la valide. Seul ACCEPT permet de retourner le candidat, et l’enveloppe technique d’un tool n’est jamais retournée telle quelle. Un tool qui a réussi n’est pas rappelé ; un résultat JSON peut déclarer status, success et retryable. Embedding et Reranker préparent le contexte et ne peuvent jamais produire directement une réponse finale. Un tool externe compte comme étape à la réception atomique de son résultat, pas lors de l’émission du tool call. Les 5 étapes maximum sont conservées ; seul un échec relançable peut être retenté, 2 fois au plus, et le candidat de la cinquième étape est aussi challengé.

V2 limite le corps initial à 25 MB (25 000 000 octets), images inline et encodage base64 compris, comme Vision. Les sous-limites restent strictes : 4 images maximum, 10 MB décodés par image, PNG/JPEG/WEBP en data URL base64 uniquement ; aucune URL distante, file:// ou chemin de fichier. Les définitions de tools restent limitées à 32 Kio, les arguments à 16 Kio, un résultat externe à 12 000 caractères et 32 Kio, et le corps de reprise à 64 Kio. Les références de schéma, regexes et mots-clés JSON Schema non pris en charge sont refusés. L’objectif reste limité à 16 000 caractères ; le contexte combiné objectif, candidat et descriptions doit tenir dans les 32 000 caractères de Decision, sans troncature pour obtenir ACCEPT.

todou-vision assure l’OCR / perception des images inline autorisées et la restitution documentaire. L’analyse et l’interprétation métier sont effectuées par todou-fast ou todou-pro. Les contrats Vision direct et Auto V1 sans tools restent inchangés.

Le workflow expire après 600 secondes par défaut, sans renouvellement à chaque reprise. Le traitement Todou dispose de 180 secondes cumulées, hors attente client. L’état est chiffré et lié à la clé, au projet et au tenant. Un replay reçoit 409 sans double traitement ; un workflow expiré reçoit 410. Les droits sont revérifiés à la reprise.

La réservation augmente uniquement pour le prochain segment nécessaire. L’attente d’un tool ne déclenche aucun règlement final ; les réservations existantes restent immobilisées jusqu’à clôture ou expiration. Les tools exécutés chez vous ont un coût Todou nul ; la préparation de leurs arguments et les appels Decision restent inclus au cost-plus. Un seul règlement après ACCEPT, remboursement en cas d’échec. L’usage retourné est cumulatif : ne pas additionner les réponses intermédiaires.

Combiner les modèles dans votre application

Pour une recherche documentaire : calculez les embeddings des documents et de la requête, recherchez les candidats dans votre propre index vectoriel, classez ces candidats avec Reranker, puis fournissez les extraits retenus à Fast ou Pro. Stockage, indexation et enchaînement des appels restent à la charge de votre application.

Pour un document image : extrayez le texte avec Vision, puis utilisez Fast/Pro pour l’analyser ou Decision pour choisir parmi une liste d’actions. Chaque appel possède son propre usage, ses limites et sa facturation. Aucun enchaînement ni fallback automatique n’est effectué par ces endpoints.

Tool-calling multi-tours

Sur un modèle qui déclare la capacité tools, déclarez jusqu’à 128 fonctions. Le modèle choisit un outil et retourne un message assistant avec content: null et tool_calls. Votre application exécute la fonction puis renvoie son résultat avec le rôle tool.

1. Déclarer l’outil

{
  "model": "todou-fast",
  "messages": [
    { "role": "user", "content": "Quel est mon solde ?" }
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_balance",
      "description": "Retourne le solde du client",
      "parameters": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    }
  }],
  "tool_choice": "auto"
}

2. Renvoyer le résultat

{
  "model": "todou-fast",
  "messages": [
    { "role": "user", "content": "Quel est mon solde ?" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_balance",
        "type": "function",
        "function": { "name": "get_balance", "arguments": "{}" }
      }]
    },
    {
      "role": "tool",
      "tool_call_id": "call_balance",
      "content": "12500 FCFA"
    }
  ],
  "tools": [/* mêmes outils qu’au premier appel */]
}

Streaming SSE

Sur un modèle de chat qui déclare la capacité streaming, ajoutez stream: true. Vision, Embedding, Reranker et Decision ne proposent pas de streaming. La réponse utilise text/event-stream et chaque événement commence par data:.

• Le premier delta annonce le rôle assistant.
• Les deltas suivants contiennent content ou tool_calls.
• Le dernier événement contient finish_reason.
• La séquence se termine par data: [DONE].

JSON structuré

Sur un modèle déclarant structured_outputs, utilisez response_format pour demander une réponse JSON exploitable par votre application.

{
  "model": "todou-pro",
  "messages": [{
    "role": "user",
    "content": "Extrait le nom et le montant : ACME, facture de 42 000 FCFA"
  }],
  "response_format": { "type": "json_object" }
}

Décrivez précisément les propriétés attendues dans le message système ou utilisateur. Validez toujours le résultat dans votre application avant une action métier.

Limites actuelles

Les tailles de corps incluent le JSON et son encodage UTF-8. Les quotas de tokens, de requêtes et les limites de débit dépendent du compte et du projet ; consultez votre console. Les plafonds de taille et de lot sont vérifiés avant l’inférence. Les contenus des nouveaux endpoints ne sont pas journalisés par le backend.

Erreurs et traçabilité

Chaque réponse fournit un en-tête X-Request-ID. Conservez-le dans vos logs pour faciliter le diagnostic. Vous pouvez aussi envoyer votre propre identifiant dans cet en-tête.

Les appels d’inférence réussis exposent aussi X-Todou-Request-ID pour le suivi de l’usage. Conservez ces identifiants : ils peuvent différer du champ id du résultat. Les erreurs sont sanitisées ; aucune adresse privée du moteur n’est nécessaire à votre intégration.

Traitez tout statut non 2xx avant de lire le résultat métier. Corrigez les erreurs de validation avant de réessayer ; sur 429 ou indisponibilité temporaire, utilisez des tentatives limitées avec attente progressive et respectez Retry-After lorsqu’il est présent. Une relance après une coupure réseau peut créer une nouvelle requête facturée si la précédente a réussi.