Synthesia API

Plateforme d'analyse de documents intelligente

Liens Rapides

Fonctionnalités

Traitement de Documents

Analyse Intelligente

Services ML Avancés

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        API Synthesia                         │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│  Documents  │   Analysis  │   Search    │     Services     │
│  /document  │  /analysis  │   /raptor   │  /ocr /vlm /tts  │
├─────────────┴─────────────┴─────────────┴──────────────────┤
│                       Core Services                          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │
│  │ Storage │ │   LLM   │ │ Whisper │ │  ML-Svc │          │
│  │ (Local) │ │ Albert  │ │  (STT)  │ │  (GPU)  │          │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘          │
└─────────────────────────────────────────────────────────────┘

Workflow Recommandé

1. Upload          2. Convert         3. Extract        4. Report
   ───────>           ───────>           ───────>          ───────>

┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐
│  PDF    │      │Markdown │      │ Topics  │      │  HTML   │
│  DOCX   │  →   │  Text   │  →   │ Summary │  →   │ Report  │
│  Audio  │      │         │      │         │      │ Chatbot │
└─────────┘      └─────────┘      └─────────┘      └─────────┘

Endpoints Clés

Authentification

Deux méthodes disponibles :

JWT Token (expire en 24h)

curl -X POST /auth/login \
  -d '{"username": "user", "password": "pass"}'

API Key (permanent)

curl -X POST /auth/api-keys \
  -H "Authorization: Bearer TOKEN" \
  -d '{"name": "My App"}'

Utilisation :

# JWT Token
-H "Authorization: Bearer TOKEN"

# API Key
-H "X-API-Key: sk_synthesia_..."

Formats Supportés

Documents

• PDF (.pdf) - Avec OCR si nécessaire
• Word (.docx, .doc)
• Text (.txt, .rtf, .odt)

Audio/Vidéo

• Audio : MP3, WAV, M4A, FLAC, OGG
• Vidéo : MP4, MOV, AVI, MKV, WEBM

Limites

• Taille max : 1 GB par fichier
• Recommandé : < 100 MB pour performances optimales

Instructions d'Analyse Personnalisées

Orientez l'analyse selon votre contexte métier :

{
  "analysis_instructions": "Analyse comme un expert juridique. Focus sur les clauses contractuelles et les risques."
}

Exemples de contextes

Support MCP

Intégration avec assistants IA (Claude Desktop, etc.) via Model Context Protocol.

Endpoint SSE : /mcp/sse
Messages    : /mcp/messages

Voir Guide MCP pour la configuration complète.

Prochaines Étapes

1. Démarrage Rapide - Votre premier document en 5 minutes
2. Authentification - Configuration des accès
3. Référence API - Documentation Swagger complète

Authentification

Vue d'ensemble

Synthesia supporte deux méthodes d'authentification :

1. Obtenir un Token JWT

Via JSON (Recommandé pour les applications)

curl -X POST "http://localhost:8052/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "votre_username", "password": "votre_password"}'

Réponse :

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Via OAuth2 Form (Compatible Swagger)

curl -X POST "http://localhost:8052/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=votre_username&password=votre_password"

2. Créer une API Key

Les API Keys n'expirent jamais et sont idéales pour les intégrations.

Étape 1 : Obtenir un JWT Token

Utilisez la méthode ci-dessus pour obtenir un token JWT.

Étape 2 : Créer une API Key

curl -X POST "http://localhost:8052/auth/api-keys" \
  -H "Authorization: Bearer VOTRE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mon Application"}'

Réponse :

{
  "key": "sk_synthesia_abc123...",
  "key_id": "uuid-de-la-clé",
  "name": "Mon Application",
  "created_at": "2025-01-22T10:00:00Z"
}

Important : Conservez la clé retournée immédiatement. Elle ne peut pas être récupérée ultérieurement.

3. Utiliser l'authentification

Avec un JWT Token

curl -X GET "http://localhost:8052/document/list" \
  -H "Authorization: Bearer VOTRE_JWT_TOKEN"

Avec une API Key

curl -X GET "http://localhost:8052/document/list" \
  -H "X-API-Key: sk_synthesia_votre_clé"

4. Exemples par langage

Python

import requests

# Avec JWT Token
def get_with_jwt(token: str, endpoint: str):
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(f"http://localhost:8052{endpoint}", headers=headers)
    return response.json()

# Avec API Key
def get_with_api_key(api_key: str, endpoint: str):
    headers = {"X-API-Key": api_key}
    response = requests.get(f"http://localhost:8052{endpoint}", headers=headers)
    return response.json()

# Login et obtention du token
def login(username: str, password: str) -> str:
    response = requests.post(
        "http://localhost:8052/auth/login",
        json={"username": username, "password": password}
    )
    return response.json()["access_token"]

JavaScript / TypeScript

// Avec JWT Token
async function fetchWithJWT(token, endpoint) {
  const response = await fetch(`http://localhost:8052${endpoint}`, {
    headers: { "Authorization": `Bearer ${token}` }
  });
  return response.json();
}

// Avec API Key
async function fetchWithAPIKey(apiKey, endpoint) {
  const response = await fetch(`http://localhost:8052${endpoint}`, {
    headers: { "X-API-Key": apiKey }
  });
  return response.json();
}

// Login
async function login(username, password) {
  const response = await fetch("http://localhost:8052/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ username, password })
  });
  const data = await response.json();
  return data.access_token;
}

5. Gérer vos API Keys

Lister vos API Keys

curl -X GET "http://localhost:8052/auth/api-keys" \
  -H "Authorization: Bearer VOTRE_JWT_TOKEN"

Révoquer une API Key

curl -X DELETE "http://localhost:8052/auth/api-keys/KEY_ID" \
  -H "Authorization: Bearer VOTRE_JWT_TOKEN"

6. Créer un compte utilisateur

Si vous n'avez pas de compte :

curl -X POST "http://localhost:8052/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "nouveau_user",
    "email": "user@example.com",
    "password": "mot_de_passe_securise"
  }'

7. Vérifier votre identité

Pour obtenir les informations de l'utilisateur connecté :

curl -X GET "http://localhost:8052/auth/me" \
  -H "Authorization: Bearer VOTRE_JWT_TOKEN"

Réponse :

{
  "user_id": "uuid-utilisateur",
  "username": "votre_username",
  "email": "votre@email.com",
  "is_admin": false,
  "disabled": false
}

Références Swagger

• Endpoints d'authentification
• Tester le login

Démarrage Rapide

Analysez votre premier document en 5 étapes.

Prérequis

• URL de l'API : http://localhost:8052 (ou votre URL de production)
• Identifiants : username et password

1. Authentification

Obtenez un token JWT pour les appels suivants :

