Documentation API Kooma

Ajoute la voix et la langue à tes applications : transcription, synthèse vocale, traduction, sous-titrage et doublage de vidéos — avec un bambara natif et les grandes langues internationales.

L'API Kooma est organisée autour de REST : des URL prévisibles, des corps JSON (ou multipart/form-data pour les fichiers), les codes de statut HTTP standards et l'authentification par clé. Tout ce que tu fais dans la console, tu peux l'automatiser ici.

URL de base	`https://api.kooma.ai/v1`
Authentification	En-tête `Authorization: Bearer sk-intermo-…`
Format	Requêtes en `JSON` ou `multipart/form-data` · réponses en `JSON` ou fichier (audio / vidéo / sous-titres)
Facturation	À l'usage réel : à la minute d'audio/vidéo, ou aux 1 000 caractères pour le texte. Prépayé, décompté sur ton portefeuille.

Le plus rapide

Tu veux juste essayer sans écrire de code ? Ouvre le playground interactif : il génère automatiquement le code de chaque appel.

Démarrage rapide

Ton premier appel en moins de 5 minutes.

1 · Crée une clé API

Dans la console, ouvre Clés API, clique Créer une clé et coche au moins une autorisation (Synthèse vocale, Transcription ou Traduction). Copie la clé sk-intermo-… : elle ne s'affiche qu'une fois.

2 · Fais ta première requête

Cet appel transforme un texte bambara en audio et l'enregistre dans sortie.wav. Remplace VOTRE_CLE par ta clé.

Génère un fichier audio à partir d'un texte.

curl https://api.kooma.ai/v1/audio/speech \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"input":"Aw ni ce, i ka kɛnɛ wa?","voice":"modibo"}' \
  --output sortie.wav

import requests

r = requests.post(
    "https://api.kooma.ai/v1/audio/speech",
    headers={"Authorization": "Bearer sk-intermo-VOTRE_CLE"},
    json={"input": "Aw ni ce, i ka kɛnɛ wa?", "voice": "modibo"},
)
open("sortie.wav", "wb").write(r.content)

const r = await fetch("https://api.kooma.ai/v1/audio/speech", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-intermo-VOTRE_CLE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "Aw ni ce, i ka kɛnɛ wa?", voice: "modibo" }),
});
const audio = await r.arrayBuffer(); // fichier WAV

3 · Vérifie la réponse

Un statut 200 OK renvoie directement le fichier audio (Content-Type: audio/wav). Une erreur renvoie un corps JSON explicite — voir Erreurs.

Et ensuite ?

Passe à Faire une requête pour les conventions communes, ou saute directement à la référence des endpoints.

Authentification

Chaque requête doit porter ta clé API dans l'en-tête Authorization, préfixée par Bearer .

Les clés commencent par sk-intermo-. Crée-les, limite leur portée et supprime-les depuis Clés API.

Autorisations (portée)

À la création, tu choisis ce que la clé peut appeler. Une requête vers un endpoint hors périmètre renvoie 403.

Autorisation	Donne accès à
`tts`	Synthèse vocale
`stt`	Transcription
`mt`	Traduction
`inference`	Accès complet (toutes les capacités)

Garde ta clé secrète

Une clé donne accès à ton crédit. Ne la mets jamais dans du code côté navigateur, une app mobile ou un dépôt public. Appelle l'API depuis ton serveur. En cas de fuite, révoque-la depuis la console.

Test vs production

Crée une clé Personnelle pour le développement et une clé Service pour la production. Tu peux poser un plafond de crédit et une liste d'adresses IP autorisées par clé.

EN-TÊTE

Authorization: Bearer sk-intermo-VOTRE_CLE

401 Clé absente ou invalide

