Guide de démarrage – YODI API

Ce guide montre comment utiliser l'API YODI via HTTP (fetch, axios, curl, etc.).

1. Créer un compte

Rendez-vous sur notre plateforme
Cliquez sur Connexion
Créez un compte

2. Obtenir votre clé API

Connectez-vous à votre tableau de bord
Allez dans Clé API
Cliquez sur Générer une nouvelle clé
Copiez la clé et stockez-la en sécurité

Sécurité

Ne partagez jamais votre clé API,
Ne mettez jamais votre clé dans le frontend

3. Configuration de l'environnement

Variables d’environnement (backend)

Exemple de fichier `.env`

YODI_API_KEY="votre_cle_api"
YODI_BASE_URL="https://admin.yodi.tg"

4. Envoyer vos premières requêtes

- Service de traduction

Description : Traduire un texte d'une langue source vers une langue cible.
Body (JSON) :
- text (string) — texte à traduire
- sourceLang (string) — code langue source (ex: fra_Latn)
- targetLang (string) — code langue cible (ex: mina_Latn, ewe_Latn)
Réponse (JSON) :

{
  "message": "TRANSLATION_SUCCESS",
  "error": false,
  "data": null,
  "status": 200
}

1import os
2import requests
3from dotenv import load_dotenv
4
5load_dotenv()
6
7API_KEY = os.getenv("YODI_API_KEY")
8BASE_URL = os.getenv("YODI_BASE_URL")
9
10def translate(source_text, source_lang, target_lang):
11  url = f"{BASE_URL}/v1/ai/translate-v2"
12  # L'en-tête Authorization attendu : 'Authorization: <API_KEY>'
13  headers = {
14    "Authorization": f"{API_KEY}",
15    "Content-Type": "application/json"
16  }
17  payload = {
18      "text": source_text,
19      "sourceLang": source_lang,
20      "targetLang": target_lang
21  }
22  response = requests.post(url, headers=headers, json=payload)
23  result = response.json()
24  print(result)
25
26# Exemple d'appel
27translate("Bonjour, je souhaite avoir un rappel le 10-12-2025", "fra_Latn", "ewe_Latn")
28

- Service de transcription

Description : Transcrire un fichier audio envoyé en multipart/form-data ou via url.
Form-data attendu : file (obligatoire si url n’est pas envoyé) — fichier audio (.mp3, .wav, .m4a, etc.)
Optionnel url (body field) : si fourni, l'audio sera d'abord téléchargé.
Réponse (JSON) :

{
  "message": "TRANSCRIBE_SUCCESS",
  "error": false,
  "data": null,
  "status": 200
}

1import os
2import requests
3from dotenv import load_dotenv
4
5load_dotenv()
6
7API_KEY = os.getenv("YODI_API_KEY")
8BASE_URL = os.getenv("YODI_BASE_URL")
9
10def transcribe_file(file_path):
11  url = f"{BASE_URL}/v1/ai/transcribe"
12  # Pour les requêtes multipart/form-data, ne pas fixer le Content-Type manuellement
13  headers = {"Authorization": f"{API_KEY}"}
14  files = {"file": open(file_path, "rb")}
15  response = requests.post(url, headers=headers, files=files)
16  result = response.json()
17  print(result.get("message"))
18
19transcribe_file("./sample.mp3")
20

- Service de contact

Description : Envoie un message via contactMethod (sms, call, whatsapp_audio, whatsapp_sms).
Params : contactMethod (ex: sms)
Body (JSON) :
- phone (string | string[]) — numéro(s) destinataires
- input (string) — texte ou URL audio selon le contactMethod
Réponse : objet JSON avec statut et détails

