Documentation API esacode

Explorez notre documentation complète

🌟 Bienvenue dans l'écosystème API esacode 🌟

Intégrez facilement nos services de traduction et détection linguistique dans vos applications. Nos APIs sont conçues pour être simples, fiables et performantes, avec un support étendu pour les langues africaines.

55+ Langues

Support étendu pour les langues africaines et internationales avec une précision exceptionnelle

Yoruba Swahili Haoussa +50

Ultra Rapide

Réponses en moins de 100ms avec une infrastructure cloud optimisée et distribuée

Temps réel

Ultra Sécurisé

Authentification par token Bearer, chiffrement HTTPS et protection avancée des données

Services disponibles

Détection de Langue

Identifiez automatiquement la langue d'un texte avec une précision supérieure à 95%

POST /api/detect
Disponible

Traduction de Texte

Traduisez vos textes entre plus de 55 langues avec une qualité professionnelle

POST /api/translate
Disponible

Authentification requise

Toutes nos APIs nécessitent un token d'authentification Bearer. Obtenez votre token d'accès en souscrivant à l'un de nos plans.

Authorization Header
Authorization: Bearer VOTRE_TOKEN_ICI
Obtenir mon token

Essai gratuit • Pas de carte bancaire

Détection automatique de langue

Identifiez automatiquement la langue d'un texte parmi plus de 55 langues supportées, avec une précision optimisée pour les langues africaines.

🌍
55+ Langues

Support étendu incluant les langues africaines

⚡
Ultra Rapide

Réponses en moins de 100ms

🔒
Sécurisé

Authentification par token Bearer

Informations de l'endpoint
https://www.esacode.org/api/detect/
POST
Headers requis
Content-Type: application/json

Format des données envoyées au serveur

Authorization: Bearer VOTRE_TOKEN

Token d'authentification obtenu lors de l'inscription

Corps de la requête
Exemple de requête (un seul champ requis)
{
  "message": "Hello everyone and welcome to the esacode website."
}

message (string, requis) : Le texte dont vous souhaitez détecter la langue. Maximum 5000 caractères.

Réponse de succès
JSON Response (200 OK)
{
  "status": "success",
  "language": "en",
  "language_name": "English",
  "confidence": 0.99,
  "characters_used": 56,
  "characters_remaining": 9944
}

status : Statut de la requête (success/error)

language : Code ISO 639-1 de la langue détectée

language_name : Nom complet de la langue en anglais

confidence : Niveau de confiance de la détection (0-1)

characters_used/remaining : Gestion de votre quota de caractères

Exemples de code
JavaScript (Fetch API)
const response = await fetch('https://www.esacode.org/api/detect/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer VOTRE_TOKEN'
  },
  body: JSON.stringify({
    message: 'Hello everyone and welcome to the esacode website.'
  })
});

const data = await response.json();
console.log('Langue détectée:', data.language_name);
Python (Requests)
import requests

url = 'https://www.esacode.org/api/detect/'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer VOTRE_TOKEN'
}
data = {
    'message': 'Hello everyone and welcome to the esacode website.'
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

print(f"Langue détectée: {result['language_name']}")
print(f"Confiance: {result['confidence']:.2%}")
cURL (Terminal)
curl -X POST https://www.esacode.org/api/detect/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -d '{
    "message": "Hello everyone and welcome to the esacode website."
  }'
Gestion des erreurs
401 Token invalide ou manquant

Vérifiez que votre token Bearer est correct et actif.

429 Quota de caractères dépassé

Vous avez atteint votre limite mensuelle de caractères.

400 Données manquantes ou invalides

Le champ 'message' est requis et ne peut pas être vide.

Traduction multilingue avancée

Traduisez vos textes entre plus de 55 langues avec une qualité professionnelle. Notre API supporte particulièrement bien les langues africaines et propose une détection automatique de la langue source.

🌐
55+ Langues

Support étendu incluant les langues africaines

🤖
Auto-détection