# Enregistrer le token dans une variable
TOKEN=$(curl -s -X POST "http://localhost:8052/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "VOTRE_USERNAME", "password": "VOTRE_PASSWORD"}' \
  | jq -r '.access_token')

echo "Token: $TOKEN"

2. Upload d'un document

Uploadez un fichier (PDF, DOCX, audio, vidéo) :

curl -X POST "http://localhost:8052/document/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/chemin/vers/document.pdf"

Réponse :

{
  "document_id": "abc12345-6789-...",
  "message": "File uploaded successfully"
}

Conservez le document_id pour les étapes suivantes.

3. Vérifier le statut

Attendez que le traitement soit terminé :

DOC_ID="votre_document_id"

curl -X GET "http://localhost:8052/document/status/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN"

Réponse (traitement terminé) :

{
  "document_id": "abc12345...",
  "status": "completed",
  "processes": {
    "markdown_conversion": {"status": "completed"},
    "topic_extraction": {"status": "pending"},
    "raptor_index": {"status": "pending"}
  }
}

4. Extraire les thèmes

Lancez l'extraction automatique des thèmes :

curl -X POST "http://localhost:8052/topics/extract_topics/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN"

Réponse :

{
  "document_id": "abc12345...",
  "topics": [
    {
      "topic_name": "Stratégie d'entreprise",
      "summary": "Discussion sur les objectifs 2025",
      "relevance_score": 0.95
    },
    {
      "topic_name": "Budget",
      "summary": "Allocation des ressources financières",
      "relevance_score": 0.87
    }
  ]
}

5. Générer un rapport

Créez un rapport d'analyse complet :

curl -X GET "http://localhost:8052/analysis/get_report/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN"

Le rapport HTML est généré avec : - Synthèse exécutive - Analyse par thème - Points clés identifiés - Chatbot intégré pour Q&A

6. Rechercher dans le document (RAPTOR)

Posez des questions sur le contenu :

curl -X GET "http://localhost:8052/raptor/query/$DOC_ID?query=Quels sont les objectifs principaux ?" \
  -H "Authorization: Bearer $TOKEN"

Réponse :

{
  "query": "Quels sont les objectifs principaux ?",
  "response": "Les objectifs principaux identifiés sont...",
  "sources": ["Section 2.1", "Annexe A"],
  "confidence": 0.92
}

Workflow Tout-en-Un

Pour traiter un fichier de A à Z en une seule requête :

curl -X POST "http://localhost:8052/analysis/get_report_from_any_file" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/chemin/vers/document.pdf" \
  -F "gravity=0.5"

Cette requête : 1. Upload le fichier 2. Convertit en markdown 3. Extrait les thèmes 4. Crée l'index de recherche 5. Génère le rapport complet

Exemples Complets

Python

import requests

BASE_URL = "http://localhost:8052"

# 1. Login
def login(username, password):
    response = requests.post(f"{BASE_URL}/auth/login",
        json={"username": username, "password": password})
    return response.json()["access_token"]

# 2. Upload document
def upload_document(token, file_path):
    with open(file_path, "rb") as f:
        response = requests.post(f"{BASE_URL}/document/upload",
            headers={"Authorization": f"Bearer {token}"},
            files={"file": f})
    return response.json()["document_id"]

# 3. Wait for processing
def wait_for_status(token, doc_id, timeout=300):
    import time
    for _ in range(timeout // 5):
        response = requests.get(f"{BASE_URL}/document/status/{doc_id}",
            headers={"Authorization": f"Bearer {token}"})
        data = response.json()
        if data.get("status") == "completed":
            return True
        time.sleep(5)
    return False

# 4. Extract topics
def extract_topics(token, doc_id):
    response = requests.post(f"{BASE_URL}/topics/extract_topics/{doc_id}",
        headers={"Authorization": f"Bearer {token}"})
    return response.json()

# 5. Generate report
def generate_report(token, doc_id):
    response = requests.get(f"{BASE_URL}/analysis/get_report/{doc_id}",
        headers={"Authorization": f"Bearer {token}"})
    return response.json()

# Workflow complet
token = login("username", "password")
doc_id = upload_document(token, "document.pdf")
wait_for_status(token, doc_id)
topics = extract_topics(token, doc_id)
report = generate_report(token, doc_id)
print(f"Rapport généré: {report.get('report_url')}")

JavaScript

const BASE_URL = "http://localhost:8052";

async function analyzeDocument(username, password, filePath) {
  // 1. Login
  const loginRes = await fetch(`${BASE_URL}/auth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ username, password })
  });
  const { access_token: token } = await loginRes.json();

  // 2. Upload
  const formData = new FormData();
  formData.append("file", fileInput.files[0]);

  const uploadRes = await fetch(`${BASE_URL}/document/upload`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${token}` },
    body: formData
  });
  const { document_id: docId } = await uploadRes.json();

  // 3. Wait for completion
  let status = "processing";
  while (status !== "completed") {
    await new Promise(r => setTimeout(r, 5000));
    const statusRes = await fetch(`${BASE_URL}/document/status/${docId}`, {
      headers: { "Authorization": `Bearer ${token}` }
    });
    const statusData = await statusRes.json();
    status = statusData.status;
  }

  // 4. Extract topics
  await fetch(`${BASE_URL}/topics/extract_topics/${docId}`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${token}` }
  });

  // 5. Generate report
  const reportRes = await fetch(`${BASE_URL}/analysis/get_report/${docId}`, {
    headers: { "Authorization": `Bearer ${token}` }
  });
  return reportRes.json();
}

Prochaines étapes

• Référence complète des routes - Swagger interactif
• Services ML (OCR, TTS, VLM) - Fonctionnalités avancées
• Administration - Gestion des utilisateurs

Référence des Endpoints

Documentation complète de tous les points d'entrée de l'API.

Explorer dans Swagger UI

Authentification

Tester dans Swagger

Documents

Upload et Conversion

Gestion

Tester dans Swagger

Extraction de Thèmes

Paramètres d'extraction

Tester dans Swagger

Recherche RAPTOR

Exemple de recherche

curl -X GET "/raptor/query/{doc_id}?query=Quels sont les objectifs ?" \
  -H "Authorization: Bearer TOKEN"

Tester dans Swagger

Analyse et Rapports

Endpoints Tout-en-Un

Tester dans Swagger

Prompts

Tester dans Swagger

Santé du Service

Tester dans Swagger

Services ML

Voir la section Services pour la documentation détaillée.

Endpoints Publics

Accessibles sans authentification :

MCP (Model Context Protocol)

Intégration avec assistants IA :

Voir Guide MCP

Paramètres Communs

Headers d'authentification

Authorization: Bearer VOTRE_JWT_TOKEN
# ou
X-API-Key: sk_synthesia_VOTRE_CLE

Paramètre return_id

Disponible sur la plupart des endpoints de traitement :

Formats de sortie

Codes de Réponse

Limites

Administration

Routes réservées aux administrateurs - voir section Admin.

API de Téléchargement de Fichiers

Formats Supportés

Documents

• PDF (.pdf) - Format recommandé
• Microsoft Word (.docx, .doc)
• Text (.txt)
• RTF (.rtf)
• OpenDocument (.odt)

Audio/Vidéo

• Audio : MP3, WAV, M4A, FLAC, OGG
• Vidéo : MP4, MOV, AVI, MKV, WEBM

Upload de Fichier avec Instructions d'Analyse

Endpoint

POST /document/convert/from_file

Exemple avec cURL

curl -X POST "http://localhost:8050/document/convert/from_file" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "output_format=markdown" \
  -F "analysis_instructions=Votre contexte d'analyse personnalisé" \
  -F "picture_description=false" \
  -F "return_id=true"

Exemple avec Python

import requests

# Préparer le fichier et les paramètres
with open('document.pdf', 'rb') as f:
    files = {'file': f}
    data = {
        'output_format': 'markdown',
        'analysis_instructions': 'Analyse comme un expert juridique. Focus sur les clauses contractuelles et les risques.',
        'return_id': 'true'
    }
    headers = {'Authorization': f'Bearer {token}'}

    # Envoyer la requête
    response = requests.post(
        'http://localhost:8050/document/convert/from_file',
        files=files,
        data=data,
        headers=headers
    )

    result = response.json()
    document_id = result['document_id']

Exemple avec JavaScript

async function uploadDocument(file, analysisContext) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('output_format', 'markdown');
  formData.append('analysis_instructions', analysisContext);
  formData.append('return_id', 'true');

  const response = await fetch('http://localhost:8050/document/convert/from_file', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`
    },
    body: formData
  });

  const result = await response.json();
  return result.document_id;
}

Upload depuis URL

Endpoint

POST /document/convert/from_url

Exemple

POST /document/convert/from_url
{
  "url": "https://example.com/document.pdf",
  "output_format": "markdown",
  "analysis_instructions": "Analyse technique focalisée sur l'architecture système",
  "return_id": true
}

Transcription Audio/Vidéo

Endpoint

POST /document/convert/from_audio

Paramètres spécifiques

• language: Code langue (fr, en, es, etc.)
• output_format: Format de sortie de la transcription
• analysis_instructions: Contexte pour l'analyse de la transcription

Exemple pour un entretien RH

curl -X POST "http://localhost:8050/document/convert/from_audio" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@interview.mp3" \
  -F "language=fr" \
  -F "output_format=markdown" \
  -F "analysis_instructions=Analyse cet entretien RH. Focus sur les compétences techniques, l'expérience en leadership et l'adéquation culturelle." \
  -F "return_id=true"

Gestion des Erreurs

Codes de réponse

Exemple de gestion d'erreur