1import os
2import requests
3from dotenv import load_dotenv
4
5load_dotenv()
6
7API_KEY = os.getenv("YODI_API_KEY")
8BASE_URL = os.getenv("YODI_BASE_URL")
9
10def send_contact(contact_method, phone, input_data):
11  url = f"{BASE_URL}/v1/ai/{contact_method}/communication"
12  headers = {
13      "Authorization": f"{API_KEY}",
14      "Content-Type": "application/json"
15  }
16  payload = {
17    "phone": phone,
18    "input": input_data
19  }
20  response = requests.post(url, headers=headers, json=payload)
21  print(response.json())
22
23# Exemples :
24# --- SMS texte ---
25send_contact("sms", "+22812345678", "Votre message ici")
26
27# --- Call ou WhatsApp Audio ---
28send_contact(
29  "whatsapp_audio",
30  "22812345678",
31  {"audioUrl": "https://url/audio.mp3", "durationInSeconds": 12}
32)
33

- Service de synthèse vocale (TTS)

Convertit un texte en message vocal.

Body (JSON) :
- input (string) — texte à convertir en audio
- lang (string) — code de langue
Codes de langue (format standardisé) : fra_Latn (français), mina_Latn (mina), kdh_Latn (tem / kotokoli)
Réponse (JSON) :

{
  "message": "TTS_SUCCESS",
  "error": false,
  "data": {
    "audioUrl": "https://..."
  },
  "status": 200
}

1import os
2import requests
3from dotenv import load_dotenv
4
5load_dotenv()
6
7API_KEY = os.getenv("YODI_API_KEY")
8BASE_URL = os.getenv("YODI_BASE_URL")
9
10def tts(input_text, lang):
11  url = f"{BASE_URL}/v1/ai/tts"
12  headers = {"Authorization": f"{API_KEY}", "Content-Type": "application/json"}
13  payload = {"input": input_text, "lang":lang}
14  response = requests.post(url, headers=headers, json=payload)
15  print(response.json())
16
17tts("Bonjour, ceci est un message vocal Yodi.", "fra_Latn")
18

- Service Financier Text-to-Speech (TTS Finance Agent)

Ce service génère un audio financier et un texte SMS traduit à partir d’une entrée (input) fournie. Il permet notamment :

De convertir un texte en message vocal (audio URL)
D'obtenir la durée de l’audio pour envoie par Appel ou Whatsapp
D’obtenir une version texte traduite pour envoi SMS ou Message whatsapp

Il s'agit d'une interface avec un agent d’IA externe via un appel HTTP sécurisé.

Exemple du contenu attendu pour le champ input

L'API financière attend le champ input comme une chaîne JSON (string). Il faut donc envoyer soit une chaîne JSON stringifiée, soit — si votre endpoint accepte un objet natif — un objet JSON. Exemples :

input envoyé comme objet JSON (si supporté) :

{ "input":{ "date": "01-14-2025",
  "caisse": "1500",
  "caisse_bool": true,
  "compte": "500",
  "compte_bool": true,
  "penalite": "50",
  "penalite_bool": true,
  "credit": "200",
  "credit_bool": true,
  "tontine": "300",
  "tontine_bool": true,
  "total": "2050",
  "total_bool": true,
  "credit_restant": "100",
  "credit_restant_bool": true,
  "total_tontine": "3000",
  "total_tontine_bool": true,
  "arriere": "0",
  "arriere_bool": true,
  "reste": "50",
  "reste_bool": true
  }
}

Réponse (JSON) Succès (200)

{
  "message": "FINANCIAL_AUDIO_GENERATED",
  "error": false,
  "data": {
    "audio": "https://cdn.example.com/audio/xyz.mp3",
    "sms_text": "...",
    "time": 12
  },
  "status": 200
}

Champ	Description
`audio`	URL du fichier audio généré
`sms_text`	Texte SMS traduit généré par l’agent
`time`	Durée de l’audio en secondes