Détection automatique de la langue source

⭐
Haute Qualité

Traductions précises et naturelles

Informations de l'endpoint
https://www.esacode.org/api/translate/
POST
Headers requis
Content-Type: application/json

Format des données envoyées au serveur

Authorization: Bearer VOTRE_TOKEN

Token d'authentification obtenu lors de l'inscription

Corps de la requête
Exemple minimal (les 2 champs requis)
{
  "message": "Before translating, please select a language.",
  "target_language": "fr"
}
Exemple complet (tous les paramètres)
{
  "message": "Before translating, please select a language.",
  "target_language": "fon",
  "source_language": "en"
}

Sans source_language (ou avec "auto"), la langue source est détectée automatiquement.

message (string, requis) : Le texte à traduire. Maximum 5000 caractères.

target_language (string, requis) : Code ISO de la langue cible (ex: "fr", "es", "de").

source_language (string, optionnel) : Code ISO de la langue source ou "auto" pour détection automatique.

Réponse de succès
JSON Response (200 OK)
{
  "status": "success",
  "source_language": "en",
  "source_language_name": "English",
  "target_language": "fr",
  "target_language_name": "French",
  "translated_text": "Avant de traduire, veuillez sélectionner une langue.",
  "original_text": "Before translating, please select a language.",
  "characters_used": 44,
  "characters_remaining": 9956
}

status : Statut de la requête (success/error)

source_language : Code ISO de la langue source détectée

target_language : Code ISO de la langue cible demandée

translated_text : Le texte traduit dans la langue cible

characters_used/remaining : Gestion de votre quota de caractères

Exemples de code
JavaScript (Fetch API)
const response = await fetch('https://www.esacode.org/api/translate/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer VOTRE_TOKEN'
  },
  body: JSON.stringify({
    message: 'Hello, how are you today?',
    target_language: 'fr',
    source_language: 'auto'
  })
});

const data = await response.json();
console.log('Traduction:', data.translated_text);
console.log('De:', data.source_language_name, '→ Vers:', data.target_language_name);
Python (Requests)
import requests

