Documentation non disponible pour la section Introduction

Documentation non disponible pour la section Installation et Démarrage

Documentation non disponible pour la section Points d'Entrée de l'API

Documentation non disponible pour la section API de Téléchargement de Fichiers

Documentation non disponible pour la section 🎯 Extraction de Thèmes - Exemples

Documentation non disponible pour la section Utilisation de l'Interface Swagger

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

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

Documentation non disponible pour la section Génération de Détails Thématiques

Dépannage

Problèmes Courants et Solutions

L'API ne Démarre Pas

• Vérifier l'environnement virtuel: Assurez-vous d'avoir activé l'environnement virtuel
• Vérifier la disponibilité du port: Assurez-vous que le port 8050 n'est pas utilisé par un autre processus
• Vérifier les dépendances: Assurez-vous que toutes les dépendances sont installées avec pip install -r requirements.txt
• Vérifier les journaux: Recherchez les messages d'erreur dans la sortie du terminal

Problèmes de Traitement de Documents

• Contenu du document vide: Vérifiez si le document contient du texte extractible
• Délais d'attente de traitement: Pour les grands documents, le traitement peut prendre plus de temps
• L'extraction de thèmes échoue: Assurez-vous que le document a un contenu textuel suffisant
• Problèmes d'indexation RAPTOR: Vérifiez que les thèmes ont été extraits avec succès

Messages d'Erreur Courants

• "Erreur de conversion de fichier": Le format du document peut ne pas être pris en charge ou le fichier est corrompu
• "L'extraction de thèmes a échoué": Le document peut avoir un contenu insuffisant ou un format non reconnu
• "La création de l'index RAPTOR a échoué": Les étapes de traitement précédentes peuvent avoir échoué
• "La génération de rapport a échoué": Les données requises pour le rapport peuvent être manquantes

File de Traitement Bloquée

Symptômes: Les conversions audio/vidéo restent en état "processing" indéfiniment, les nouveaux documents ne se traitent pas.

Causes: - Une opération dans la file d'attente n'a pas libéré son emplacement de traitement - Le processus a échoué sans nettoyer correctement ses ressources - La mémoire GPU est saturée par un modèle Whisper bloqué - Le traitement asynchrone a été interrompu sans libérer les ressources

Solutions:

1. Vérifier l'état de la file d'attente (admin requis): bash curl -H "Authorization: Bearer $TOKEN" http://localhost:8050/admin/monitoring/queue

2. Nettoyer les opérations bloquées (admin requis): ```bash # Nettoyer toutes les opérations ayant dépassé leur timeout curl -X POST -H "Authorization: Bearer $TOKEN" \ http://localhost:8050/admin/monitoring/queue/clear-stuck

# Nettoyer une opération spécifique curl -X POST -H "Authorization: Bearer $TOKEN" \ "http://localhost:8050/admin/monitoring/queue/clear-stuck?operation_id=XXX" ```

1. Redémarrer l'API si nécessaire: ```bash # Trouver le processus API ps aux | grep "uvicorn api_main:app" | grep -v grep

# Tuer le processus (remplacer PID par l'ID réel) kill -9

# L'API devrait redémarrer automatiquement, sinon: cd /data/loic/resume_v2/api_package python start_api.py ```

Prévention: - Les opérations ont maintenant un timeout automatique (60 min pour audio/vidéo, 30 min pour autres) - Surveillez régulièrement la file d'attente via l'endpoint admin - Les opérations bloquées sont automatiquement identifiées dans le monitoring

Problèmes GPU/CPU pour la Transcription Audio

Symptômes: Erreurs de mémoire GPU, transcription lente, échecs de conversion audio.

Causes: - Mémoire GPU insuffisante pour les gros fichiers - Configuration GPU incorrecte - Modèle Whisper ne se charge pas sur le bon périphérique

Solutions:

1. Vérifier la configuration GPU: ```bash # Vérifier que CUDA est disponible nvidia-smi

# Vérifier la configuration dans .env grep WHISPER_DEVICE .env ```

1. Forcer l'utilisation du CPU: bash # Dans .env WHISPER_DEVICE=cpu

2. Ajuster les limites mémoire: bash # Dans .env WHISPER_GPU_MEMORY_LIMIT_GB=8.0 # Augmenté de 4GB à 8GB WHISPER_CPU_THRESHOLD_MB=100.0 # Fichiers < 100MB utilisent le CPU

3. Surveiller l'utilisation GPU: bash # Via l'endpoint health curl http://localhost:8050/health/system | jq .gpu

Prévention: - Utilisez WHISPER_DEVICE=cuda pour de meilleures performances - Les petits fichiers (< 100MB) utilisent automatiquement le CPU - La limite mémoire GPU est maintenant de 8GB par défaut

Surveillance et Journalisation

Fichiers de Journaux

L'API génère des fichiers de journaux détaillés qui peuvent aider à diagnostiquer les problèmes:

• Journaux d'application: Situés dans le dossier logs/
• Journaux de traitement: Inclus dans le dossier du document sous resu/<document_id>/logs/

Vérification de l'État du Système

Pour vérifier l'état actuel du système:

curl http://localhost:8050/health/system

Cette commande renvoie des informations détaillées sur l'utilisation des ressources système.

Tâches de Maintenance Courantes

Nettoyage du Cache

Pour nettoyer les fichiers temporaires et le cache:

./scripts/cleanup.sh

Mise à Jour des Dépendances

Pour mettre à jour les dépendances vers les dernières versions compatibles:

pip install --upgrade -r requirements.txt

Redémarrage Complet

En cas de problèmes persistants, un redémarrage complet peut résoudre de nombreux problèmes:

./stop_api.sh
./start_api.sh

Gestion du Mode Persistant

Si l'API a été démarrée en mode persistant (mode par défaut ou via ./start_api.sh sans options):

• Trouver le processus: bash ps aux | grep uvicorn # ou lsof -ti:8050

• Arrêter le processus: bash kill -9 $(lsof -ti:8050)

• Consulter les journaux du mode persistant: bash ls -lt logs/nohup_api_*.log tail -f logs/nohup_api_TIMESTAMP.log