try {
  const response = await uploadDocument(file, context);

  if (!response.ok) {
    switch(response.status) {
      case 400:
        throw new Error('Format de fichier non supporté');
      case 413:
        throw new Error('Fichier trop volumineux (max 1GB)');
      case 401:
        throw new Error('Token expiré, reconnexion nécessaire');
      default:
        throw new Error('Erreur lors de l\'upload');
    }
  }
} catch (error) {
  console.error('Erreur:', error.message);
}

Limites et Recommandations

Taille des fichiers

• Maximum : 1GB par fichier
• Recommandé : < 100MB pour des performances optimales

Formats recommandés

• Documents texte : PDF avec OCR déjà effectué
• Audio : MP3 ou M4A pour la meilleure compatibilité
• Vidéo : MP4 H.264 pour un traitement rapide

Optimisation

• Utilisez return_id=true pour les gros fichiers
• Compressez les vidéos avant upload si possible
• Pour les PDFs scannés, activez picture_description=true

Suivi du Traitement

Après upload avec return_id=true, surveillez l'état :

async function checkStatus(documentId) {
  const response = await fetch(
    `http://localhost:8050/document/status/${documentId}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );

  const status = await response.json();

  if (status.processes.markdown_conversion.status === 'completed') {
    console.log('Conversion terminée !');
  }
}

Services ML

Documentation des services de Machine Learning avancés.

Vue d'ensemble

OCR - Extraction de Texte

Extraction de texte depuis images et PDFs scannés.

Endpoints

Exemple

curl -X POST "http://localhost:8052/ocr/extract" \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@image.png" \
  -F "language=fr"

Réponse :

{
  "text": "Texte extrait de l'image...",
  "confidence": 0.95,
  "language": "fr",
  "processing_time": 1.2
}

Langues supportées

auto, en, fr, es, de, it, pt, nl, pl, ru, zh, ja, ko

Tester dans Swagger

VLM - Vision-Language

Modèle multimodal pour description et Q&A sur images.

Endpoints

Exemple : Décrire une image

curl -X POST "http://localhost:8052/vlm/describe" \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@photo.jpg" \
  -F "language=fr"

Réponse :

{
  "description": "L'image montre un graphique représentant l'évolution des ventes...",
  "confidence": 0.87,
  "backend": "hunyuan",
  "processing_time": 2.3
}

Exemple : Question sur image

curl -X POST "http://localhost:8052/vlm/query" \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@document.png" \
  -F "question=Quelle est la date mentionnée ?"

Tester dans Swagger

TTS - Synthèse Vocale

Génération de parole à partir de texte avec Supertonic 2.

Endpoints

Voix disponibles

Langues supportées

en, fr, es, pt, ko

Exemple

curl -X POST "http://localhost:8052/tts/stream" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Bonjour, ceci est un test de synthèse vocale.",
    "voice": "F3",
    "language": "fr",
    "speed": 1.0,
    "quality": 5
  }' \
  --output audio.wav

Paramètres

Tester dans Swagger

Translation - Traduction

Traduction multilingue avec TranslateGemma.

Endpoints

Exemple

curl -X POST "http://localhost:8052/translation/translate" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, how are you?",
    "source_language": "auto",
    "target_language": "fr"
  }'

Réponse :

{
  "translated_text": "Bonjour, comment allez-vous ?",
  "source_language": "en",
  "target_language": "fr",
  "detected_language": "en",
  "processing_time_ms": 150
}

Langues supportées (55)

Dont : en, fr, es, de, it, pt, nl, pl, ru, zh, ja, ko, ar, hi, etc.

Tester dans Swagger

NER - Entités Nommées

Extraction et anonymisation d'entités.

Endpoints

Types d'entités

Exemple : Extraction

curl -X POST "http://localhost:8052/ner/extract" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Jean Dupont travaille chez Acme Corp depuis 2020.",
    "entity_types": ["person", "organization", "date"]
  }'

Réponse :

{
  "entities": [
    {"text": "Jean Dupont", "type": "person", "start": 0, "end": 11},
    {"text": "Acme Corp", "type": "organization", "start": 26, "end": 35},
    {"text": "2020", "type": "date", "start": 43, "end": 47}
  ],
  "entity_count": 3
}

Exemple : Anonymisation

curl -X POST "http://localhost:8052/ner/anonymize" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Contactez Jean Dupont à jean@email.com",
    "mode": "replace"
  }'

Réponse :

{
  "anonymized_text": "Contactez [PERSON_1] à [EMAIL_1]",
  "mapping": {
    "[PERSON_1]": "Jean Dupont",
    "[EMAIL_1]": "jean@email.com"
  }
}

Tester dans Swagger

Embeddings - Vecteurs Sémantiques

Génération d'embeddings multimodaux.

Endpoints

Exemple

curl -X POST "http://localhost:8052/embed/text" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Analyse des données financières"}'

Réponse :

{
  "embedding": [0.123, -0.456, 0.789, ...],
  "dimension": 1024,
  "model": "qwen3-vl-embedding",
  "processing_time": 0.15
}

Batch Embeddings

curl -X POST "http://localhost:8052/embed/batch" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"type": "text", "text": "Premier texte"},
      {"type": "text", "text": "Deuxième texte"}
    ]
  }'

Tester dans Swagger

Graph - Graphes de Connaissances

Graphes relationnels entre documents et entités.

Endpoints

Exemple

curl -X POST "http://localhost:8052/graph/build/DOC_ID" \
  -H "Authorization: Bearer TOKEN"

Tester dans Swagger

Diarization - Identification des Locuteurs

Identification et séparation des locuteurs dans un audio.

Endpoints

Exemple

curl -X POST "http://localhost:8052/diarization/process" \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@interview.mp3"

Réponse :

{
  "speakers": ["SPEAKER_00", "SPEAKER_01"],
  "segments": [
    {"start": 0.0, "end": 5.2, "speaker": "SPEAKER_00", "text": "Bonjour..."},
    {"start": 5.5, "end": 12.0, "speaker": "SPEAKER_01", "text": "Merci..."}
  ],
  "duration": 120.5
}

Tester dans Swagger

Statut des Services

Vérifier la disponibilité des services ML :

curl -X GET "http://localhost:8052/health/system" \
  -H "Authorization: Bearer TOKEN"

Réponse :

{
  "status": "healthy",
  "services": {
    "ocr": "available",
    "vlm": "available",
    "tts": "available",
    "translation": "available",
    "embeddings": "available"
  },
  "gpu": {
    "available": true,
    "memory_utilization": 45.0
  }
}

Guide Complet de l'Extraction de Thèmes

Vue d'ensemble

L'extraction de thèmes permet d'identifier automatiquement les sujets principaux et sous-thèmes d'un document. Avec les nouveaux paramètres, vous pouvez guider et personnaliser cette extraction selon vos besoins spécifiques.

Méthodes d'Extraction

1. LLM (Intelligence Artificielle)

• Analyse sémantique profonde
• Comprend le contexte et les nuances
• Respecte les instructions d'analyse personnalisées
• Idéal pour : documents complexes, analyses spécialisées

2. BERTopic (Statistique)

• Clustering basé sur les similarités
• Identification de patterns récurrents
• Peut être guidé par des seed words/topics
• Idéal pour : grands corpus, analyses exploratoires

3. Both (Combiné)

• Fusion des approches LLM et BERTopic
• Déduplication automatique
• Vue la plus complète
• Idéal pour : analyses critiques, rapports complets

Paramètres Disponibles

Paramètres de base

Paramètres BERTopic

Comprendre la Gravity

• 0.0 : Maximum de thèmes (très granulaire)
• 0.3 : Beaucoup de thèmes détaillés
• 0.5 : Équilibre (défaut)
• 0.7 : Thèmes principaux seulement
• 1.0 : Très peu de thèmes (vue macro)

Exemples Complets

Exemple 1 : Extraction Simple avec LLM

curl -X POST "http://localhost:8050/topics/extract_topics/DOCUMENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "llm",
    "return_id": false
  }'

Cas d'usage : Document standard nécessitant une analyse rapide et intelligente.

Exemple 2 : Extraction BERTopic avec Guidage

curl -X POST "http://localhost:8050/topics/extract_topics/DOCUMENT_ID?method=bertopic&gravity=0.3&return_id=false" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -G \
  --data-urlencode 'seed_words=innovation,technologie,IA,transformation digitale,cloud,data' \
  --data-urlencode 'seed_topics=[["machine learning","deep learning","neural networks"],["cloud computing","AWS","Azure"],["data science","analytics","big data"]]'

Cas d'usage : Document technique où vous savez quels thèmes rechercher.

Exemple 3 : Analyse RH d'un Entretien

D'abord, upload avec instructions :

# 1. Upload avec contexte RH
curl -X POST "http://localhost:8050/document/convert/from_audio" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@interview.mp3" \
  -F "language=fr" \
  -F "analysis_instructions=Agis comme un spécialiste RH évaluant un candidat pour un poste de manager. Focus sur : compétences techniques, leadership, communication, travail en équipe, motivation, adéquation culturelle." \
  -F "return_id=false"

# 2. Extraction guidée
curl -X POST "http://localhost:8050/topics/extract_topics/DOCUMENT_ID?method=both&gravity=0.4" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -G \
  --data-urlencode 'seed_topics=[
    ["compétences techniques","expertise","savoir-faire"],
    ["leadership","management","gestion équipe"],
    ["soft skills","communication","relationnel"],
    ["expérience","parcours","réalisations"],
    ["motivation","ambition","objectifs"]
  ]'

Résultat attendu : Thèmes orientés RH avec analyse des compétences du candidat.

Exemple 4 : Analyse Médicale d'un Dossier Patient

# 1. Upload du dossier médical
curl -X POST "http://localhost:8050/document/convert/from_file" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@dossier_medical.pdf" \
  -F "analysis_instructions=Analyse ce dossier comme un professionnel médical. Identifie : symptômes, antécédents, examens, diagnostics, traitements, suivi nécessaire, facteurs de risque." \
  -F "return_id=false"

# 2. Extraction avec seeds médicaux
curl -X POST "http://localhost:8050/topics/extract_topics/DOCUMENT_ID?method=both&gravity=0.3" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -G \
  --data-urlencode 'seed_words=symptômes,diagnostic,traitement,médicaments,examens,antécédents,allergie,pathologie,thérapie,posologie' \
  --data-urlencode 'seed_topics=[
    ["symptômes","signes cliniques","manifestations"],
    ["diagnostic","examens","analyses"],
    ["traitement","thérapeutique","médication"],
    ["antécédents","historique médical","comorbidités"],
    ["suivi","surveillance","contrôle"]
  ]'

Exemple 5 : Analyse Financière d'un Rapport Annuel

# 1. Configuration des paramètres
DOCUMENT_ID="your-document-id"
TOKEN="your-token"

# 2. Extraction avec guidage financier
curl -X POST "http://localhost:8050/topics/extract_topics/${DOCUMENT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "both",
    "gravity": 0.5,
    "seed_multiplier": 3.0,
    "return_id": false
  }' \
  -G \
  --data-urlencode 'seed_words=revenus,EBITDA,croissance,marge,ROI,cash flow,dette,investissement,risque,opportunité' \
  --data-urlencode 'seed_topics=[
    ["performance financière","résultats","KPIs"],
    ["croissance","expansion","développement"],
    ["risques","challenges","menaces"],
    ["opportunités","potentiel","marchés"],
    ["stratégie","vision","objectifs"]
  ]'

Exemple 6 : Analyse Juridique de Contrat

import requests
import json

# Configuration
document_id = "contract-doc-id"
token = "your-token"
base_url = "http://localhost:8050"

# Paramètres juridiques
params = {
    "method": "both",
    "gravity": 0.2,  # Plus de détails pour analyse juridique
    "return_id": False,
    "seed_multiplier": 2.5
}

# Topics juridiques guidés
seed_topics = [
    ["obligations", "engagements", "responsabilités"],
    ["clauses", "conditions", "termes"],
    ["pénalités", "sanctions", "indemnités"],
    ["propriété intellectuelle", "confidentialité", "données"],
    ["résiliation", "rupture", "fin de contrat"],
    ["litiges", "arbitrage", "juridiction"]
]

seed_words = "clause,obligation,responsabilité,garantie,indemnité,résiliation,confidentialité,propriété,litige,force majeure"

# Requête
response = requests.post(
    f"{base_url}/topics/extract_topics/{document_id}",
    headers={"Authorization": f"Bearer {token}"},
    params=params,
    data={
        "seed_topics": json.dumps(seed_topics),
        "seed_words": seed_words
    }
)

topics = response.json()
print(f"Thèmes juridiques identifiés: {len(topics['topics'])}")

Exemple 7 : Analyse Technique de Documentation

async function extractTechnicalTopics(documentId) {
  const params = new URLSearchParams({
    method: 'both',
    gravity: 0.4,
    seed_multiplier: 2.0,
    return_id: 'false'
  });

  // Topics techniques spécifiques
  const seedTopics = [
    ["architecture", "design", "patterns"],
    ["API", "endpoints", "interfaces"],
    ["sécurité", "authentification", "autorisation"],
    ["performance", "optimisation", "scalabilité"],
    ["technologies", "frameworks", "librairies"],
    ["déploiement", "CI/CD", "DevOps"]
  ];

  const seedWords = "API,REST,microservices,cloud,docker,kubernetes,sécurité,performance,architecture,database";

  params.append('seed_topics', JSON.stringify(seedTopics));
  params.append('seed_words', seedWords);

  const response = await fetch(
    `${API_BASE_URL}/topics/extract_topics/${documentId}?${params}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return await response.json();
}

Workflow Complet avec Python

import requests
import time
import json

class TopicExtractor:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {"Authorization": f"Bearer {token}"}

    def extract_with_guidance(self, document_id, domain_config):
        """
        Extraction guidée selon le domaine

        domain_config = {
            'domain': 'finance',  # finance, hr, medical, legal, tech
            'gravity': 0.5,
            'seed_words': [],
            'seed_topics': []
        }
        """

        # Configurations prédéfinies par domaine
        domain_presets = {
            'finance': {
                'gravity': 0.5,
                'seed_words': 'revenus,coûts,marge,croissance,risque,investissement',
                'seed_topics': [
                    ["performance", "résultats", "KPIs"],
                    ["stratégie", "objectifs", "vision"]
                ]
            },
            'hr': {
                'gravity': 0.4,
                'seed_words': 'compétences,expérience,leadership,motivation,culture',
                'seed_topics': [
                    ["compétences", "expertise", "savoir-faire"],
                    ["personnalité", "soft skills", "comportement"]
                ]
            },
            'medical': {
                'gravity': 0.3,
                'seed_words': 'symptômes,diagnostic,traitement,médicament,examen',
                'seed_topics': [
                    ["pathologie", "maladie", "syndrome"],
                    ["thérapeutique", "traitement", "médication"]
                ]
            }
        }

        # Merge avec les presets
        config = domain_presets.get(domain_config['domain'], {})
        config.update(domain_config)

        # Préparer la requête
        params = {
            'method': 'both',
            'gravity': config.get('gravity', 0.5),
            'return_id': 'true'
        }

        if config.get('seed_words'):
            params['seed_words'] = config['seed_words']

        if config.get('seed_topics'):
            params['seed_topics'] = json.dumps(config['seed_topics'])

        # Lancer l'extraction
        response = requests.post(
            f"{self.base_url}/topics/extract_topics/{document_id}",
            headers=self.headers,
            params=params
        )

        if response.status_code == 200:
            result = response.json()

            # Si asynchrone, attendre la fin
            if result.get('status') == 'processing':
                return self.wait_for_completion(document_id)

            return result
        else:
            raise Exception(f"Extraction failed: {response.text}")

    def wait_for_completion(self, document_id, timeout=300):
        """Attendre la fin de l'extraction"""
        start_time = time.time()

        while time.time() - start_time < timeout:
            status = requests.get(
                f"{self.base_url}/document/status/{document_id}",
                headers=self.headers
            ).json()

            topic_status = status['processes'].get('topic_deduplication', {})

            if topic_status.get('status') == 'completed':
                # Récupérer les thèmes
                topics = requests.get(
                    f"{self.base_url}/topics/extract_topics/{document_id}",
                    headers=self.headers
                ).json()
                return topics

            elif topic_status.get('status') == 'error':
                raise Exception(f"Extraction failed: {topic_status.get('error')}")

            time.sleep(5)

        raise TimeoutError("Topic extraction timeout")

# Utilisation
extractor = TopicExtractor("http://localhost:8050", "YOUR_TOKEN")

# Exemple finance
finance_topics = extractor.extract_with_guidance(
    document_id="doc-123",
    domain_config={
        'domain': 'finance',
        'gravity': 0.6,
        'seed_words': 'blockchain,crypto,DeFi,tokenisation'  # Ajout spécifique
    }
)

Optimisation des Résultats

Ajuster la Gravity

Seed Topics Efficaces

✅ Bonnes pratiques :

[
  ["terme principal", "synonyme 1", "synonyme 2"],
  ["concept", "variation", "abréviation"]
]

❌ À éviter :

[
  ["mot seul"],  // Trop restrictif
  ["phrase très longue et complexe"]  // Trop spécifique
]

Seed Words Stratégiques

Pour guider sans contraindre :

seed_multiplier=2.0  // Influence modérée
seed_words="5-10 mots clés pertinents"

Pour forcer certains thèmes :

seed_multiplier=5.0  // Forte influence
seed_words="mots critiques à ne pas manquer"

Interprétation des Résultats

Structure de la réponse

{
  "success": true,
  "topics": {
    "topics": [
      {
        "name": "Innovation technologique",
        "short_name": "Innovation",
        "subtopics": ["IA", "Blockchain", "IoT"],
        "description": "Les avancées technologiques...",
        "source": "llm"
      },
      {
        "name": "Transformation digitale",
        "short_name": "Digital",
        "subtopics": ["Cloud", "Data", "Automatisation"],
        "description": "La digitalisation des processus...",
        "source": "bertopic"
      }
    ]
  }
}

Analyser la source

• source: "llm" : Thème identifié par analyse sémantique
• source: "bertopic" : Thème identifié par clustering
• source: "merged" : Thème présent dans les deux analyses

Résolution de Problèmes

Trop peu de thèmes

• Diminuer la gravity (ex: 0.5 → 0.3)
• Ajouter des seed_topics pertinents
• Utiliser method="both"

Trop de thèmes

• Augmenter la gravity (ex: 0.5 → 0.7)
• Réduire seed_multiplier
• Utiliser method="llm" pour consolidation intelligente

Thèmes non pertinents

• Fournir des analysis_instructions lors de l'upload
• Utiliser des seed_words spécifiques au domaine
• Ajuster seed_multiplier (2.0-3.0 optimal)

Performance lente

• Utiliser return_id=true pour traitement asynchrone
• Préférer method="llm" pour rapidité
• Augmenter gravity pour réduire le nombre de thèmes

Bonnes Pratiques

1. Toujours fournir analysis_instructions lors de l'upload pour un contexte optimal
2. Commencer avec gravity=0.5 puis ajuster selon les résultats
3. Utiliser des seed_topics pour les analyses spécialisées
4. Combiner LLM et BERTopic (method="both") pour les documents importants
5. Surveiller le status pour les traitements asynchrones
6. Sauvegarder les paramètres qui fonctionnent bien pour votre domaine

Génération de Détails Thématiques

Vue d'ensemble

La génération de détails thématiques est une étape cruciale qui enrichit les thèmes extraits avec des analyses approfondies et des synthèses contextuelles.

Processus de génération

1. Extraction initiale des thèmes

Les thèmes sont d'abord extraits via : - LLM : Analyse sémantique intelligente - BERTopic : Clustering statistique - Both : Combinaison des deux approches

2. Enrichissement avec instructions d'analyse

Si des analysis_instructions ont été fournies lors de l'upload : - Les thèmes sont orientés selon le contexte spécifié - Les synthèses adoptent la perspective demandée - Les recommandations sont adaptées au domaine

3. Structure des détails thématiques

Chaque thème génère un fichier JSON contenant :

{
  "topic_name": "Nom du thème principal",
  "short_name": "Nom court",
  "subtopics": ["Sous-thème 1", "Sous-thème 2"],
  "description": "Description concise du thème",
  "synthesis": "Analyse approfondie de 300-500 mots...",
  "source": "llm ou bertopic"
}

Fichiers générés

Structure des dossiers

document_id/
├── general_topics.json       # Liste unifiée des thèmes
├── llm_topics.json           # Thèmes extraits par LLM
├── bertopic_topics.json      # Thèmes extraits par BERTopic
└── topic_details/            # Dossier des analyses détaillées
    ├── theme_1.json
    ├── theme_2.json
    └── ...

Contenu d'une synthèse

La synthèse de chaque thème inclut :

1. Contexte et importance : Mise en perspective du thème
2. Analyse des sous-thèmes : Relations et interconnexions
3. Implications principales : Impact et conséquences
4. Recommandations : Actions suggérées selon le contexte

Personnalisation avec Instructions

Sans instructions

Analyse générale et neutre des thèmes identifiés.

Avec instructions RH

"Agis comme un spécialiste RH..."

→ Focus sur compétences, expérience, adéquation culturelle

Avec instructions médicales

"Analyse comme un professionnel médical..."

→ Focus sur symptômes, diagnostic, traitement

Avec instructions financières

"Analyse comme un expert financier..."

→ Focus sur KPIs, risques, opportunités d'investissement

API Endpoints

Forcer la régénération

POST /analysis/create_report/{document_id}?force_regenerate_topics=true

Force la régénération complète des détails thématiques.

Récupérer les détails

GET /document/get_file/{document_id}/topic_details/theme_name.json

Optimisation et Performance

Mise en cache

• Les détails sont générés une seule fois
• Réutilisés pour les rapports ultérieurs
• Supprimés uniquement si force_regenerate_topics=true

Traitement parallèle

• Génération simultanée de plusieurs thèmes
• Utilisation optimale des ressources GPU/CPU

Gestion mémoire

• Chunking intelligent pour les longs documents
• Libération automatique de la mémoire après traitement

Exemples de synthèses

Exemple 1 : Analyse technique

Thème : Architecture Cloud

Synthèse avec instructions techniques :

L'architecture cloud proposée repose sur une infrastructure multi-régions utilisant AWS. Les services clés incluent ECS pour l'orchestration de conteneurs, Lambda pour les fonctions serverless, et API Gateway pour la gestion des APIs. La scalabilité horizontale est assurée par des Auto Scaling Groups...

Exemple 2 : Analyse RH

Thème : Compétences en Leadership

Synthèse avec instructions RH :

Le candidat démontre une expérience solide en gestion d'équipes de 5 à 15 personnes. Son approche du leadership s'articule autour du mentorat et de la collaboration. Les exemples concrets incluent la restructuration d'une équipe en difficulté...

Intégration dans le Pipeline

graph LR
    A[Upload + Instructions] --> B[Extraction Thèmes]
    B --> C[Génération Détails]
    C --> D[Création Synthèses]
    D --> E[Génération Rapport]

    style A fill:#f9f,stroke:#333
    style C fill:#bbf,stroke:#333
    style E fill:#bfb,stroke:#333

Résolution de problèmes

Détails manquants

• Vérifiez que l'extraction de thèmes est complète
• Utilisez force_regenerate_topics=true si nécessaire

Synthèses génériques

• Fournissez des analysis_instructions plus spécifiques
• Utilisez des seed_words pour guider l'extraction

Performance lente

• Réduisez le nombre de thèmes avec gravity plus élevée
• Utilisez method=llm au lieu de both pour plus de rapidité

Configuration avancée

Paramètres de génération

Dans core/api_utils.py :

SYNTHESIS_MAX_LENGTH = 500  # Mots par synthèse
SYNTHESIS_TEMPERATURE = 0.7  # Créativité (0.0-1.0)
SYNTHESIS_LANGUAGE = "fr"    # Langue des synthèses

Personnalisation des prompts

Dans core/prompts.py, modifiez : - topic_analysis_prompt : Structure de l'analyse - unified_topic_synthesis_prompt : Format des synthèses

Utilisation de l'Interface Swagger

Accès à l'interface

Une fois l'API démarrée, accédez à l'interface Swagger :

• Swagger UI : /docs
• ReDoc : /redoc (interface alternative)
• OpenAPI JSON : /openapi.json

Authentification dans Swagger

1. Obtenir un token

1. Cliquez sur l'endpoint /auth/login
2. Cliquez sur "Try it out"
3. Entrez vos identifiants :

{
  "username": "votre_nom",
  "password": "votre_mot_de_passe"
}

1. Cliquez sur "Execute"
2. Copiez le token depuis la réponse

2. Configurer l'authentification

1. Cliquez sur le bouton "Authorize" en haut de la page
2. Dans le champ "Value", entrez : Bearer VOTRE_TOKEN
3. Cliquez sur "Authorize"
4. Cliquez sur "Close"

Vous êtes maintenant authentifié pour tous les endpoints !

Navigation dans l'interface

Organisation par catégories

Les endpoints sont groupés par fonctionnalité : - Health : Vérification de l'état - Authentication : Connexion et inscription - Documents : Gestion des documents - Topics : Extraction de thèmes - RAPTOR : Recherche sémantique - Analysis : Génération de rapports - OCR : Extraction de texte - VLM : Vision-Language - TTS : Synthèse vocale - Translation : Traduction - NER : Entités nommées - Embeddings : Vecteurs sémantiques - Admin : Administration (admin seulement)

Exploration d'un endpoint

1. Cliquez sur une catégorie pour l'ouvrir
2. Cliquez sur un endpoint pour voir ses détails
3. Observez :
4. Parameters : Paramètres requis et optionnels
5. Request body : Structure des données à envoyer
6. Responses : Formats de réponse possibles

Test d'un endpoint

Exemple : Upload de document avec analyse personnalisée

1. Naviguez vers POST /document/convert/from_file
2. Cliquez sur "Try it out"
3. Remplissez les paramètres :
4. file : Cliquez sur "Choose File" et sélectionnez un PDF
5. output_format : markdown
6. analysis_instructions : Analyse comme un expert financier
7. return_id : true
8. Cliquez sur "Execute"
9. Observez la réponse avec le document_id

Exemple : Vérification du statut

1. Copiez le document_id de l'étape précédente
2. Naviguez vers GET /document/status/{document_id}
3. Cliquez sur "Try it out"
4. Collez l'ID dans le champ document_id
5. Cliquez sur "Execute"
6. Vérifiez l'état du traitement

Fonctionnalités utiles

Export de la documentation

• Cliquez sur le lien /openapi.json pour obtenir la spécification OpenAPI
• Utilisez cette spec pour générer des clients dans différents langages

Schemas des modèles

Scrollez en bas de la page pour voir tous les modèles de données : - User : Structure utilisateur - Document : Métadonnées document - Topic : Structure des thèmes - HTTPValidationError : Format des erreurs

Test de workflows complets

Workflow 1 : Analyse rapide

1. /document/convert/from_file - Upload avec instructions
2. /topics/extract_topics/{id} - Extraction de thèmes
3. /analysis/create_report/{id} - Génération de rapport
4. /analysis/get_report/{id} - Récupération du rapport

Workflow 2 : Recherche dans document

1. /document/convert/from_file - Upload
2. /raptor/create_index/{id} - Création index
3. /raptor/query/{id} - Requêtes de recherche

Codes de réponse courants

Astuces

Performance

• Utilisez return_id=true pour ne pas bloquer l'interface
• Testez d'abord avec de petits fichiers
• Vérifiez régulièrement le statut pour les longs traitements

Debug

• Les erreurs 422 incluent des détails sur les champs invalides
• Vérifiez l'onglet "Network" du navigateur pour plus de détails
• Les logs serveur donnent plus d'informations sur les erreurs 500

Sécurité

• Ne partagez jamais votre token
• Déconnectez-vous après vos tests (clear authorization)
• Utilisez HTTPS en production

MCP (Model Context Protocol) API

Direct SSE-based access to Synthesia document processing.

API Endpoints

Production

https://api.dev.synthesia.bhub.cloud/mcp/sse         # SSE stream
https://api.dev.synthesia.bhub.cloud/mcp/messages    # POST messages
https://api.dev.synthesia.bhub.cloud/mcp/info        # Server info
https://api.dev.synthesia.bhub.cloud/mcp/tools       # List tools

Local Development

http://localhost:8052/mcp/sse
http://localhost:8052/mcp/messages

Authentication

API Keys (Recommended)

Never expire, ideal for integrations.

1. Get JWT token:

curl -X POST 'https://api.dev.synthesia.bhub.cloud/auth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=USERNAME&password=PASSWORD'

2. Create API key:

curl -X POST 'https://api.dev.synthesia.bhub.cloud/auth/api-keys' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "My MCP Client"}'