1import os
2import requests
3from dotenv import load_dotenv
4import json
5
6load_dotenv()
7
8API_KEY = os.getenv("YODI_API_KEY")
9BASE_URL = os.getenv("YODI_BASE_URL")
10
11def generate_financial_audio(payload):
12  url = f"{BASE_URL}/v1/ai/financial"
13  headers = {
14    "Authorization": f"{API_KEY}",
15    "Content-Type": "application/json"
16  }
17  # Convertir en string JSON si l'API attend un champ stringifié
18  body = { "input": payload }
19
20  response = requests.post(url, json=body, headers=headers)
21  print(response.json())
22
23# Exemple d'appel (payload complet)
24generate_financial_audio({
25  "date": "01-14-2025",
26  "caisse": "1500",
27  "caisse_bool": True,
28  "compte": "500",
29  "compte_bool": True,
30  "penalite": "50",
31  "penalite_bool": True,
32  "credit": "200",
33  "credit_bool": True,
34  "tontine": "300",
35  "tontine_bool": True,
36  "total": "2050",
37  "total_bool": True,
38  "credit_restant": "100",
39  "credit_restant_bool": True,
40  "total_tontine": "3000",
41  "total_tontine_bool": True,
42  "arriere": "0",
43  "arriere_bool": True,
44  "reste": "50",
45  "reste_bool": True
46})
47

- Service de Rappel

Description : Planifie un rappel pour un ou plusieurs destinataires via différents canaux (sms, call).
Endpoint : POST /v1/ai/reminder
Body (JSON) :

{
  "phones": ["22892567297"], // string ou tableau de strings
  "response_to_recipient": "Votre message ici",
  "lang": "fr", // Langue du message (ex: "fr")
  "reminder_date": "2025-11-28 18:29:00", // Date/heure du rappel (format yyyy-MM-dd HH:mm:ss)
  "deadline_date": "2025-11-28 18:33:00", // Date limite du rappel (format yyyy-MM-dd HH:mm:ss)
  "type": "call", // "sms" | "call" | "whatsapp-auto"
  "frequency": "every-2-minutes" // "every-2-minutes", "every-2-minutes"
}

Réponse : Objet JSON contenant le statut et les détails du rappel créé

{
  "message": "REMINDER_CREATED",
  "error": false,
  "data": {
    "id": "uuid_du_rappel",
    "recipient_phone": ["22892567297"],
    "response_to_recipient": "Votre message ici",
    "lang": "fr",
    "reminder_date": "2025-11-28T18:29:00",
    "deadline_date": "2025-11-28T18:33:00",
    "type": "call",
    "frequency": "every-2-minutes",
    "status": "Enrégistrement réussie"
  },
  "status": 200
}

1import os
2import requests
3from dotenv import load_dotenv
4
5load_dotenv()
6
7API_KEY = os.getenv("YODI_API_KEY")
8BASE_URL = os.getenv("YODI_BASE_URL")
9
10payload = {
11  "phones": ["+22892567297"],
12  "response_to_recipient": "Bonsoir Monsieur, je vous espère en forme",
13  "lang": "fr",
14  "reminder_date": "2025-11-28 18:29:00",
15  "deadline_date": "2025-11-28 18:33:00",
16  "type": "call",
17  "frequency": "every-2-minutes"
18}
19
20response = requests.post(
21  f"{BASE_URL}/v1/ai/reminder",
22  headers={
23      "Authorization": f"{API_KEY}",
24      "Content-Type": "application/json"
25  },
26  json=payload
27)
28
29print(response.json())
30

5. Bonnes pratiques

Bonne pratique	Pourquoi
Stockez la clé en variable d’environnement	Sécurité
Utilisez un backend pour communiquer avec Yodi	Ne jamais exposer la clé sur le frontend
Gérez les erreurs API	Meilleure expérience développeur (DX) et facilité de débogage
Vérifiez les limites d’usage	Éviter les blocages

1. Créer un compte​

2. Obtenir votre clé API​

3. Configuration de l'environnement​

Variables d’environnement (backend)​

Exemple de fichier .env​

4. Envoyer vos premières requêtes​

- Service de traduction​

- Service de transcription​

- Service de contact​

- Service de synthèse vocale (TTS)​

- Service Financier Text-to-Speech (TTS Finance Agent)​

- Service de Rappel​

5. Bonnes pratiques​