Kooma API
English Clés API S'inscrire

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

Client Python

Sans dépendance : la bibliothèque standard suffit. Copiez, collez, c'est prêt.

import json, time, urllib.request, urllib.error

class Kooma:
    def __init__(self, cle, base="https://api.kooma.ai/v1"):
        self.cle, self.base = cle, base

    def _appel(self, chemin, corps=None, methode="GET", brut=False):
        données = json.dumps(corps).encode() if corps is not None else None
        entêtes = {"Authorization": f"Bearer {self.cle}"}
        if données:
            entêtes["Content-Type"] = "application/json"
        rq = urllib.request.Request(self.base + chemin, data=données,
                                    headers=entêtes, method=methode)
        for tentative in range(5):
            try:
                with urllib.request.urlopen(rq, timeout=120) as r:
                    return r.read() if brut else json.loads(r.read())
            except urllib.error.HTTPError as e:
                # 429 : on respecte Retry-After plutôt que de réessayer à l'aveugle.
                if e.code == 429 and tentative < 4:
                    time.sleep(int(e.headers.get("Retry-After") or 2 ** tentative))
                    continue
                raise

    # --- appels synchrones ---
    def voix(self):
        return self._appel("/voices")

    def parler(self, texte, voice, response_format="wav"):
        return self._appel("/audio/speech", {"input": texte, "voice": voice,
                                             "response_format": response_format}, "POST", brut=True)

    def traduire(self, texte, source, cible):
        return self._appel("/translations", {"text": texte, "source": source,
                                             "target": cible}, "POST")["translations"][0]["text"]

    # --- job asynchrone : création, attente, récupération ---
    def attendre(self, chemin_job, intervalle=5, limite=1800):
        """Interroge jusqu'à un état terminal. Préférez un webhook si vous le pouvez :
        cette boucle existe pour les cas où vous n'avez pas de serveur joignable."""
        début = time.time()
        while time.time() - début < limite:
            job = self._appel(chemin_job)
            if job.get("status") in ("done", "error"):
                return job
            time.sleep(intervalle)
        raise TimeoutError("le job n'a pas abouti dans le délai imparti")


k = Kooma("sk-intermo-YOUR_KEY")
open("sortie.wav", "wb").write(k.parler("Aw ni ce", voice="modibo"))
print(k.traduire("Bonjour", "fra_Latn", "bam_Latn"))

Client JavaScript

Sans dépendance non plus : fetch natif, Node 18+ ou navigateur (côté serveur uniquement — ne mettez jamais votre clé dans du code exécuté par le navigateur).

class Kooma {
  constructor(cle, base = "https://api.kooma.ai/v1") { this.cle = cle; this.base = base; }

  async appel(chemin, { corps, methode = "GET", brut = false } = {}) {
    const entetes = { Authorization: `Bearer ${this.cle}` };
    if (corps) entetes["Content-Type"] = "application/json";
    for (let tentative = 0; tentative < 5; tentative++) {
      const r = await fetch(this.base + chemin, {
        method: methode, headers: entetes,
        body: corps ? JSON.stringify(corps) : undefined,
      });
      // 429 : on respecte Retry-After au lieu de réessayer à l'aveugle.
      if (r.status === 429 && tentative < 4) {
        const attente = parseInt(r.headers.get("Retry-After") || 2 ** tentative, 10);
        await new Promise((s) => setTimeout(s, attente * 1000));
        continue;
      }
      if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
      return brut ? Buffer.from(await r.arrayBuffer()) : r.json();
    }
  }

  voix()                          { return this.appel("/voices"); }
  parler(texte, voice)            { return this.appel("/audio/speech",
                                      { corps: { input: texte, voice }, methode: "POST", brut: true }); }
  async traduire(texte, source, cible) {
    const d = await this.appel("/translations",
                { corps: { text: texte, source, target: cible }, methode: "POST" });
    return d.translations[0].text;
  }
}

// Enveloppé dans une fonction asynchrone : `await` au premier niveau ferait basculer
// Node en mode module ES, où `require` n'existe pas. Fonctionne tel quel dans les deux cas.
(async () => {
  const fs = require("fs");
  const k = new Kooma("sk-intermo-YOUR_KEY");
  fs.writeFileSync("sortie.wav", await k.parler("Aw ni ce", "modibo"));
})();

Vérifier une signature de webhook

C'est le point où une intégration se trompe le plus souvent, et l'erreur y est silencieuse : une signature mal vérifiée laisse passer n'importe qui.

import hmac, hashlib, time

def signature_valide(corps: bytes, entete: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in entete.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False                                   # rejoue d'une livraison capturée
    attendu = hmac.new(secret.encode(), f"{parts['t']}.".encode() + corps,
                       hashlib.sha256).hexdigest()
    return hmac.compare_digest(attendu, parts["v1"])   # comparaison en temps constant
↑↓ naviguer↵ ouvriresc fermer