API Speech-to-Text

Convertissez audio et vidéo en texte directement depuis votre code. Une seule clé vous donne tout le pipeline : n'importe quel format d'entrée, détection automatique de la langue (~99 langues), découpage des fichiers longs et post-traitement LLM — texte propre, résumés, tâches, traduction.

Démarrage rapide

1. Inscrivez-vous et confirmez votre e-mail. 2. Dans votre compte, ouvrez « Clés API » et créez une clé (affichée une seule fois). 3. Envoyez votre première requête :

Téléverser un fichier et attendre le résultat :

curl -X POST https://oratext.com/api/v1/transcriptions \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -F "file=@meeting.mp3" \
  -F "wait=true"

Avec wait=true, le serveur maintient la connexion jusqu'à ~90 secondes et renvoie le texte final en une seule requête — suffisant pour la plupart des fichiers. Pour les enregistrements longs, utilisez le flux asynchrone ci-dessous.

Authentification

Chaque requête doit inclure l'en-tête Authorization: Bearer ora_sk_… . Les clés se créent dans votre compte et peuvent être révoquées à tout moment. Gardez votre clé secrète : quiconque la détient consomme vos minutes.

Authorization: Bearer ora_sk_YOUR_KEY

Inscription →

Créer une transcription

POST /api/v1/transcriptions

POST /api/v1/transcriptions accepte soit du multipart/form-data avec un fichier, soit du JSON/formulaire avec un paramètre url — nous téléchargeons le fichier nous-mêmes (hôtes publics, ports 80/443, jusqu'à 3 redirections). Une seule source par requête.

Paramètre	Description
`file`	Fichier audio ou vidéo (multipart/form-data). MP3, WAV, M4A, OGG, MP4, MOV et la plupart des autres formats.
`url`	Lien http(s) direct vers le fichier, au lieu de le téléverser.
`level`	Niveau de traitement : standard, premium ou ultra. Par défaut, le meilleur niveau de votre offre. Plus le niveau est élevé, plus les modèles sont puissants.
`mode`	Post-traitement optionnel appliqué juste après la transcription : clean (supprimer les tics de langage), summary (résumé), tasks (tâches) ou translate (traduction). Le résultat est renvoyé dans mode_text, à côté du texte brut.
`target_lang`	Langue cible pour mode=translate, par exemple « English » ou « Français ».
`wait`	true — maintient la requête jusqu'à ce que le résultat soit prêt (jusqu'à ~90 s). Si le délai est dépassé, vous recevez un 202 avec l'id — interrogez ensuite le statut comme d'habitude.

Ou passer un lien — avec un résumé demandé au passage :

curl -X POST https://oratext.com/api/v1/transcriptions \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/podcast.mp3", "mode": "summary", "wait": "true"}'

Codes de succès : 201 — tâche créée (sans wait), 200 — wait terminé avec le résultat, 202 — délai de wait dépassé, continuez à interroger par id.

Récupérer le résultat

GET /api/v1/transcriptions/{id}