Response: {"key": "sk_synthesia_...", "key_id": "...", ...}

3. Use API key:

curl -H "X-API-Key: sk_synthesia_YOUR_KEY" \
  https://api.dev.synthesia.bhub.cloud/mcp/info

Manage keys:

# List all your keys
curl -H "Authorization: Bearer YOUR_JWT" \
  https://api.dev.synthesia.bhub.cloud/auth/api-keys

# Revoke a key
curl -X DELETE \
  -H "Authorization: Bearer YOUR_JWT" \
  https://api.dev.synthesia.bhub.cloud/auth/api-keys/KEY_ID

JWT Bearer Tokens

Expire after 24 hours (default).

# Get token
curl -X POST 'https://api.dev.synthesia.bhub.cloud/auth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=USERNAME&password=PASSWORD'

# Use token
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.dev.synthesia.bhub.cloud/mcp/info

SSE Connection

Open SSE stream for real-time communication:

# With API key
curl -N -H "X-API-Key: sk_synthesia_YOUR_KEY" \
  https://api.dev.synthesia.bhub.cloud/mcp/sse

# With JWT token
curl -N -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.dev.synthesia.bhub.cloud/mcp/sse

Send Messages

POST JSON-RPC messages to invoke tools:

# List available tools
curl -X POST https://api.dev.synthesia.bhub.cloud/mcp/messages \
  -H "X-API-Key: sk_synthesia_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