{
  "error": {
    "message": "Missing bearer token. Use 'Authorization: Bearer sk-intermo-...'.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Faire une requête

Conventions communes à tous les endpoints.

Corps de requête & fichiers

Les endpoints texte (synthèse vocale, traduction) attendent un corps JSON avec Content-Type: application/json. Les endpoints qui reçoivent un média (transcription, sous-titrage, doublage) attendent un envoi multipart/form-data avec un champ file, ou une source_url.

Contrainte	Valeur
Formats média acceptés	`mp3`, `wav`, `m4a`, `webm`, `mp4`, `mov` …
Taille maximale d'un fichier	80 Mo au-delà : `413`
Longueur maximale d'un texte	5 000 caractères par requête
Codes de langue	Voir Langues (ex. `bam_Latn`, `fra_Latn`, `eng_Latn`)

Synchrone vs asynchrone

Deux familles d'appels selon le temps de traitement :

Synchrone — transcription, synthèse vocale, traduction. La réponse (JSON ou fichier) arrive dans le même appel.
Asynchrone (jobs) — sous-titrage et doublage traitent une vidéo entière. L'appel de création renvoie immédiatement {"job_id": "…", "status": "queued"}. Tu suis ensuite l'avancement.

Suivre un job (polling)

Interroge l'endpoint de statut jusqu'à ce que status passe à done (ou error), puis télécharge le résultat.

Boucle de polling type sur un job asynchrone.

# interroger toutes les 5 s
curl https://api.kooma.ai/subtitle/jobs/JOB_ID \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE"

import time, requests
H = {"Authorization": "Bearer sk-intermo-VOTRE_CLE"}

while True:
    j = requests.get(
        f"https://api.kooma.ai/subtitle/jobs/{job_id}", headers=H
    ).json()
    if j["status"] in ("done", "error"):
        break
    time.sleep(5)

Statuts d'un job

queued → processing → done. En cas d'échec : error avec un champ error lisible. Un intervalle de 5 s entre deux interrogations est un bon compromis.

Idempotence & reprise

Le sous-titrage et le doublage sont facturés à la création du job. Ne relance pas un job identique en boucle : réutilise le job_id existant et son statut.

POST Transcription

Convertit un fichier audio ou vidéo en texte, avec détection automatique de la langue. Idéal pour le bambara, disponible aussi pour les grandes langues internationales.

POST/v1/audio/transcriptions

Envoi multipart/form-data. Autorisation requise : stt.

Paramètres

Nom	Type	Description
`file`requis	fichier	Le fichier audio ou vidéo à transcrire (80 Mo max).
`response_format`option	string	`json` (défaut) renvoie `{"text": …}` ; `text` renvoie le texte brut.
`model`option	string	Identifiant de modèle (informatif). Défaut `kooma-stt-1`.

Réponse

Champ	Type	Description
`text`	string	La transcription du média.

Facturé à la seconde réelle d'audio.

curl https://api.kooma.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE" \
  -F [email protected]

import requests

r = requests.post(
    "https://api.kooma.ai/v1/audio/transcriptions",
    headers={"Authorization": "Bearer sk-intermo-VOTRE_CLE"},
    files={"file": open("reunion.mp3", "rb")},
)
print(r.json()["text"])

const fd = new FormData();
fd.append("file", fileInput.files[0]);

const r = await fetch("https://api.kooma.ai/v1/audio/transcriptions", {
  method: "POST",
  headers: { "Authorization": "Bearer sk-intermo-VOTRE_CLE" },
  body: fd,
});
const { text } = await r.json();

200 OK application/json

{
  "text": "Aw ni ce, an bɛɛ ye ɲɔgɔn ye bi..."
}

413 Fichier trop volumineux

{
  "error": {
    "message": "File too large.",
    "type": "invalid_request_error",
    "code": "file_too_large"
  }
}

POST Synthèse vocale

Transforme un texte en voix naturelle. Choisis parmi les voix bambara publiées, ou une voix internationale. Réponse : un fichier audio WAV.

POST/v1/audio/speech

Corps JSON. Autorisation requise : tts.

Paramètres

Nom	Type	Description
`input`requis	string	Le texte à lire (5 000 caractères max).
`voice`option	string	Identifiant de voix (voir Voix). Défaut `modibo`.
`tgt`option	string	Langue du texte/de la voix (voir Langues). Défaut `bam_Latn`.
`src`option	string	Traduire le texte avant lecture : langue source, ou `auto`. Défaut `same` (pas de traduction).
`speed`option	number	Débit de parole, de `0.5` à `2.0`.
`response_format`option	string	Format audio de sortie. `wav` (défaut).

Réponse

Le corps est le fichier audio brut (Content-Type: audio/wav), pas du JSON. Écris-le directement sur disque.

Facturé au caractère. Les voix personnalisées (clonées) sont facturées à un tarif supérieur.

curl https://api.kooma.ai/v1/audio/speech \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "I ni ce, i ka kɛnɛ wa?",
    "voice": "aminata",
    "tgt": "bam_Latn",
    "speed": 1.0
  }' \
  --output sortie.wav

import requests

r = requests.post(
    "https://api.kooma.ai/v1/audio/speech",
    headers={"Authorization": "Bearer sk-intermo-VOTRE_CLE"},
    json={
        "input": "I ni ce, i ka kɛnɛ wa?",
        "voice": "aminata",
        "tgt": "bam_Latn",
    },
)
open("sortie.wav", "wb").write(r.content)

const r = await fetch("https://api.kooma.ai/v1/audio/speech", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-intermo-VOTRE_CLE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "I ni ce, i ka kɛnɛ wa?",
    voice: "aminata",
    tgt: "bam_Latn",
  }),
});
const wav = await r.arrayBuffer();

