API de voz a texto

Convierte audio y vídeo en texto desde tu propio código. Una sola clave te da el pipeline completo: cualquier formato de entrada, detección automática de idioma (~99 idiomas), división de archivos largos en fragmentos y posprocesamiento con LLM — texto limpio, resúmenes, tareas y traducción.

Inicio rápido

1. Regístrate y confirma tu correo. 2. En tu cuenta, abre «Claves API» y crea una clave (se muestra solo una vez). 3. Envía tu primera petición:

Subir un archivo y esperar el resultado:

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

Con wait=true el servidor mantiene la conexión hasta ~90 segundos y devuelve el texto terminado en una sola petición: suficiente para la mayoría de archivos. Para grabaciones largas usa el flujo asíncrono de más abajo.

Autenticación

Cada petición necesita la cabecera Authorization: Bearer ora_sk_… . Las claves se crean en tu cuenta y puedes revocarlas en cualquier momento. Mantén la clave en secreto: cualquiera que la tenga gasta tus minutos.

Authorization: Bearer ora_sk_YOUR_KEY

Registro →

Crear una transcripción

POST /api/v1/transcriptions

POST /api/v1/transcriptions acepta multipart/form-data con un archivo, o JSON/formulario con una url — el archivo lo descargamos nosotros (hosts públicos, puertos 80/443, hasta 3 redirecciones). Exactamente una fuente por petición.

Parámetro	Descripción
`file`	Archivo de audio o vídeo (multipart/form-data). MP3, WAV, M4A, OGG, MP4, MOV y la mayoría de los demás formatos.
`url`	Enlace http(s) directo al archivo en lugar de subirlo.
`level`	Nivel de procesamiento: standard, premium o ultra. Por defecto, el mejor nivel de tu plan. Los niveles superiores usan modelos más potentes.
`mode`	Posprocesamiento opcional aplicado justo después de la transcripción: clean (quitar muletillas), summary (resumen), tasks (tareas) o translate (traducción). El resultado llega en mode_text junto al texto original.
`target_lang`	Idioma de destino para mode=translate, p. ej. “English” o “Español”.
`wait`	true — mantener la petición hasta que el resultado esté listo (hasta ~90 s). Si se agota el tiempo, recibirás un 202 con el id: consúltalo como de costumbre.

O pasar un enlace y pedir el resumen de una vez:

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

Códigos de éxito: 201 — tarea creada (sin wait), 200 — wait terminó con el resultado, 202 — wait agotó el tiempo, sigue consultando por id.

Obtener el resultado

GET /api/v1/transcriptions/{id}

Consulta GET /api/v1/transcriptions/{id} cada 1–3 segundos. Estados: queued → processing → done; error significa que el procesamiento falló (no pierdes minutos: la tarea no se completó), rejected significa que una regla de negocio la detuvo (cuota, duración).

Comprobar el estado / obtener el resultado:

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

Respuesta al terminar:

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

Posprocesar el texto

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

Cualquier transcripción terminada puede reprocesarse sin gastar minutos nuevos: POST /api/v1/transcriptions/{id}/process con mode y, para la traducción, target_lang. Hasta 20 procesamientos por transcripción.

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

Consulta tu cuota

GET /api/v1/usage

GET /api/v1/usage devuelve tu plan, el límite, los minutos usados y restantes, y cuándo se restablece la cuota. Llámalo antes de enviar archivos grandes.

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

Ejemplo 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"])

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

Límites

Los minutos se comparten con tu plan: Gratis — 5 min/día, Premium — 500 min/mes, Ultra — 1000 min/mes. Un archivo que no cabe en los minutos restantes se rechaza antes de procesarlo.
Un archivo: hasta 200 MB y hasta 120 minutos de audio.
Límites de frecuencia por clave: 10 peticiones de transcripción/procesamiento por minuto, 60 peticiones de estado por minuto.
Hasta 5 claves activas por cuenta; revoca en tu cuenta las que no uses.

Errores

Los errores llegan en JSON: {"error": {"code": "…", "message": "…"}}. Los códigos principales:

HTTP	Descripción
`400`	bad_request / invalid_level / invalid_mode / url_invalid / url_blocked / url_failed — un parámetro o la url es incorrecto; detalles en message.
`401`	Clave API ausente, inválida o revocada.
`402`	quota_exceeded — no quedan suficientes minutos en el plan; la respuesta incluye remaining_minutes.
`403`	email_unverified, level_not_allowed o llm_limit — confirma tu correo; el nivel solicitado supera tu plan; o se agotó el tope de 20 procesamientos de esa transcripción.
`404`	not_found — no existe una transcripción con ese id en esta clave API.
`409`	not_ready — la transcripción aún no está terminada; espera al estado done.
`413`	file_too_large / too_long — el archivo supera el límite de tamaño o duración.
`415`	unsupported_media — no pudimos decodificar audio del archivo.
`429`	rate_limited — demasiadas peticiones por minuto; baja el ritmo y reintenta.
`502`	llm_failed — falló el procesamiento del texto; reintenta más tarde.

¿Dudas?

Escríbenos en Telegram: @oratextbot — respondemos rápido y te ayudamos encantados con la integración.