# Call a tool
curl -X POST https://api.dev.synthesia.bhub.cloud/mcp/messages \
  -H "X-API-Key: sk_synthesia_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_document_status",
      "arguments": {"document_id": "abc123"}
    },
    "id": 2
  }'

Available Tools

Get full list: GET https://api.dev.synthesia.bhub.cloud/mcp/tools

Document Management

• upload_document - Upload PDF, DOCX, TXT, audio, video
• list_documents - List all documents with status
• get_document_status - Check processing status
• download_original_document - Download original file
• delete_document - Delete document and data

Document Conversion

• convert_file_to_document - Convert to markdown/text
• convert_url_to_document - Convert from URL
• convert_audio_to_document - Transcribe audio/video
• get_converted_document - Get markdown content
• save_converted_document - Save edited content

Document Processing

• process_document_complete - Full pipeline: convert, topics, index, report
• wait_for_processing - Wait for completion

Analysis Tools

• extract_document_topics - Extract topics with AI
• get_topic_details - Get topic information
• find_similar_topics - Find similar topics across docs
• create_search_index - Create RAPTOR index
• search_document - Semantic search
• generate_report - Generate analysis report

Text-to-Speech (TTS)

• tts_supertonic - Fast TTS with 10 preset voices (M1-M5, F1-F5)
• tts_qwen - Qwen3 Voice Design: describe voice in natural language
• list_tts_voices - List available voices and languages