200 OK audio/wav (binaire)

RIFF....WAVEfmt ............   # fichier audio

402 Crédit insuffisant

{
  "error": {
    "message": "Insufficient prepaid credits for 'tts'.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  }
}

POST Traduction

Traduit un texte d'une langue vers une autre — bambara ↔ français / anglais et grandes langues internationales — avec détection automatique de la langue source.

POST/v1/translations

Corps JSON. Autorisation requise : mt.

Paramètres

Nom	Type	Description
`text`requis	string	Le texte à traduire (5 000 caractères max).
`target`option	string	Langue cible (voir Langues). Défaut `bam_Latn`.
`source`option	string	Langue source. Absent ou `auto` = détection automatique.

Réponse

Champ	Type	Description
`text`	string	Le texte traduit.
`source`	string	Langue source retenue (utile si `auto`).
`target`	string	Langue cible.
`translations`	array	Liste des traductions `{text, source, target}`.

Facturé au caractère du texte source.

curl https://api.kooma.ai/v1/translations \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Bonjour, comment allez-vous ?",
    "target": "bam_Latn"
  }'

import requests

r = requests.post(
    "https://api.kooma.ai/v1/translations",
    headers={"Authorization": "Bearer sk-intermo-VOTRE_CLE"},
    json={"text": "Bonjour, comment allez-vous ?", "target": "bam_Latn"},
)
print(r.json()["text"])

const r = await fetch("https://api.kooma.ai/v1/translations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-intermo-VOTRE_CLE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Bonjour, comment allez-vous ?", target: "bam_Latn" }),
});
const { text } = await r.json();

200 OK application/json

{
  "text": "I ni ce, i ka kɛnɛ wa?",
  "source": "fra_Latn",
  "target": "bam_Latn",
  "translations": [
    {
      "text": "I ni ce, i ka kɛnɛ wa?",
      "source": "fra_Latn",
      "target": "bam_Latn"
    }
  ]
}

POST Sous-titrage

Génère des sous-titres horodatés pour une vidéo, dans une ou plusieurs langues. Traitement asynchrone : tu crées un job, tu suis son avancement, puis tu récupères les fichiers SRT / VTT.

Envoi multipart/form-data.

Créer un job

POST/subtitle/jobs

Nom	Type	Description
`file`l'un des deux	fichier	La vidéo à sous-titrer (80 Mo max).
`source_url`l'un des deux	string	Lien direct vers un fichier, ou lien de plateforme vidéo.
`target_langs`option	string	Langues cibles, séparées par des virgules (une piste par langue).
`source_lang`option	string	Langue parlée dans la vidéo. Défaut `auto`.

Suivre & exporter

Endpoint	Rôle
GET `/subtitle/jobs/{id}`	Statut + segments horodatés.
GET `/subtitle/jobs/{id}/export`	Fichier sous-titres. Query `format=srt\|vtt\|ttml`, `track=target\|original`, `lang`.
POST `/subtitle/jobs/{id}/translate`	Ajouter des langues à un job déjà transcrit — corps `{"langs": […]}`.
GET `/subtitle/jobs`	Lister tes jobs récents.

Facturé à la minute de vidéo.

# 1. créer le job
curl https://api.kooma.ai/subtitle/jobs \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE" \
  -F [email protected] \
  -F source_lang=bam_Latn \
  -F target_langs=fra_Latn,eng_Latn

# 2. quand status=done, exporter le SRT français
curl "https://api.kooma.ai/subtitle/jobs/JOB_ID/export?format=srt&track=target&lang=fra_Latn" \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE" \
  --output sous-titres-fr.srt

import requests
H = {"Authorization": "Bearer sk-intermo-VOTRE_CLE"}

