Getting Started Guide – YODI API

This guide shows how to use the YODI API over HTTP (fetch, axios, curl, etc.).

1. Create an account

Visit our platform
Click Sign in
Create an account

2. Get your API key

Sign in to your dashboard
Go to API Key
Click Generate a new key
Copy the key and store it securely

Security

Never share your API key.
Never put your API key in frontend code.

3. Environment setup

Environment variables (backend)

Example `.env` file

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

4. Sending your first requests

- Translation service

Description: Translate a text from a source language to a target language.
Request body (JSON):
- text (string) — text to translate
- sourceLang (string) — source language code (e.g. fra_Latn)
- targetLang (string) — target language code (e.g. mina_Latn, ewe_Latn)
Response (JSON):

{
  "success": true,
  "message": "translation",
  "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"
    # The expected Authorization header: 'Authorization: <API_KEY>'
    headers = {
      "Authorization": f"{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)

# Example call
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: `${API_KEY}`,
          "Content-Type": "application/json",
        },
      }
    );

    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error("API Error:", 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: 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"}'

- Transcription service

{
  "success": true,
  "message": "Message transcrit",
  "code": "TRANSCRIBE_SUCCESS"
}

Description: Transcribe an audio file sent as multipart/form-data or via a url.
Form data expected: file (required if url is not provided) — audio file (.mp3, .wav, .m4a, etc.)
Optional url (body field): if provided, the audio will be downloaded first.
Response (JSON):

{
  "success": true,
  "message": "Message 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"
    # For multipart/form-data requests, do not set the Content-Type manually
    headers = {"Authorization": f"{API_KEY}"}
    files = {"file": open(file_path, "rb")}
    response = requests.post(url, headers=headers, files=files)
    result = response.json()
    print(result.get("message"))

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: `${API_KEY}`,
    },
  });
  console.log(response.data.transcription);
}

// Example call
transcribeFile("./sample.mp3");

cURL

# Example with a local file path

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

# Example with a URL

curl -X POST "https://admin.yodi.tg/v1/ai/transcribe" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/audio/abalo.m4a"}'

- Contact service

Description: Send a message via contactMethod (sms, call, whatsapp_audio, whatsapp_sms).
Parameters: contactMethod (e.g. sms)
Request body (JSON):
- phone (string | string[]) — recipient phone number(s)
- input (string) — text or audio URL depending on contactMethod
Response: JSON object with status and details

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

# Examples:
# --- SMS text ---
send_contact("sms", "22812345678", "Your message here")

# --- Call or 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", "Your message here");

// 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": "Your message here"}'

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}}'

- Text-to-Speech (TTS) service

Converts text into a spoken audio message.

input (string) — text to convert into audio
lang (string) — language code

{
  "success": true,
  "message": "Audio generated successfully",
  "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())

# Example call
tts("Hello, this is a Yodi voice message.", "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: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"input": "Bonjour, ceci est un test TTS", "lang":"mina_Latn"}'

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

This service generates financial audio and translated SMS text from a provided input. In particular, it allows you to:

To convert text into a voice message (audio URL)
To obtain the audio duration for sending via Call or WhatsApp
To obtain a translated text version for sending via SMS or WhatsApp message

This is an interface with an external AI agent via a secure HTTP call.

Example of expected content for the input field

The financial API expects the input field as a JSON string. You must therefore send either a stringified JSON string or—if your endpoint accepts a native object—a JSON object. Examples :

input sent as a JSON object (if supported):

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

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

Champ	Description
`audio`	URL of the generated audio file
`sms_text`	Translated SMS text generated by the agent
`time`	Audio duration in seconds

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"{API_KEY}",
      "Content-Type": "application/json"
    }
    # Convertir en string JSON si l'API attend un champ stringifié
    body = { "input": payload }

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

  # Exemple d'appel (payload complet)
generate_financial_audio({
    "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
})

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: payload,
    },
    {
      headers: {
        Authorization: `${API_KEY}`,
        "Content-Type": "application/json",
      },
    }
  );

  console.log(response.data);
}

cURL

curl -X POST "http://admin.yodi.tg/v1/ai/financial" -H "Authorization: YOUR_API_KEY" 
-H "Content-Type: application/json" 
-d '{
  "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
  }}'

- Reminder Service

Description : Schedule a reminder for one or more recipients via different channels (sms, call).
Endpoint : POST /v1/ai/reminder
Body (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 : JSON object containing the status and details of the created recall

{
  "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. Best practices

Best practice	Why
Store your API key in an environment variable	Security
Use a backend to communicate with YODI	Never expose the key in frontend code
Handle API errors	Better developer experience (DX) and easier debugging
Check usage limits	Avoid service interruptions

1. Create an account​

2. Get your API key​

3. Environment setup​

Environment variables (backend)​

Example .env file​

4. Sending your first requests​

- Translation service​

Python​

JavaScript (Node.js)​

cURL​

- Transcription service​

Python​

JavaScript​

cURL​

- Contact service​

Python​

JavaScript​

cURL​

- Text-to-Speech (TTS) service​

Python​

JavaScript​

cURL​

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

Python​

JavaScript (Axios)​

cURL​

- Reminder Service​

Python​

JavaScript / Node.js​

cURL​

5. Best practices​

1. Create an account

2. Get your API key

3. Environment setup

Environment variables (backend)

Example `.env` file

4. Sending your first requests

- Translation service

Python

JavaScript (Node.js)

cURL

- Transcription service

Python

JavaScript

cURL

- Contact service

Python

JavaScript

cURL

- Text-to-Speech (TTS) service

Python

JavaScript

cURL

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

Python

JavaScript (Axios)

cURL

- Reminder Service

Python

JavaScript / Node.js

cURL

5. Best practices