Speaker Diarization

• analyze_speakers - Identify speakers in audio/video
• get_diarized_transcript - Get transcript with speaker labels
• rename_speakers - Rename identified speakers
• burn_subtitles - Burn subtitles into video

Translation

• translate_text - Translate text (55 languages)
• translate_document - Translate entire document
• detect_language - Detect text language

Vision & Images

• query_image - Query image with VLM
• search_images - Visual semantic search
• upload_image - Upload image for RAG
• ocr_image - Extract text from image (OCR)

Knowledge Graph

• build_graph - Build entity/relationship graph from document
• get_entities - Get extracted entities
• get_relationships - Get entity relationships
• visualize_graph - Graph visualization data

Embeddings

• embed_text - Generate text embedding vector
• embed_batch - Batch embedding generation
• compute_similarity - Semantic similarity between texts

Smart Search

• smart_filter - Search across multiple documents
• build_user_index - Build unified user document index
• search_user_index - Search across all user documents

Web Search

• search_web - Web search via SearXNG
• search_web_images - Web image search
• search_news - News article search

Structured Extraction

• extract_structured - Extract structured data from document using schema

Named Entity Recognition

• extract_entities - Extract named entities (NER)
• anonymize_text - Anonymize text (mask entities)

Examples

Check Server Status