job = requests.post(
    "https://api.kooma.ai/subtitle/jobs", headers=H,
    files={"file": open("video.mp4", "rb")},
    data={"source_lang": "bam_Latn", "target_langs": "fra_Latn,eng_Latn"},
).json()

# ... polling sur /subtitle/jobs/{id} jusqu'a done ...
srt = requests.get(
    f"https://api.kooma.ai/subtitle/jobs/{job['job_id']}/export",
    headers=H, params={"format": "srt", "track": "target", "lang": "fra_Latn"},
).text

200 OK job créé

{
  "job_id": "a1b2c3d4e5f6a7b8",
  "status": "queued",
  "duration_sec": 184.2,
  "minutes": 4,
  "target_langs": ["fra_Latn", "eng_Latn"]
}

POST Doublage

Traduit et re-vocalise une vidéo dans une autre langue, avec une voix de la bibliothèque, synchronisée sur l'original. Traitement asynchrone.

Envoi multipart/form-data.

Créer un job

POST/dub/jobs

Nom	Type	Description
`file`source	fichier	La vidéo à doubler (80 Mo max).
`source_url`source	string	Lien direct ou lien de plateforme vidéo.
`from_job`source	string	Réutilise un job de sous-titrage terminé (transcription + traduction déjà faites).
`target_lang`option	string	Langue de la voix doublée. Défaut `bam_Latn`.
`voice`option	string	Voix de la bibliothèque (voir Voix). Défaut `modibo`.
`source_lang`option	string	Langue parlée dans la vidéo. Défaut `auto`.
`debit`option	string	Rythme de la voix : `lent`, `normal`, `rapide`.

Suivre & télécharger

Endpoint	Rôle
GET `/dub/jobs/{id}`	Statut du job + segments.
GET `/dub/jobs/{id}/download`	Télécharger la vidéo doublée (prête quand `status=done`).
GET `/dub/jobs`	Lister tes doublages récents.

Facturé à la minute de vidéo.

# 1. créer le doublage (FR -> bambara, voix Modibo)
curl https://api.kooma.ai/dub/jobs \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE" \
  -F [email protected] \
  -F target_lang=bam_Latn \
  -F voice=modibo

# 2. quand status=done, récupérer la vidéo doublée
curl https://api.kooma.ai/dub/jobs/JOB_ID/download \
  -H "Authorization: Bearer sk-intermo-VOTRE_CLE" \
  --output video-doublee.mp4

import requests
H = {"Authorization": "Bearer sk-intermo-VOTRE_CLE"}

job = requests.post(
    "https://api.kooma.ai/dub/jobs", headers=H,
    files={"file": open("video.mp4", "rb")},
    data={"target_lang": "bam_Latn", "voice": "modibo"},
).json()

# ... polling sur /dub/jobs/{id} jusqu'a done ...
out = requests.get(
    f"https://api.kooma.ai/dub/jobs/{job['job_id']}/download", headers=H
)
open("video-doublee.mp4", "wb").write(out.content)

200 OK job créé

{
  "job_id": "9f8e7d6c5b4a3210",
  "status": "queued",
  "duration_sec": 184.2,
  "minutes": 4
}

Voix disponibles

Passe l'identifiant dans le champ voice de la synthèse vocale ou du doublage. Le catalogue complet, avec écoute, est dans la console (Voix). Tu peux aussi cloner ta propre voix.

Voix	Genre	Identifiant API
Chargement du catalogue…

Plus de 40 voix

Le catalogue s'enrichit régulièrement. Ouvre Voix dans la console pour écouter toutes les voix et récupérer leur identifiant, ou pour cloner la tienne.

Langues

Les codes de langue combinent la langue et l'écriture (norme ISO), par exemple bam_Latn pour le bambara. Utilise-les dans tgt/src (synthèse), target/source (traduction) et target_langs (sous-titrage).

Langue	Code	Transcription	Traduction	Synthèse
Bambara natif	`bam_Latn`	✓	✓	✓
Français	`fra_Latn`	✓	✓	✓
English	`eng_Latn`	✓	✓	✓
Español	`spa_Latn`	✓	✓	✓
Português	`por_Latn`	✓	✓	✓
Italiano	`ita_Latn`	✓	✓	✓
العربية (Arabe)	`arb_Arab`	✓	✓	✓
中文 (Chinois)	`zho_Hans`	✓	✓	✓
Русский (Russe)	`rus_Cyrl`	✓	✓	✓
Türkçe (Turc)	`tur_Latn`	✓	✓	✓
Kiswahili (Swahili)	`swh_Latn`	✓	✓	✓
日本語 (Japonais)	`jpn_Jpan`	✓	✓	✓
한국어 (Coréen)	`kor_Hang`	✓	✓	✓
हिन्दी (Hindi)	`hin_Deva`	✓	✓	✓

