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éer 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) :

{
  "success": true,
  "message": "traduction",
  "code": "TRANSLATION_SUCCESS"
}

Python

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("YODI_API_KEY")
BASE_URL = os.getenv("YODI_BASE_URL")

def translate(source_text, source_lang, target_lang):
    url = f"{BASE_URL}/v1/ai/translate-v2"
    # L'en-tête d'authorization attendu : 'Authorization: Bearer <API_KEY>'
    headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
    }
    payload = {
        "text": source_text,
        "sourceLang": source_lang,
        "targetLang": target_lang
    }
    response = requests.post(url, headers=headers, json=payload)
    result = response.json()
    print(result)

# Exemple d'appel
translate("Bonjour, je souhaite avoir un rappel le 10-12-2025", "fra_Latn", "ewe_Latn")

JavaScript (Node.js)

import axios from "axios";

const API_KEY = process.env.YODI_API_KEY;
const BASE_URL = process.env.YODI_BASE_URL;

async function translate(sourceText, sourceLang, targetLang) {
  try {
    const response = await axios.post(
      `${BASE_URL}/v1/ai/translate-v2`,
      {
        text: sourceText,
        sourceLang,
        targetLang,
      },
      {
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
        },
      }
    );

    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error("Erreur API :", error.response?.data || error.message);
  }
}

translate(
  "Bonjour, Je souhaite avoir un rappel le 10-12-2025",
  "fra_Latn",
  "ewe_Latn"
);

cURL

curl -X POST "https://admin.yodi.tg/v1/ai/translate-v2" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"text": "Bonjour, Je souhaite avoir un rappel le 10-12-2025", "sourceLang": "fra_Latn", "targetLang": "mina_Latn"}'

- 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) :

{
  "success": true,
  "message": "Transcription réussie",
  "transcription": "texte transcrit",
  "code": "TRANSCRIBE_SUCCESS"
}

Python

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("YODI_API_KEY")
BASE_URL = os.getenv("YODI_BASE_URL")

def transcribe_file(file_path):
    url = f"{BASE_URL}/v1/ai/transcribe"
    # Pour les requêtes multipart/form-data, ne pas fixer le Content-Type manuellement
    headers = {"Authorization": f"Bearer {API_KEY}"}
    files = {"file": open(file_path, "rb")}
    response = requests.post(url, headers=headers, files=files)
    result = response.json()
    print(result.get("transcription"))

transcribe_file("./sample.mp3")

JavaScript

import axios from "axios";
import fs from "fs";
import FormData from "form-data";

const API_KEY = process.env.YODI_API_KEY;
const BASE_URL = process.env.YODI_BASE_URL;

async function transcribeFile(filePath) {
  const form = new FormData();
  form.append("file", fs.createReadStream(filePath));

  const response = await axios.post(`${BASE_URL}/v1/ai/transcribe`, form, {
      headers: {
      ...form.getHeaders(),
      Authorization: `Bearer ${API_KEY}`,
    },
  });
  console.log(response.data.transcription);
}

// Exemple d'appel
transcribeFile("./sample.mp3");

cURL

curl -X POST "https://admin.yodi.tg/v1/ai/transcribe" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -F "file=@./sample.mp3"

- 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

Python

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("YODI_API_KEY")
BASE_URL = os.getenv("YODI_BASE_URL")

def send_contact(contact_method, phone, input_data):
    url = f"{BASE_URL}/v1/ai/{contact_method}/communication"
    headers = {
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
      "phone": phone,
      "input": input_data
    }

    response = requests.post(url, headers=headers, json=payload)
    print(response.json())

# Exemples :
# --- SMS texte ---
send_contact("sms", "22812345678", "Votre message ici")

# --- Call ou WhatsApp Audio ---
send_contact(
    "whatsapp_audio",
    "22812345678",
    {"audioUrl": "https://url/audio.mp3", "durationInSeconds": 12}
)

JavaScript

import axios from "axios";

const API_KEY = process.env.YODI_API_KEY;
const BASE_URL = process.env.YODI_BASE_URL;

async function sendContact(contactMethod, phone, input) {
  const response = await axios.post(
    `${BASE_URL}/v1/ai/${contactMethod}/communication`,
    { phone, input },
    { headers: { Authorization: `${API_KEY}` } }
  );

  console.log(response.data);
}

// SMS
sendContact("sms", "22812345678", "Votre message ici");

// WhatsApp audio & Call
sendContact("whatsapp_audio", "22812345678", {
  audioUrl: "https://url/audio.mp3",
  durationInSeconds: 1,
});

cURL

SMS

curl -X POST "https://admin.yodi.tg/v1/ai/sms/communication" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"phone": "22812345678", "input": "Votre message ici"}'

WhatsApp Audio & Call

curl -X POST "https://admin.yodi.tg/v1/ai/whatsapp_audio/communication" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"phone":"22812345678","input":{"audioUrl":"https://url/audio.mp3","durationInSeconds":14}}'

- 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) :

{
  "success": true,
  "message": "Audio généré avec succès",
  "audioUrl": "https://..."
}

Python

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("YODI_API_KEY")
BASE_URL = os.getenv("YODI_BASE_URL")

def tts(input_text,lang):
    url = f"{BASE_URL}/v1/ai/tts"
    headers = {"Authorization": f"{API_KEY}", "Content-Type": "application/json"}
    payload = {"input": input_text, "lang":lang}
    response = requests.post(url, headers=headers, json=payload)
    print(response.json())