url = 'https://www.esacode.org/api/translate/'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer VOTRE_TOKEN'
}
data = {
    'message': 'Hello, how are you today?',
    'target_language': 'fr',
    'source_language': 'auto'
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

print(f"Traduction: {result['translated_text']}")
print(f"De: {result['source_language_name']} → Vers: {result['target_language_name']}")
print(f"Caractères utilisés: {result['characters_used']}")
PHP (cURL)
 'Hello, how are you today?',
    'target_language' => 'fr',
    'source_language' => 'auto'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo "Traduction: " . $result['translated_text'];
?>
Gestion des erreurs
401 Token invalide ou manquant

Vérifiez que votre token Bearer est correct et actif.

429 Quota de caractères dépassé

Vous avez atteint votre limite mensuelle de caractères.

422 Langue non supportée

Le code de langue fourni n'est pas supporté par l'API.

400 Données manquantes ou invalides

Les champs 'message' et 'target_language' sont requis.

Donnez une voix à vos textes

Convertissez n'importe quel texte en audio avec des voix neuronales de qualité premium. Et avec Traduire & Écouter, envoyez un texte en français : il est traduit puis lu à voix haute dans la langue de votre audience, en un seul appel.

🎙️
Voix neuronales

Français, anglais, espagnol, arabe, swahili, amharique, zoulou…

🌍
Langues africaines

Éwé, lingala, yoruba, haoussa, bambara… en version bêta (en optimisation)

🔊
Traduire & Écouter

Traduction + audio en un seul appel API

Quel endpoint choisir ?

/api/tts/ : lit votre texte tel quel, sans le traduire. Envoyez un texte déjà écrit dans la langue de la voix : texte français + voix française, texte fon + voix fon.

/api/translate-speak/ : traduit d'abord, puis lit le texte traduit. Envoyez votre texte en français avec target_language : c'est le bon choix pour les langues africaines.

Piège classique : envoyer un texte français à /api/tts/ avec "language": "ee" ne le traduit pas — la voix éwé lira le français mot à mot. Pour « écris en français, écoute en éwé », utilisez /api/translate-speak/.

Endpoint 1 : Synthèse vocale directe, le texte est lu tel quel
https://www.esacode.org/api/tts/
POST
Content-Type: application/json
Authorization: Bearer VOTRE_TOKEN
Corps de la requête
Exemple minimal (les 2 champs essentiels)
{
  "message": "Bienvenue chez esacode, votre partenaire vocal.",
  "language": "fr"
}
Exemple complet (tous les paramètres)
{
  "message": "Bienvenue chez esacode, votre partenaire vocal.",
  "voice": "fr-esacode",
  "rate": "+10%",
  "audio_base64": true,
  "name": "Message d'accueil"
}

Quand voice est fourni, language devient inutile : la voix porte déjà sa langue. Utilisez l'un OU l'autre.

message (string, requis) : Le texte à synthétiser. Maximum 5000 caractères.

language (string, requis*) : Code de la langue (ex : "fr", "en", "sw", "ee", "ln"). Un nom de voix esacode y est aussi accepté : "fon-esacode" vaut "fon". *Optionnel si voice est fourni.

voice (string, optionnel) : Nom d'une voix esacode au format <langue>-esacode (ex : "fr-esacode", "fon-esacode"). Catalogue complet via GET /api/tts/voices/.

rate (string, optionnel) : Vitesse de lecture, de "-50%" à "+100%".

audio_base64 (booléen, optionnel) : Si true, la réponse inclut aussi le champ audio_base64 (fichier encodé, +33% de taille).

name (string, optionnel) : Nom du projet affiché dans votre dashboard.

Réponse de succès
JSON Response (200 OK)
{
  "status": "success",
  "project_id": 42,
  "audio_url": "https://www.esacode.org/api/tts/audio/42/",
  "voice": "fr-esacode",
  "format": "mp3",
  "characters_used": 48,
  "characters_remaining": 9952
}

audio_url est protégée : envoyez le même header Authorization: Bearer VOTRE_TOKEN pour télécharger le fichier : vos audios ne sont accessibles qu'à vous. Format mp3 pour les voix premium, wav pour les voix africaines en bêta. Besoin de l'audio directement dans la réponse ? Ajoutez "audio_base64": true à votre requête.

Endpoint 2 : Traduire & Écouter, traduit d'abord puis lit POST

Le flux signature d'esacode : votre texte est traduit vers la langue cible puis lu à voix haute, en un seul appel, une seule déduction de quota. Mêmes options que le TTS direct : rate, audio_base64, name ; source_language vaut "auto" par défaut (détection automatique).

Une règle, partout la même : un nom publié par GET /api/tts/voices/ est compris partout où l'on nomme une langue ou une voix. "target_language": "fon-esacode" et "target_language": "fon" désignent la même chose, et voice seul suffit à choisir la langue cible.

https://www.esacode.org/api/translate-speak/
JSON Request Body
{
  "message": "Bonjour mon ami, comment vas-tu aujourd'hui ?",
  "target_language": "ee",
  "source_language": "fr",
  "rate": "+5%",
  "audio_base64": false,
  "name": "Salutation en éwé"
}
JSON Response (200 OK)
{
  "status": "success",
  "project_id": 43,
  "translated_text": "Mido gbe na xɔ̃nye, aleke nèle egbea ?",
  "audio_url": "https://www.esacode.org/api/tts/audio/43/",
  "voice": "ee-esacode",
  "format": "wav",
  "characters_used": 46,
  "characters_remaining": 9906,
  "warning": {
    "code": "AFRICAN_VOICE_BETA",
    "language": "ee",
    "title": "Voix ewe en version bêta",
    "message": "La voix ewe est en cours d'amélioration. Écrivez en français, le texte est traduit puis lu. Les autres langues sont en qualité premium."
  }
}
Catalogue des voix

GET /api/tts/voices/ renvoie la liste des voix disponibles. Chaque langue a sa voix esacode, et le champ quality en indique la nature : neuronale (voix de synthèse moderne), studio (construite sur des enregistrements en studio) ou communautaire (issue de corpus ouverts, en cours d'amélioration). Cet endpoint est limité à 30 appels par minute et par adresse ; le catalogue bouge rarement, gardez-le en cache de votre côté.

JSON Response (extrait)
{
  "status": "success",
  "voices": [
    { "language": "fr",  "voice": "fr-esacode",  "quality": "neuronale" },
    { "language": "sw",  "voice": "sw-esacode",  "quality": "neuronale" },
    { "language": "ee",  "voice": "ee-esacode",  "quality": "studio" },
    { "language": "ha",  "voice": "ha-esacode",  "quality": "studio" },
    { "language": "bm",  "voice": "bm-esacode",  "quality": "communautaire" }
  ]
}
Voix africaines en version bêta

Les voix éwé (ee), lingala (ln), yoruba (yo) et haoussa (ha) sont entraînées sur des enregistrements studio ; le bambara, le dioula et les autres langues africaines du catalogue sont en qualité standard, en cours d'optimisation. Les autres langues bénéficient de voix neuronales premium.

Pour ces langues, la réponse (succès) contient en plus un objet warning que vous pouvez afficher à vos utilisateurs :

"warning": {
  "code": "AFRICAN_VOICE_BETA",
  "language": "bm",
  "title": "Voix bambara en version bêta",
  "message": "La voix bambara est en cours d'amélioration. Écrivez en français, le texte est traduit puis lu. Les autres langues sont en qualité premium."
}
Erreurs spécifiques au TTS

VOICE_UNAVAILABLE (HTTP 400) : la langue demandée n'a pas encore de voix au catalogue. Consultez GET /api/tts/voices/ pour la liste à jour.

TTS_UNAVAILABLE (HTTP 503) : le service de synthèse est momentanément indisponible, réessayez plus tard. Prévoyez un timeout large (jusqu'à 120 s) : le premier appel dans une langue africaine peut être plus lent, le temps de préparer la voix.

Exemples d'intégration
Python
import requests

response = requests.post(
    "https://www.esacode.org/api/translate-speak/",
    headers={"Authorization": "Bearer VOTRE_TOKEN"},
    json={
        "message": "Bienvenue dans notre application !",
        "target_language": "ln",
        "source_language": "fr",
    },
)
data = response.json()
print(data["translated_text"])

audio = requests.get(
    data["audio_url"],
    headers={"Authorization": "Bearer VOTRE_TOKEN"},
)
with open("bienvenue_lingala.wav", "wb") as f:
    f.write(audio.content)
JavaScript
const response = await fetch("https://www.esacode.org/api/tts/", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer VOTRE_TOKEN",
    },
    body: JSON.stringify({
        message: "Bienvenue chez esacode !",
        language: "fr",
    }),
});
const data = await response.json();

const audioResp = await fetch(data.audio_url, {
    headers: { "Authorization": "Bearer VOTRE_TOKEN" },
});
const blob = await audioResp.blob();
new Audio(URL.createObjectURL(blob)).play();
Support multilingue étendu

Notre API supporte plus de 55 langues, avec un focus particulier sur les langues africaines. Utilisez les codes ISO 639-1 pour spécifier les langues dans vos requêtes.

🌍
Langues Internationales

Français, Anglais, Espagnol, Allemand, etc.

🏺
Langues Africaines

Yoruba, Swahili, Haoussa, Amharique, etc.

Langues Internationales
en - English (Anglais)
fr - Français (French)
es - Español (Spanish)
de - Deutsch (German)
it - Italiano (Italian)
pt - Português (Portuguese)
ru - Русский (Russian)
zh - 中文 (Chinese)
ja - 日本語 (Japanese)
ko - 한국어 (Korean)
ar - العربية (Arabic)
hi - हिन्दी (Hindi)
th - ไทย (Thai)
vi - Tiếng Việt (Vietnamese)
nl - Nederlands (Dutch)
sv - Svenska (Swedish)
no - Norsk (Norwegian)
da - Dansk (Danish)
fi - Suomi (Finnish)
pl - Polski (Polish)
tr - Türkçe (Turkish)
he - עברית (Hebrew)
fa - فارسی (Persian)
ur - اردو (Urdu)
Langues Africaines (Spécialité esacode)

Spécialité esacode : Nous offrons un support optimisé pour les langues africaines avec une précision élevée.

Afrique de l'Ouest
yo - Yoruba (Nigeria, Bénin)
ha - Haoussa (Nigeria, Niger)
ig - Igbo (Nigeria)
wo - Wolof (Sénégal)
fon - Fon (Bénin)
bm - Bambara (Mali)
dyu - Dioula (Côte d'Ivoire)
bci - Baoulé (Côte d'Ivoire)
ee - Ewe (Togo, Ghana)
Afrique de l'Est
sw - Swahili (Kenya, Tanzanie)
am - Amharique (Éthiopie)
om - Oromo (Éthiopie)
ti - Tigrigna (Érythrée)
rw - Kinyarwanda (Rwanda)
run - Kirundi (Burundi)
lg - Luganda (Ouganda)
so - Somali (Somalie)
Afrique Centrale & Australe
ln - Lingala (RDC, Congo)
kg - Kikongo (RDC, Angola)
sg - Sango (Centrafrique)
zu - Zoulou (Afrique du Sud)
xh - Xhosa (Afrique du Sud)
af - Afrikaans (Afrique du Sud)
sn - Shona (Zimbabwe)
ny - Chichewa (Malawi)
Exemple d'utilisation des codes de langues
Exemples de Traduction
// Traduction Français → Yoruba
{
  "message": "Bonjour, comment allez-vous ?",
  "target_language": "yo",
  "source_language": "fr"
}

// Traduction automatique → Swahili
{
  "message": "Hello, how are you?",
  "target_language": "sw",
  "source_language": "auto"
}

// Détection de langue pour un texte en Haoussa
{
  "message": "Sannu, yaya kake?"
}
Notes importantes
Détection automatique :

Utilisez "source_language": "auto" pour laisser l'API détecter automatiquement la langue source.

Précision optimisée :

Notre algorithme est spécialement optimisé pour les langues africaines, offrant une précision supérieure à 95% pour ces langues.

Mises à jour régulières :

Nous ajoutons régulièrement de nouvelles langues à notre API. Consultez cette documentation pour les dernières mises à jour.

Codes d'erreur et résolution

Notre API utilise des codes d'erreur HTTP standard avec des messages détaillés pour vous aider à diagnostiquer et résoudre rapidement les problèmes. Voici la liste complète des erreurs possibles.

Erreurs d'authentification
401
Token manquant ou invalide
{
  "status": "error",
  "error_code": "INVALID_TOKEN",
  "message": "Token d'authentification manquant ou invalide",
  "details": "Vérifiez que votre header Authorization contient 'Bearer VOTRE_TOKEN'"
}

Causes possibles :

  • • Header Authorization manquant
  • • Token expiré ou révoqué
  • • Format incorrect (doit être "Bearer TOKEN")
  • • Caractères spéciaux dans le token

Solution : Vérifiez votre token dans votre tableau de bord et regenerez-le si nécessaire.

403
Accès refusé
{
  "status": "error",
  "error_code": "ACCESS_DENIED",
  "message": "Votre abonnement ne permet pas l'accès à cette API",
  "details": "Upgradez votre plan pour accéder à cette fonctionnalité"
}

Solution : Vérifiez votre plan d'abonnement et mettez-le à niveau si nécessaire.

Erreurs de quota et limites
429
Quota de caractères dépassé
{
  "status": "error",
  "error_code": "QUOTA_EXCEEDED",
  "message": "Quota mensuel de caractères dépassé",
  "details": {
    "characters_used": 10000,
    "characters_limit": 10000,
    "reset_date": "2025-02-01T00:00:00Z"
  }
}

Solution : Attendez le renouvellement mensuel ou upgradez votre plan.

429
Limite de taux dépassée
{
  "status": "error",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "message": "Trop de requêtes par minute",
  "details": {
    "limit": 60,
    "current": 62,
    "retry_after": 45
  }
}

Solution : Attendez 45 secondes avant de refaire une requête ou implémentez un système de retry.

Erreurs de validation des données
400
Données manquantes ou invalides
{
  "status": "error",
  "error_code": "VALIDATION_ERROR",
  "message": "Données requises manquantes",
  "details": {
    "missing_fields": ["message"],
    "invalid_fields": {
      "target_language": "Code de langue invalide 'xyz'"
    }
  }
}

Validations :

  • • message : requis, 1-5000 caractères
  • • target_language : code ISO valide (ex: "fr", "en")
  • • source_language : code ISO valide ou "auto"
422
Langue non supportée
{
  "status": "error",
  "error_code": "UNSUPPORTED_LANGUAGE",
  "message": "Langue non supportée",
  "details": {
    "requested_language": "xyz",
    "supported_languages": ["en", "fr", "es", "yo", "sw", "..."]
  }
}

Solution : Consultez la liste des langues supportées dans cette documentation.

Erreurs serveur
500
Erreur interne du serveur
{
  "status": "error",
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Une erreur interne s'est produite",
  "details": {
    "request_id": "req_12345",
    "timestamp": "2025-01-03T10:30:00Z"
  }
}

Solution : Réessayez dans quelques minutes. Si le problème persiste, contactez le support avec le request_id.

503
Service temporairement indisponible
{
  "status": "error",
  "error_code": "SERVICE_UNAVAILABLE",
  "message": "Service temporairement indisponible",
  "details": {
    "retry_after": 300,
    "maintenance": false
  }
}

Solution : Attendez 5 minutes et réessayez. Vérifiez notre page de statut.

Bonnes pratiques pour la gestion d'erreurs
Implémentez un système de retry :

Pour les erreurs 429 et 503, attendez le délai indiqué dans `retry_after` avant de refaire la requête.

Surveillez votre quota :

Chaque réponse réussie contient `characters_used` et `characters_remaining` pour vous aider à gérer votre consommation.

Loggez les erreurs :

Conservez les `request_id` et `error_code` pour faciliter le débogage et le support technique.

Exemple de gestion d'erreurs en JavaScript
JavaScript - Gestion complète des erreurs
async function callesacodeAPI(message, targetLang) {
  try {
    const response = await fetch('https://www.esacode.org/api/translate/', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer VOTRE_TOKEN'
      },
      body: JSON.stringify({
        message: message,
        target_language: targetLang,
        source_language: 'auto'
      })
    });

    const data = await response.json();

    if (!response.ok) {
      switch (response.status) {
        case 401:
          throw new Error('Token invalide. Vérifiez votre authentification.');
        case 429:
          const retryAfter = data.details?.retry_after || 60;
          throw new Error(`Quota dépassé. Réessayez dans ${retryAfter} secondes.`);
        case 422:
          throw new Error(`Langue '${targetLang}' non supportée.`);
        case 500:
          throw new Error(`Erreur serveur (ID: ${data.details?.request_id})`);
        default:
          throw new Error(`Erreur ${response.status}: ${data.message}`);
      }
    }

    return data;

  } catch (error) {
    console.error('Erreur API esacode:', error.message);
    // Loggez l'erreur dans votre système de monitoring
    throw error;
  }
}

// Utilisation avec gestion d'erreur
try {
  const result = await callesacodeAPI('Hello world', 'fr');
  console.log('Traduction:', result.translated_text);
} catch (error) {
  alert('Erreur: ' + error.message);
}