Bambara natif

Le bambara bénéficie du plus haut niveau de fidélité (transcription, traduction et voix conçues pour lui). La transcription détecte aussi automatiquement bien d'autres langues.

SDK & exemples

Il n'y a rien de spécial à installer : l'API est du REST standard, utilisable avec n'importe quel client HTTP.

Prérequis

Un client HTTP dans ton langage. En Python, requests ; en JavaScript, fetch (natif). Récupère la clé API et garde-la côté serveur.

Spécification & playground

Spec OpenAPI	/openapi.json — importable dans Postman, Insomnia ou un générateur de client.
Playground	/playground — teste chaque appel et copie le code généré.

# importer la spec dans Postman / Insomnia
curl -O https://api.kooma.ai/openapi.json

pip install requests
# puis reprends les exemples Python de chaque endpoint

// Node 18+ : fetch est natif, rien a installer.
// Reprends les exemples JavaScript de chaque endpoint.

Erreurs

Kooma utilise les codes HTTP standards. Les erreurs renvoient un corps JSON avec un message lisible et un code stable pour le traitement programmatique.

Statut	Code	Cause & résolution
400	`empty_input` · `empty_text` · `empty_file`	Le champ obligatoire est vide. Vérifie `input` / `text` / `file`.
400	`unsupported_format`	Format de sortie non pris en charge. Utilise `wav`.
401	`invalid_api_key`	Clé absente ou invalide. Vérifie l'en-tête `Authorization: Bearer sk-intermo-…`.
402	`insufficient_credits`	Crédit prépayé insuffisant. Recharge ton portefeuille.
403	`insufficient_scope`	La clé n'a pas l'autorisation nécessaire. Ajoute le scope (`tts`/`stt`/`mt`) ou crée une clé `inference`.
413	`file_too_large`	Fichier au-delà de 80 Mo. Compresse ou découpe le média.
422	`aucune_source`	Job vidéo sans source. Fournis `file` ou `source_url`.
429	`rate_limited`	Trop de requêtes. Attends la durée indiquée par l'en-tête `Retry-After`.
503	`tts_unavailable` · `stt_unavailable` · `mt_unavailable`	Moteur momentanément indisponible. Réessaie après le délai `Retry-After`. Non facturé.

Forme d'une erreur

Le champ error.code est stable et sûr à tester dans ton code ; error.message peut évoluer et sert à l'affichage/journalisation.

Quotas & limites

Le débit est encadré par compte et par clé. Quand tu dépasses, l'API renvoie 429 avec un en-tête Retry-After (secondes à attendre).

Limite	Valeur
Taille max d'un fichier	80 Mo
Longueur max d'un texte	5 000 caractères / requête
Plafond de dépense par clé	Configurable à la création (vide = illimité)
Débit par clé	Selon ton plan · dépassement → `429` + `Retry-After`

Bien gérer le 429

Mets en place un retry avec back-off : respecte Retry-After, espace tes appels, et lisse les pics côté file d'attente. Pour les gros volumes, ouvre plusieurs jobs de sous-titrage/doublage plutôt que d'envoyer un fichier géant.

Le solde et la consommation en temps réel sont visibles dans Usage et Portefeuille.

Changelog

2026-07	Doublage — nouvel endpoint `/dub/jobs` : traduction vocale de vidéos avec voix synchronisée, reprise possible depuis un job de sous-titrage.
2026-07	Catalogue de voix étendu — plus de 40 voix bambara, hommes et femmes.
2026-06	Sous-titrage multi-langues — `/subtitle/jobs` avec export `SRT`/`VTT`/`TTML` et ajout de langues sans re-transcrire.
2026-06	Langues internationales — transcription, traduction et synthèse étendues aux grandes langues (français, anglais, arabe, chinois…).
2026-06	API à clé — lancement de `/v1/audio/speech`, `/v1/audio/transcriptions` et `/v1/translations` avec facturation à l'usage.

Kooma · API — . Une question ? Écris-nous depuis la console. Retour à la console.