Guide de démarrage – API YODI

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

1. Créer un compte

1. Visitez notre plateforme
2. Cliquez sur Sign in
3. Créez un compte

2. Obtenir votre clé API

1. Connectez-vous à votre tableau de bord
2. Allez dans API Key
3. Cliquez sur Generate a new key
4. Copiez la clé et stockez-la en toute sécurité

Sécurité

• Ne partagez jamais votre clé API.
• Ne mettez jamais votre clé API dans du code frontend.

3. Configuration de l'environnement

Variables d'environnement (backend)

Exemple de fichier .env

YODI_API_KEY="your_api_key"
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.

• Corps de la requête (JSON) :

  • text (string) — texte à traduire
  • sourceLang (string) — code de la langue source (ex. fra_Latn)
  • targetLang (string) — code de la langue cible (ex. mina_Latn, ewe_Latn)

• Réponse (JSON) :

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

PythonJavaScriptcURL

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  # The expected Authorization header: '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# Example call
27translate("Bonjour, je souhaite avoir un rappel le 10-12-2025", "fra_Latn", "ewe_Latn")
28

- Service de transcription

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

• Description : Transcrire un fichier audio envoyé en tant que multipart/form-data ou via une url.
• Données du formulaire attendues : file (obligatoire si url n'est pas fournie) — fichier audio (.mp3, .wav, .m4a, etc.)
• url optionnelle (champ du corps) : si fournie, l'audio sera d'abord téléchargé.
• Réponse (JSON) :

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

PythonJavaScriptcURL

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  # For multipart/form-data requests, do not set the Content-Type manually
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 : Envoyer un message via contactMethod (sms, call, whatsapp_audio, whatsapp_sms).

• Paramètres : contactMethod (ex. sms)

• Corps de la requête (JSON) :

  • phone (string | string[]) — numéro(s) de téléphone du destinataire
  • input (string) — texte ou URL audio selon le contactMethod

• Réponse : Objet JSON avec le statut et les détails

PythonJavaScriptcURL

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# Examples:
24# --- SMS text ---
25send_contact("sms", "22812345678", "Your message here")
26
27# --- Call or WhatsApp Audio ---
28send_contact(
29"whatsapp_audio",
30"22812345678",
31{"audioUrl": "https://url/audio.mp3", "durationInSeconds": 12}
32)
33

- Service Text-to-Speech (TTS)

Convertit un texte en un message audio parlé.

• input (string) — texte à convertir en audio
• lang (string) — code de la langue

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

PythonJavaScriptcURL

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
17# Example call
18tts("Hello, this is a Yodi voice message.", "fra_Latn")
19

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

Ce service génère un audio financier et un texte SMS traduit à partir d'une entrée fournie. En particulier, il vous permet de :

• Convertir du texte en message vocal (URL audio)
• Obtenir la durée audio pour l'envoi par appel ou WhatsApp
• Obtenir une version texte traduit pour l'envoi par SMS ou message WhatsApp

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

Exemple de contenu attendu pour le champ input

L'API financière attend le champ input sous forme de chaîne JSON. Vous devez donc envoyer soit une chaîne JSON stringifiée, soit — si votre endpoint accepte un objet natif — un objet JSON. Exemples :

1. input envoyé en tant qu'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

PythonJavaScriptcURL

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 : Planifier un rappel pour un ou plusieurs destinataires via différents canaux (sms, call).
• Endpoint : POST /v1/ai/reminder
• Corps (JSON) :

{
  "phones": ["22892567297"], // string or array of strings
  "response_to_recipient": "Votre message ici",
  "lang": "fr", // Language of the message (e.g., “en”)
  "reminder_date": "2025-11-28 18:29:00", // Date/time of the reminder (format yyyy-MM-dd HH:mm:ss)
  "deadline_date": "2025-11-28 18:33:00", // Reminder deadline (format yyyy-MM-dd HH:mm:ss)
  "type": "call", // "sms" | "call" | "whatsapp-auto"
  "frequency": "every-3600-minutes" // "every-3600-minutes", "every-3600-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
}

PythonJavaScriptcURL

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
Stocker votre clé API dans une variable d'environnement	Sécurité
Utiliser un backend pour communiquer avec YODI	Ne jamais exposer la clé dans le code frontend
Gérer les erreurs API	Meilleure expérience développeur (DX) et débogage facilité
Vérifier les limites d'utilisation	Éviter les interruptions de service