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

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

- Transcription service

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

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

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

- 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

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

- Text-to-Speech (TTS) service

Converts text into a spoken audio message.

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

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

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

{
  "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 of the generated audio file
`sms_text`	Translated SMS text generated by the agent
`time`	Audio duration in seconds

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

- 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

{
  "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. 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​

- Transcription service​

- Contact service​

- Text-to-Speech (TTS) service​

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

- Reminder Service​

5. Best practices​