tts("Bonjour, ceci est un message vocal Yodi.", "fra_Latn")

JavaScript

import axios from "axios";

async function tts(text) {
  try {
    const response = await axios.post(
      `${process.env.YODI_BASE_URL}/v1/ai/tts`,
      { input: text , lang: "fra_Latn"},
      { headers: { Authorization: `${process.env.YODI_API_KEY}`, "Content-Type": "application/json" } }
    );
    console.log(response.data);
  } catch (error) {
    console.error("Erreur API :", error.response?.data || error.message);
  }
}

tts("Bonjour, ceci est un message vocal Yodi.");

cURL

curl -X POST "https://admin.yodi.tg/v1/ai/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Bonjour, ceci est un test TTS", "lang":"mina_Latn"}'

- 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 stringifié :

{
  "input": "{ \"payload\": { \"date\": \"2025-01-14\", \"caisse\": 1500, \"compte\": 500, \"penalite\": 50, \"credit\": 200, \"tontine\": 300, \"total\": 2050 } }"
}

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

{
  "input": {
    "payload": {
      "date": "2025-01-14",
      "caisse": 1500,
      "compte": 500,
      "penalite": 50,
      "credit": 200,
      "tontine": 300,
      "total": 2050
    }
  }
}

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

{
  "audio": "https://cdn.example.com/audio/xyz.mp3",
  "sms_text": "...",
  "time": 12
}

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

Python

import os
import requests
from dotenv import load_dotenv
import json

load_dotenv()

API_KEY = os.getenv("YODI_API_KEY")
BASE_URL = os.getenv("YODI_BASE_URL")

def generate_financial_audio(payload):
    url = f"{BASE_URL}/v1/ai/financial"
    headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
    }

    # Convertir en string JSON si l'API attend un champ stringifié
    body = { "input": json.dumps(payload) }

    response = requests.post(url, json=body, headers=headers)
    print(response.json())

  # Exemple d'appel (payload complet)
  generate_financial_audio({
    "payload": {
      "date": "2025-12-04",
      "caisse": 1500,
      "compte": 500,
      "penalite": 50,
      "credit": 200,
      "tontine": 300,
      "total": 2050,
      "credit_restant": 100,
      "total_tontine": 3000,
      "arriere": 0,
      "reste": 50
    }
  })

JavaScript (Axios)

import axios from "axios";

const API_KEY = process.env.YODI_API_KEY;
const BASE_URL = process.env.YODI_BASE_URL;

async function generateFinancialAudio(payload) {
  const response = await axios.post(
    `${BASE_URL}/v1/ai/financial`,
    {
      input: JSON.stringify(payload),
    },
    {
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
    }
  );

  console.log(response.data);
}

cURL

curl -X POST "https://admin.yodi.tg/v1/ai/financial" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
        "input": "{ \"date\": \"2025-12-04\", \"amount\": 50000 }"
      }'

- 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éé

{
  "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"
}

Python

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("YODI_API_KEY")
BASE_URL = os.getenv("YODI_BASE_URL")

payload = {
    "phones": ["+22892567297"],
    "response_to_recipient": "Bonsoir Monsieur, je vous espère en forme",
    "lang": "fr",
    "reminder_date": "2025-11-28 18:29:00",
    "deadline_date": "2025-11-28 18:33:00",
    "type": "call",
    "frequency": "every-2-minutes"
}

response = requests.post(
    f"{BASE_URL}/v1/ai/reminder",
    headers={
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())

JavaScript / Node.js

import axios from "axios";

const API_KEY = process.env.YODI_API_KEY;
const BASE_URL = process.env.YODI_BASE_URL;

const payload = {
  phones: ["+22892567297"],
  response_to_recipient: "Bonsoir Monsieur, je vous espère en forme",
  lang: "fr",
  reminder_date: "2025-11-28 18:29:00",
  deadline_date: "2025-11-28 18:33:00",
  type: "call",
  frequency: "every-2-minutes"
};

async function createReminder() {
  try {
    const response = await axios.post(`${BASE_URL}/v1/ai/reminder`, payload, {
      headers: { 
        Authorization: API_KEY, 
        "Content-Type": "application/json" 
      }
    });
    console.log(response.data);
  } catch (err) {
    console.error(err.response?.data || err.message);
  }
}

// Exemple d'appel
createReminder();

cURL

curl -X POST "https://admin.yodi.tg/v1/ai/reminder" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": ["+22892567297"],
    "response_to_recipient": "Bonsoir Monsieur, je vous espère en forme",
    "lang": "fr",
    "reminder_date": "2025-11-28 18:29:00",
    "deadline_date": "2025-11-28 18:33:00",
    "type": "call",
    "frequency": "every-2-minutes"
  }'

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​

Python​

JavaScript (Node.js)​

cURL​

- Service de transcription​

Python​

JavaScript​

cURL​

- Service de contact​

Python​

JavaScript​

cURL​

- Service de synthèse vocale (TTS)​

Python​

JavaScript​

cURL​

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

Python​

JavaScript (Axios)​

cURL​

- Service de Rappel​

Python​

JavaScript / Node.js​

cURL​

5. Bonnes pratiques​

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

Python

JavaScript (Node.js)

cURL

- Service de transcription

Python

JavaScript

cURL

- Service de contact

Python

JavaScript

cURL

- Service de synthèse vocale (TTS)

Python

JavaScript

cURL

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

Python

JavaScript (Axios)

cURL

- Service de Rappel

Python

JavaScript / Node.js

cURL

5. Bonnes pratiques