API_DOCUMENTATION.md

# 🔌 API REST - Analyse de Sentiment Audio

## 📋 Vue d'ensemble

L'API REST permet d'intégrer l'analyse de sentiment audio dans vos applications. Elle est accessible via les endpoints suivants :

**Base URL** : `https://huggingface.co/spaces/<username>/sentiment-audio-analyzer`

## 🚀 Endpoints disponibles

### 1. **GET /** - Informations générales
```bash
curl https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/
```

**Réponse :**
```json
{
  "message": "API Multimodale de Transcription & Sentiment",
  "version": "1.0",
  "endpoints": {
    "docs": "/api/docs",
    "predict": "/api/predict",
    "health": "/api/health"
  },
  "supported_formats": ["wav", "flac", "mp3"]
}
```

### 2. **GET /api/health** - Vérification de l'état
```bash
curl https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/health
```

**Réponse :**
```json
{
  "status": "healthy",
  "models_loaded": true,
  "timestamp": "2024-01-01T00:00:00Z"
}
```

### 3. **POST /api/predict** - Analyse audio
```bash
curl -X POST "https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/predict" \
     -F "file=@audio.wav"
```

**Paramètres :**
- `file` : Fichier audio (WAV, FLAC, MP3, max 50MB)

**Réponse :**
```json
{
  "transcription": "je suis très content de ce produit",
  "sentiment": {
    "négatif": 0.05,
    "neutre": 0.10,
    "positif": 0.85
  },
  "filename": "audio.wav",
  "file_size": 123456
}
```

### 4. **POST /api/predict_text** - Analyse textuelle
```bash
curl -X POST "https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/predict_text" \
     -H "Content-Type: application/json" \
     -d '{"text": "je suis très content de ce produit"}'
```

**Paramètres :**
- `text` : Texte à analyser (string)

**Réponse :**
```json
{
  "text": "je suis très content de ce produit",
  "sentiment": {
    "négatif": 0.05,
    "neutre": 0.10,
    "positif": 0.85
  }
}
```

## 📖 Exemples d'utilisation

### Python avec requests
```python
import requests

# Analyse audio
url = "https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/predict"
files = {"file": open("audio.wav", "rb")}
response = requests.post(url, files=files)
result = response.json()
print(f"Transcription: {result['transcription']}")
print(f"Sentiment: {result['sentiment']}")

# Analyse textuelle
url = "https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/predict_text"
data = {"text": "je suis très content de ce produit"}
response = requests.post(url, json=data)
result = response.json()
print(f"Sentiment: {result['sentiment']}")
```

### JavaScript avec fetch
```javascript
// Analyse audio
const formData = new FormData();
formData.append('file', audioFile);

fetch('https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/predict', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log('Transcription:', data.transcription);
  console.log('Sentiment:', data.sentiment);
});

// Analyse textuelle
fetch('https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/predict_text', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'je suis très content de ce produit'
  })
})
.then(response => response.json())
.then(data => {
  console.log('Sentiment:', data.sentiment);
});
```

### Node.js avec axios
```javascript
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

// Analyse audio
const formData = new FormData();
formData.append('file', fs.createReadStream('audio.wav'));

axios.post('https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/predict', formData, {
  headers: formData.getHeaders()
})
.then(response => {
  console.log('Transcription:', response.data.transcription);
  console.log('Sentiment:', response.data.sentiment);
});

// Analyse textuelle
axios.post('https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/predict_text', {
  text: 'je suis très content de ce produit'
})
.then(response => {
  console.log('Sentiment:', response.data.sentiment);
});
```

## ⚠️ Gestion des erreurs

### Erreur 400 - Fichier invalide
```json
{
  "detail": "Seuls les fichiers audio WAV/FLAC/MP3 sont acceptés."
}
```

### Erreur 400 - Fichier trop volumineux
```json
{
  "detail": "Fichier trop volumineux. Taille maximale: 50MB"
}
```

### Erreur 500 - Erreur serveur
```json
{
  "detail": "Erreur lors de l'analyse: [description de l'erreur]"
}
```

## 🔧 Configuration

### Headers recommandés
```bash
Content-Type: multipart/form-data  # Pour /api/predict
Content-Type: application/json     # Pour /api/predict_text
```

### Limites
- **Taille fichier** : 50MB maximum
- **Formats supportés** : WAV, FLAC, MP3
- **Langue** : Français (optimisé)
- **Rate limiting** : Selon les limites HF Spaces

## 📊 Codes de réponse

| Code | Description |
|------|-------------|
| 200 | Succès |
| 400 | Erreur de requête (fichier invalide, trop volumineux) |
| 500 | Erreur serveur (modèles, traitement) |

## 🎯 Cas d'usage

### 1. **Intégration chatbot**
```python
def analyze_user_audio(audio_file):
    response = requests.post(API_URL, files={"file": audio_file})
    result = response.json()
    
    if result["sentiment"]["positif"] > 0.7:
        return "Je suis ravi que vous soyez satisfait !"
    elif result["sentiment"]["négatif"] > 0.7:
        return "Je comprends votre préoccupation. Comment puis-je vous aider ?"
    else:
        return "Merci pour votre retour."
```

### 2. **Analyse de feedback clients**
```python
def analyze_customer_feedback(audio_files):
    results = []
    for audio in audio_files:
        response = requests.post(API_URL, files={"file": audio})
        results.append(response.json())
    
    # Statistiques
    positive_count = sum(1 for r in results if r["sentiment"]["positif"] > 0.5)
    return f"Taux de satisfaction: {positive_count/len(results)*100:.1f}%"
```

### 3. **Monitoring en temps réel**
```python
import time

def monitor_audio_stream():
    while True:
        # Capture audio
        audio_data = capture_audio()
        
        # Analyse
        response = requests.post(API_URL, files={"file": audio_data})
        result = response.json()
        
        # Alerte si sentiment négatif
        if result["sentiment"]["négatif"] > 0.8:
            send_alert("Sentiment très négatif détecté")
        
        time.sleep(30)  # Analyse toutes les 30 secondes
```

## 🔗 Documentation interactive

Accédez à la documentation interactive Swagger UI :
```
https://huggingface.co/spaces/<username>/sentiment-audio-analyzer/api/docs
```

## 📞 Support

Pour toute question ou problème :
1. Consultez les logs dans l'interface HF Spaces
2. Vérifiez la documentation Swagger
3. Testez avec l'interface Gradio

---

*API développée avec FastAPI et optimisée pour Hugging Face Spaces*