API publique & serveur MCP

Introduction

L'API publique expose le cœur de ToExplain : transformer un sujet en fiches pédagogiques visuelles (affiches 16:9). Elle est pensée pour être appelée depuis un script, un backend ou un client MCP.

• URL de base : https://api.toexplain.app (ou ton instance locale http://localhost:8080)
• Préfixe : /api/public/v1
• Facturation : chaque génération débite les tokens de ton compte (mêmes règles que dans l'app : filigrane sur le plan gratuit, erreur si solde insuffisant).
• Le modèle IA est choisi côté serveur : tu n'as rien à configurer.

Créer une clé API

Va dans Réglages → API & MCP, puis crée une clé. Le secret complet n'est affiché qu'une seule fois : copie-le immédiatement.

Toutes les requêtes publiques portent l'en-tête :

Authorization: Bearer tex_live_...

Temps de génération

L'appel de génération répond immédiatement (202) avec un identifiant de job. C'est le traitement en arrière-plan (planification, storyboard, génération d'images) qui prend du temps.

Endpoints

Lancer une génération

curl -X POST https://api.toexplain.app/api/public/v1/courses/generate \
  -H "Authorization: Bearer tex_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Comment fonctionne le DNS",
    "language": "fr",
    "sheetCount": 3
  }'

Paramètres :

• topic — sujet à expliquer (requis)
• language — fr ou en
• sheetCount — nombre de fiches (1 à 8)
• audience — public visé (optionnel)
• renderMode — poster ou editable

Réponse immédiate (202) :

{
  "course": { "id": "c_...", "status": "generating" },
  "job": { "id": "j_...", "status": "queued" },
  "tokenCost": 3
}

Flux de génération

Comme la génération est asynchrone, tu enchaînes trois étapes :

• 1. POST generate → récupère job.id + course.id
• 2. GET du job toutes les 2–3 s jusqu'à status: "completed" ou "failed"
• 3. GET du cours pour lire le titre et les URLs d'affiches

# 1. lancer
JOB=$(curl -s -X POST .../api/public/v1/courses/generate \
  -H "Authorization: Bearer tex_live_..." \
  -d '{"topic":"DNS","sheetCount":3}' | jq -r .job.id)

# 2. poller (patiemment : jusqu'à ~10 min)
while true; do
  STATUS=$(curl -s .../api/public/v1/jobs/$JOB \
    -H "Authorization: Bearer tex_live_..." | jq -r .status)
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && exit 1
  sleep 3
done

Serveur MCP

Le binaire MCP expose l'API publique comme outils dans Cursor, Claude Desktop et autres clients MCP. Il tourne en local (stdio) et utilise ta clé API.

Compiler

cd apps/api
go build -o bin/toexplain-mcp ./cmd/mcp

Configuration (mcp.json)

{
  "mcpServers": {
    "toexplain": {
      "command": "/chemin/absolu/.../apps/api/bin/toexplain-mcp",
      "env": {
        "TOEXPLAIN_API_KEY": "tex_live_...",
        "TOEXPLAIN_API_URL": "http://localhost:8080"
      }
    }
  }
}

Outils exposés :

• generate_course — génère un cours et attend la fin (jusqu'à 20 min)
• get_balance — solde de tokens et plan
• get_course — récupère un cours par ID

Erreurs

Toutes les erreurs suivent ce format :

{
  "error": {
    "code": "insufficient_tokens",
    "message": "Tokens insuffisants : cette génération coûte 3 token(s)."
  }
}