curl -H "X-API-Key: sk_synthesia_YOUR_KEY" \
  https://api.dev.synthesia.bhub.cloud/mcp/info

Response:

{
  "name": "Synthesia MCP Server",
  "version": "1.0.0",
  "tool_count": 25,
  "categories": ["document_management", "conversion", "analysis"]
}

Upload Document

curl -X POST https://api.dev.synthesia.bhub.cloud/mcp/messages \
  -H "X-API-Key: sk_synthesia_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "upload_document",
      "arguments": {
        "file": "base64_encoded_file_content",
        "filename": "document.pdf"
      }
    },
    "id": 1
  }'

List Documents

curl -X POST https://api.dev.synthesia.bhub.cloud/mcp/messages \
  -H "X-API-Key: sk_synthesia_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_documents"
    },
    "id": 2
  }'

Process Document

curl -X POST https://api.dev.synthesia.bhub.cloud/mcp/messages \
  -H "X-API-Key: sk_synthesia_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "process_document_complete",
      "arguments": {
        "document_id": "abc123",
        "options": {
          "extract_topics": true,
          "create_index": true,
          "generate_report": true
        }
      }
    },
    "id": 3
  }'

Troubleshooting

Authentication Errors

"Authentication failed"

# Verify API key
curl -H "Authorization: Bearer YOUR_JWT" \
  https://api.dev.synthesia.bhub.cloud/auth/api-keys

# Check key format: must start with "sk_synthesia_"
# Regenerate if expired or invalid

"Invalid token"

# JWT expired after 24h, get new one
curl -X POST 'https://api.dev.synthesia.bhub.cloud/auth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=USERNAME&password=PASSWORD'

Connection Errors

SSE stream not connecting - Verify URL: https://api.dev.synthesia.bhub.cloud/mcp/sse - Check authentication header - Ensure firewall allows SSE connections

Messages endpoint timeout - Check network connectivity - Verify endpoint: https://api.dev.synthesia.bhub.cloud/mcp/messages - Try with shorter timeout: curl --max-time 30

Tool Errors

"Tool not found"

# Get list of available tools
curl https://api.dev.synthesia.bhub.cloud/mcp/tools

"Invalid arguments" - Check tool schema in /mcp/tools response - Ensure all required arguments provided - Validate argument types (string, number, boolean, object)

API Documentation

Full REST API docs: https://api.dev.synthesia.bhub.cloud/docs

Interactive OpenAPI interface with: - All endpoints and schemas - Try-it-out functionality - Request/response examples - Authentication testing

Administration

Routes réservées aux utilisateurs avec is_admin=true.

Vérifier le statut Admin

curl -X GET "http://API_URL/auth/me" \
  -H "Authorization: Bearer TOKEN"

Si is_admin: true, vous avez accès aux routes admin.

Gestion des Utilisateurs

Exemple : Lister les utilisateurs

curl -X GET "http://API_URL/admin/users" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Réponse :

{
  "users": [
    {
      "user_id": "uuid-1",
      "username": "user1",
      "email": "user1@example.com",
      "is_admin": false,
      "disabled": false,
      "created_at": "2025-01-01T10:00:00Z"
    }
  ],
  "total": 150
}

Promouvoir un utilisateur Admin

curl -X PUT "http://API_URL/admin/users/USER_ID/admin" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_admin": true}'

Gestion des Groupes

Exemple : Créer un groupe

curl -X POST "http://API_URL/admin/groups" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Équipe Juridique",
    "description": "Groupe pour les documents juridiques"
  }'

Gestion des Documents (Admin)

Exemple : Lister tous les documents

curl -X GET "http://API_URL/admin/documents?limit=50&offset=0" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Monitoring Système

Statistiques système

curl -X GET "http://API_URL/admin/monitoring/stats" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Réponse :

{
  "total_documents": 1250,
  "documents_by_status": {
    "completed": 1000,
    "processing": 50,
    "error": 100,
    "waiting": 100
  },
  "documents_by_type": {
    "pdf": 600,
    "docx": 300,
    "audio": 250,
    "video": 100
  },
  "total_users": 150,
  "active_users": 120,
  "admin_users": 5,
  "storage_stats": {
    "total_size_gb": 5.0,
    "average_document_size_mb": 4.3
  }
}

État de la file de traitement

curl -X GET "http://API_URL/admin/monitoring/queue" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Réponse :

{
  "queue_length": 5,
  "active_operations": [
    {
      "operation_id": "op-123",
      "document_id": "doc-456",
      "type": "audio_transcription",
      "started_at": "2025-01-22T10:00:00Z",
      "elapsed_seconds": 120
    }
  ],
  "stuck_operations": []
}

Nettoyer les opérations bloquées

# Nettoyer toutes les opérations dépassant le timeout
curl -X POST "http://API_URL/admin/monitoring/queue/clear-stuck" \
  -H "Authorization: Bearer ADMIN_TOKEN"

# Nettoyer une opération spécifique
curl -X POST "http://API_URL/admin/monitoring/queue/clear-stuck?operation_id=OP_ID" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Nettoyage des Orphelins

Identifier les fichiers orphelins

curl -X GET "http://API_URL/admin/cleanup/orphans" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Activité récente

curl -X GET "http://API_URL/admin/monitoring/activity?limit=20" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Réponse :

{
  "activities": [
    {
      "timestamp": "2025-01-22T10:30:00Z",
      "user_id": "uuid-user",
      "action": "document_upload",
      "document_id": "doc-123",
      "details": {"filename": "rapport.pdf", "size_mb": 2.5}
    }
  ]
}

Erreurs récentes

curl -X GET "http://API_URL/admin/monitoring/errors?limit=10" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Réponse :

{
  "errors": [
    {
      "timestamp": "2025-01-22T09:15:00Z",
      "error_type": "processing_error",
      "document_id": "doc-456",
      "message": "Failed to extract topics",
      "traceback": "..."
    }
  ]
}

Bonnes Pratiques Admin

1. Monitoring régulier - Vérifiez /admin/monitoring/stats quotidiennement
2. Queue bloquée - Si la queue ne progresse pas, utilisez clear-stuck
3. Nettoyage - Lancez /admin/cleanup/orphans périodiquement
4. Utilisateurs - Désactivez plutôt que supprimer pour conserver l'historique

Swagger Admin

Explorer les routes Admin dans Swagger

Dépannage

Guide de résolution des problèmes courants.

Erreurs d'Authentification

401 Unauthorized

Message : "detail": "Could not validate credentials"

Causes possibles : - Token JWT expiré (durée de vie : 24h) - Token malformé ou invalide - Header Authorization absent

Solutions :

# Vérifier le format du header
Authorization: Bearer VOTRE_TOKEN  # Correct
Authorization: VOTRE_TOKEN         # Incorrect

# Obtenir un nouveau token
curl -X POST "http://API_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

403 Forbidden

Message : "detail": "Not enough permissions"

Causes : - Tentative d'accès à une route admin sans droits admin - Tentative d'accès à un document d'un autre utilisateur

Solution : - Vérifiez vos droits avec /auth/me - Contactez un administrateur si nécessaire

Erreurs d'Upload

413 Request Entity Too Large

Message : "detail": "File too large"

Limite : 1 GB maximum par fichier

Solutions : - Compressez le fichier avant upload - Pour les vidéos, réduisez la résolution/bitrate - Divisez en plusieurs fichiers si possible

400 Bad Request - Format non supporté

Message : "detail": "Unsupported file format"

Formats supportés :

Erreurs de Traitement

Document reste en "processing"