Interrogez GET /api/v1/transcriptions/{id} toutes les 1 à 3 secondes. Statuts : queued → processing → done ; error signale un échec de traitement (les minutes ne sont pas perdues — la tâche n'a pas abouti), rejected signale un refus par une règle métier (quota, durée).

Vérifier le statut / récupérer le résultat :

curl -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  https://oratext.com/api/v1/transcriptions/JOB_ID

Réponse une fois terminé :

{
  "id": "3f2b8c1e-5a70-4a3e-9c0f-1d2e3f4a5b6c",
  "status": "done",
  "level": "standard",
  "duration_sec": 184.2,
  "language": "ru",
  "mode": "summary",
  "text": "…full transcript…",
  "mode_text": "…summary…"
}

Post-traiter le texte

POST /api/v1/transcriptions/{id}/process

Toute transcription terminée peut être retraitée sans consommer de nouvelles minutes : POST /api/v1/transcriptions/{id}/process avec mode et, pour la traduction, target_lang. Jusqu'à 20 traitements par transcription.

curl -X POST https://oratext.com/api/v1/transcriptions/JOB_ID/process \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "translate", "target_lang": "English"}'

Vérifier votre quota

GET /api/v1/usage

GET /api/v1/usage renvoie votre offre, la limite, les minutes utilisées et restantes, ainsi que la date de réinitialisation du quota. Appelez-le avant d'envoyer de gros fichiers.

{
  "plan": "free",
  "period": "day",
  "limit_minutes": 5.0,
  "used_minutes": 1.2,
  "remaining_minutes": 3.8,
  "resets_at": "2026-08-06T00:00:00+00:00"
}

Exemple en Python :

import requests, time

API = "https://oratext.com/api/v1"
HEADERS = {"Authorization": "Bearer ora_sk_YOUR_KEY"}

with open("meeting.mp3", "rb") as f:
    r = requests.post(f"{API}/transcriptions", headers=HEADERS,
                      files={"file": f}, data={"mode": "summary", "wait": "true"})
job = r.json()
if not r.ok:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("done", "error", "rejected"):
    time.sleep(2)
    job = requests.get(f"{API}/transcriptions/{job['id']}", headers=HEADERS).json()

if job["status"] == "done":
    print(job["text"])
    print(job.get("mode_text"))
else:
    print("failed:", job["error"]["message"])

Exemple en JavaScript (Node 18+) :

const API = "https://oratext.com/api/v1";
const headers = { Authorization: "Bearer ora_sk_YOUR_KEY" };

const res = await fetch(`${API}/transcriptions`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/podcast.mp3", wait: "true" }),
});
let job = await res.json();
if (!res.ok) throw new Error(job.error.message);

while (!["done", "error", "rejected"].includes(job.status)) {
  await new Promise(r => setTimeout(r, 2000));
  job = await (await fetch(`${API}/transcriptions/${job.id}`, { headers })).json();
}
console.log(job.status === "done" ? job.text : job.error.message);

Limites

Les minutes sont partagées avec votre offre : Gratuit — 5 min/jour, Premium — 500 min/mois, Ultra — 1000 min/mois. Un fichier qui dépasse les minutes restantes est rejeté avant traitement.
Par fichier : jusqu'à 200 Mo et 120 minutes d'audio.
Limites de débit par clé : 10 requêtes de transcription/traitement par minute, 60 requêtes de statut par minute.
Jusqu'à 5 clés actives par compte ; révoquez celles que vous n'utilisez plus dans votre compte.

Erreurs

Les erreurs arrivent en JSON : {"error": {"code": "…", "message": "…"}}. Les principaux codes :

HTTP	Description
`400`	bad_request / invalid_level / invalid_mode / url_invalid / url_blocked / url_failed — un paramètre ou l'url est incorrect ; détails dans message.
`401`	Clé API absente, invalide ou révoquée.
`402`	quota_exceeded — plus assez de minutes sur l'offre ; la réponse contient remaining_minutes.
`403`	email_unverified, level_not_allowed ou llm_limit — confirmez votre e-mail ; le niveau demandé dépasse votre offre ; ou les 20 traitements de cette transcription sont épuisés.
`404`	not_found — aucune transcription avec cet id pour cette clé API.
`409`	not_ready — la transcription n'est pas encore terminée ; attendez le statut done.
`413`	file_too_large / too_long — le fichier dépasse la limite de taille ou de durée.
`415`	unsupported_media — impossible de décoder l'audio du fichier.
`429`	rate_limited — trop de requêtes par minute ; ralentissez puis réessayez.
`502`	llm_failed — le traitement du texte a échoué ; réessayez plus tard.

Des questions ?

Écrivez-nous sur Telegram : @oratextbot — nous répondons vite et vous aidons volontiers pour l'intégration.