Référence API

Base URL : https://api.afrivoice.xelsoftai.com/v1

Toutes les requêtes doivent inclure le header X-API-Key: av_xxx. Les réponses sont au format JSON.

Authentification

Toutes les routes /v1/* nécessitent un header X-API-Key contenant votre clé API. Les clés sont générées depuis votre tableau de bord et stockées uniquement en SHA-256 côté serveur.

# Header requis sur chaque requête
X-API-Key: av_votre_clé_api_complète

⚠️ Ne jamais exposer votre clé API dans du code frontend public. Utilisez des variables d'environnement côté serveur.

POST

/v1/transcribe

Transcrit un fichier audio uploadé en multipart/form-data. Formats acceptés : WAV, MP3, M4A, OGG. Taille maximale : 25 MB (Free) / 100 MB (Pro).

Paramètres (form-data)

Nom	Type	Description
`file`requis	`File`	Fichier audio à transcrire (WAV, MP3, M4A, OGG)
`language`	`string`	Code langue source (ex: 'wo'). Détection auto si absent.

Exemple cURL

curl -X POST https://api.afrivoice.xelsoftai.com/v1/transcribe \
  -H "X-API-Key: av_votre_clé" \
  -F "file=@audio.wav"

Réponse 200

{
  "success": true,
  "data": {
    "request_id": "req_01j9abc123",
    "text": "Maangi dem ci ndéy bi. Il faut partir maintenant.",
    "duration_s": 4.2,
    "inference_time_s": 1.8,
    "rtf": 0.43,
    "model": "whisper-wolof-v1",
    "status": "success",
    "cs_languages": ["wo", "fr"],
    "cs_wolof_ratio": 0.72,
    "cs_french_ratio": 0.28,
    "cs_arabic_ratio": 0.0,
    "cs_english_ratio": 0.0,
    "cs_total_words": 11,
    "segments": [
      { "start_s": 0.0, "end_s": 2.1, "text": "Maangi dem ci ndéy bi." },
      { "start_s": 2.1, "end_s": 4.2, "text": "Il faut partir maintenant." }
    ]
  }
}

POST

/v1/transcribe-url

Transcrit un fichier audio ou une vidéo YouTube à partir de son URL. Corps JSON avec Content-Type: application/json.

Corps JSON

Nom	Type	Description
`url`requis	`string`	URL du fichier audio ou vidéo YouTube
`language`	`string`	Code langue source (optionnel)
`title`	`string`	Titre de la source (pour l'historique)

Exemple

curl -X POST https://api.afrivoice.xelsoftai.com/v1/transcribe-url \
  -H "X-API-Key: av_votre_clé" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://youtube.com/watch?v=xxx", "title": "Interview Wolof" }'

GET

/v1/usage

Retourne les compteurs d'utilisation du jour en cours pour la clé API utilisée.

Réponse 200

{
  "success": true,
  "data": {
    "date": "2025-05-24",
    "requests": 47,
    "audio_seconds": 1842.5,
    "daily_limit_requests": 100,
    "daily_limit_seconds": 600,
    "tier": "free"
  }
}

Codes d'erreur

Code	Statut	Description
`401`	Unauthorized	Clé API manquante ou invalide
`403`	Forbidden	Clé API révoquée ou inactive
`413`	Payload Too Large	Fichier trop volumineux pour votre plan
`422`	Unprocessable Entity	Format audio non supporté
`429`	Too Many Requests	Quota quotidien dépassé
`500`	Internal Server Error	Erreur interne du service de transcription

Webhooks Stripe

AfriVoice utilise Stripe Webhooks pour les événements de facturation. Configurez votre endpoint dans le dashboard Stripe et vérifiez la signature avec stripe.webhooks.constructEvent().

Événements gérés

customer.subscription.createdNouveau abonnement Pro/Enterprise

customer.subscription.updatedChangement de plan

customer.subscription.deletedAnnulation — retour en Free

invoice.payment_succeededFacture payée — enregistrement dans la DB

Getting Started Changelog →