Symptômes : Le statut ne passe jamais à "completed"

Vérification :

curl -X GET "http://API_URL/document/status/DOC_ID" \
  -H "Authorization: Bearer TOKEN"

Causes possibles : 1. Fichier corrompu ou vide 2. File de traitement bloquée 3. Erreur interne du service

Solutions : 1. Vérifiez les détails d'erreur dans la réponse status 2. Pour les admins : vérifiez /admin/monitoring/queue 3. Réessayez l'upload avec un autre fichier

Extraction de thèmes échoue

Message : "detail": "Topic extraction failed"

Causes : - Document avec trop peu de contenu textuel - Document dans une langue non supportée - Timeout sur gros documents

Solutions :

# Vérifier d'abord que le document a du contenu
curl -X GET "http://API_URL/document/converted/DOC_ID" \
  -H "Authorization: Bearer TOKEN"

# Si vide, le problème est dans la conversion, pas l'extraction

Rapport ne se génère pas

Prérequis pour générer un rapport : 1. Document converti en markdown 2. Thèmes extraits

Vérification :

# Statut complet
curl -X GET "http://API_URL/document/status/DOC_ID" \
  -H "Authorization: Bearer TOKEN"

# Doit montrer :
# - markdown_conversion: completed
# - topic_extraction: completed

Codes d'Erreur HTTP

Problèmes de Recherche RAPTOR

Index non créé

Message : "detail": "RAPTOR index not found"

Solution :

# Créer l'index manuellement
curl -X POST "http://API_URL/raptor/create_index/DOC_ID" \
  -H "Authorization: Bearer TOKEN"

Résultats de recherche vides

Causes : - Document sans contenu suffisant - Index corrompu - Requête trop spécifique

Solutions : 1. Reformulez la question plus généralement 2. Vérifiez que le document contient l'information recherchée 3. Recréez l'index avec force_rebuild=true

Problèmes de Services ML

TTS ne fonctionne pas

Message : "detail": "TTS service unavailable"

Vérification :

curl -X GET "http://API_URL/health/system" \
  -H "Authorization: Bearer TOKEN"

Si le service TTS est down : Contactez l'administrateur

OCR renvoie du texte incorrect

Causes : - Image de mauvaise qualité - Langue mal détectée - PDF scanné avec artefacts

Solutions :

# Spécifier la langue explicitement
curl -X POST "http://API_URL/ocr/extract" \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@image.png" \
  -F "language=fr"

Traduction incohérente

Solutions : - Spécifiez la langue source au lieu de auto - Divisez les textes longs en segments plus courts - Vérifiez que les langues sont supportées avec /translation/languages

Vérification de l'état du système

Health Check

# Basic
curl http://API_URL/health

# Détaillé (authentifié)
curl -X GET "http://API_URL/health/system" \
  -H "Authorization: Bearer TOKEN"

Réponse saine :

{
  "status": "healthy",
  "system": {
    "cpu_percent": 45.0,
    "memory_percent": 62.0,
    "disk_percent": 38.0
  },
  "gpu": {
    "available": true,
    "memory_utilization": 25.0
  }
}

Debug avec les logs

Informations utiles à fournir au support

1. Document ID concerné
2. Timestamp de l'erreur
3. Réponse complète de l'API (code + body)
4. Étapes pour reproduire le problème

Exemple de rapport de bug

Document ID: abc123-456-789
Timestamp: 2025-01-22T10:30:00Z
Action: POST /topics/extract_topics/abc123-456-789
Response Code: 500
Response Body: {"detail": "Internal server error"}

Steps:
1. Uploaded PDF file (rapport.pdf, 5MB)
2. Waited for conversion (completed)
3. Called extract_topics
4. Got error 500

FAQ

Q: Pourquoi mon token expire-t-il si vite ?

R: Les tokens JWT expirent après 24h par sécurité. Utilisez une API Key pour les intégrations longue durée :

curl -X POST "http://API_URL/auth/api-keys" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"name": "Integration"}'

Q: Puis-je traiter plusieurs fichiers simultanément ?

R: Oui, mais respectez les limites de rate limiting (10 uploads/minute). Utilisez le traitement asynchrone (return_id=true) pour les gros fichiers.

Q: Comment savoir si un document est prêt ?

R: Utilisez /document/wait/{id}?timeout=300 pour attendre jusqu'à 5 minutes, ou pollez /document/status/{id}.

Q: Le rapport HTML s'affiche mal

R: Le rapport est conçu pour être consulté dans un navigateur moderne. Si vous le téléchargez, ouvrez-le directement dans Chrome/Firefox.

Prompt pour Agent IA

Ce prompt permet à un agent IA (chatbot, assistant) d'utiliser l'API Synthesia en autonomie.

Prompt à copier

Tu es un assistant pour l'API Synthesia, une plateforme d'analyse de documents avec IA.

### Accès à la Documentation

L'API expose sa documentation complète aux URLs suivantes :

| URL | Format | Description |
|-----|--------|-------------|
| `/` | HTML | Documentation complète avec 12 sections (Introduction, Authentification, Quickstart, Routes, Upload, Services ML, Topics, Swagger, MCP, Admin, Troubleshooting) |
| `/docs` | Swagger UI | Interface interactive pour tester tous les endpoints |
| `/redoc` | ReDoc | Documentation alternative en lecture seule |
| `/openapi.json` | JSON | Spécification OpenAPI complète (schémas, paramètres, réponses) |

### Comment utiliser la documentation

1. **Pour lister tous les endpoints disponibles** : Récupère `/openapi.json` et parse les `paths`
2. **Pour comprendre un endpoint spécifique** : Consulte `/openapi.json` → `paths` → `/{endpoint}` → méthode (get/post/etc.)
3. **Pour voir des exemples d'utilisation** : Récupère `/` et cherche la section correspondante en HTML

### Structure de l'API

L'API est organisée en catégories :

- **Authentification** (`/auth/*`) : Login, tokens JWT, API Keys
- **Documents** (`/document/*`) : Upload, conversion, statut, gestion
- **Topics** (`/topics/*`) : Extraction de thèmes
- **RAPTOR** (`/raptor/*`) : Recherche sémantique
- **Analysis** (`/analysis/*`) : Génération de rapports
- **Services ML** :
  - `/ocr/*` : OCR (extraction texte depuis images)
  - `/vlm/*` : Vision-Language (description images, Q&A)
  - `/tts/*` : Text-to-Speech (synthèse vocale)
  - `/translation/*` : Traduction (55 langues)
  - `/ner/*` : Entités nommées, anonymisation
  - `/embed/*` : Embeddings vectoriels
  - `/graph/*` : Graphes de connaissances
  - `/diarization/*` : Identification des locuteurs
- **Admin** (`/admin/*`) : Gestion utilisateurs, monitoring (admin requis)
- **Health** (`/health`, `/health/system`) : Statut du service

### Authentification requise

Tous les endpoints (sauf `/health` et `/`) nécessitent une authentification :

Authorization: Bearer

ou

X-API-Key: sk_synthesia_

Pour obtenir un token :

POST /auth/login Content-Type: application/json {"username": "...", "password": "..."}

### Ton rôle

Quand l'utilisateur demande de l'aide :
1. Identifie le besoin (upload, analyse, recherche, service ML, etc.)
2. Si nécessaire, récupère la documentation pertinente depuis `/openapi.json`
3. Propose les endpoints adaptés avec leurs paramètres
4. Fournis des exemples de requêtes cURL ou code

### Exemples de questions utilisateur

- "Comment uploader un document ?" → `/document/upload` ou `/document/convert/from_file`
- "Comment faire de l'OCR ?" → `/ocr/extract` ou `/vlm/ocr`
- "Comment générer un rapport ?" → `/analysis/get_report/{id}` ou `/analysis/get_report_from_any_file`
- "Quels services sont disponibles ?" → Liste les catégories ci-dessus

Utilisation

Copiez le prompt ci-dessus et fournissez-le comme instruction système à votre agent IA (Claude, GPT, etc.) avec l'URL de base de l'API.

L'agent pourra alors : - Récupérer la documentation depuis /openapi.json - Guider les utilisateurs vers les bons endpoints - Fournir des exemples de code adaptés