Integración
API REST de transcripción – tres llamadas y listo
Sube, haz polling, recupera el resultado. JSON, marcas de tiempo por palabra, 99 idiomas, servidores propios en Alemania.
La API de DeepScript sigue el clásico patrón de job asíncrono: envías por POST un archivo de audio o vídeo a `/v1/transcriptions`, recibes un ID de job y luego haces polling en `/v1/transcriptions/{id}` cada pocos segundos o te notificas por webhook. La autenticación se realiza mediante una cabecera `X-API-KEY`; las claves empiezan por `ds_live_` y se generan en el panel. La respuesta contiene el texto completo, las marcas de tiempo por palabra con puntuaciones de confianza, el idioma detectado, las etiquetas de hablantes y el coste calculado. Los formatos de exportación (TXT, SRT, VTT, JSON) están disponibles en `/v1/transcriptions/{id}/export?format=srt`. La especificación OpenAPI 3.1 completa está en `/openapi.json`, una interfaz Scalar interactiva en `/docs`.
Ver la especificación OpenAPI 3.1Lo que puedes crear
- Sube archivos de audio y vídeo de hasta 500 MB (mp3, wav, flac, ogg, m4a, aac, mp4, mkv, webm, mov).
- Marcas de tiempo precisas por palabra con confianza por palabra – perfectas para subtítulos e integraciones con editores.
- Diarización de hablantes en ambos niveles, optimización de dialectos DACH en el modelo Premium.
- Custom Vocabulary por solicitud – nombres de empresas, términos médicos y nombres propios se reconocen correctamente.
- Formatos de exportación bajo demanda: TXT, SRT, VTT, JSON. Sin recodificación en el lado del cliente.
- Callbacks de webhook en `transcription.completed` – el polling es opcional, no se requiere long-polling.
Ejemplos de código
# Upload an audio file and start a Premium transcription job
curl -X POST https://api.deepscript.com/v1/transcriptions \
-H "X-API-KEY: ds_live_xxx" \
-F "file=@meeting.mp3" \
-F "model=premium" \
-F "language=de"
# Response:
# {
# "id": "8b1f2e4a-9c3d-4f7e-a1b2-1234567890ab",
# "status": "queued",
# "progress": 0,
# "model": "premium",
# "createdAt": "2026-06-09T10:14:22Z"
# }
# Poll until done
curl https://api.deepscript.com/v1/transcriptions/8b1f2e4a-9c3d-4f7e-a1b2-1234567890ab \
-H "X-API-KEY: ds_live_xxx"
# Download as SRT
curl -o meeting.srt \
"https://api.deepscript.com/v1/transcriptions/8b1f2e4a-9c3d-4f7e-a1b2-1234567890ab/export?format=srt" \
-H "X-API-KEY: ds_live_xxx"import { readFile } from "node:fs/promises";
const API_KEY = process.env.DEEPSCRIPT_API_KEY; // "ds_live_xxx"
const BASE = "https://api.deepscript.com/v1";
async function transcribe(filePath) {
const buffer = await readFile(filePath);
const blob = new Blob([buffer], { type: "audio/mpeg" });
const form = new FormData();
form.append("file", blob, "meeting.mp3");
form.append("model", "premium");
form.append("language", "de");
const created = await fetch(`${BASE}/transcriptions`, {
method: "POST",
headers: { "X-API-KEY": API_KEY },
body: form,
}).then((r) => r.json());
// Poll every 3 seconds until done
while (true) {
await new Promise((r) => setTimeout(r, 3000));
const job = await fetch(`${BASE}/transcriptions/${created.id}`, {
headers: { "X-API-KEY": API_KEY },
}).then((r) => r.json());
if (job.status === "completed") return job.result;
if (job.status === "failed") throw new Error(job.errorMessage);
}
}
const result = await transcribe("./meeting.mp3");
console.log(result.text);import os
import time
import requests
API_KEY = os.environ["DEEPSCRIPT_API_KEY"] # "ds_live_xxx"
BASE = "https://api.deepscript.com/v1"
HEADERS = {"X-API-KEY": API_KEY}
def transcribe(path: str) -> dict:
with open(path, "rb") as f:
created = requests.post(
f"{BASE}/transcriptions",
headers=HEADERS,
files={"file": f},
data={"model": "premium", "language": "de"},
timeout=120,
).json()
job_id = created["id"]
while True:
time.sleep(3)
job = requests.get(
f"{BASE}/transcriptions/{job_id}", headers=HEADERS, timeout=30
).json()
if job["status"] == "completed":
return job["result"]
if job["status"] == "failed":
raise RuntimeError(job["errorMessage"])
result = transcribe("meeting.mp3")
print(result["text"])Configuración en pocos pasos
- 1
Generar una clave API
Genera una clave en el panel en Ajustes → Seguridad. La clave se muestra solo una vez y empieza por `ds_live_`. Guárdala en tu aplicación como la variable de entorno `DEEPSCRIPT_API_KEY`.
- 2
Enviar la solicitud de subida
Subida multipart a POST `/v1/transcriptions` con los campos `file`, `model` (standard/premium) y, opcionalmente, `language` (ISO 639-1) más `vocabularyId`. Recibes un ID de job de inmediato (HTTP 202).
- 3
Hacer polling o esperar el webhook
Llama a GET `/v1/transcriptions/{id}` cada 2-5 segundos, o registra un webhook en `transcription.completed`. Regla general: 1 minuto de audio = 5-15 segundos de procesamiento en Standard, algo más en Premium.
- 4
Recuperar o exportar el resultado
Cuando `status: 'completed'`, el campo `result` contiene el texto completo, las palabras con marcas de tiempo y las etiquetas de hablantes. Para exportar SRT/VTT/TXT/JSON: GET `/v1/transcriptions/{id}/export?format=srt`.
Preguntas frecuentes
¿Cuáles son los límites de tasa?
100 solicitudes por minuto por clave API en llamadas autenticadas, 30/min sin autenticación. La respuesta incluye las cabeceras `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset`. Al superarlas recibes un HTTP 429 con una cabecera Retry-After.
¿Admiten claves de idempotencia?
Sí – envía `Idempotency-Key: <uuid>` como cabecera en POST `/v1/transcriptions`. Las claves idénticas en un plazo de 24 horas devuelven la misma respuesta sin iniciar un segundo job. Recomendado para reintentos ante problemas de red.
¿Qué intervalo de polling debo usar?
Recomendamos 2-5 segundos. Para audios más largos (>30 min) cada 10 segundos es suficiente. Si prefieres evitar el polling, usa webhooks (`/v1/webhooks`) o el stream de Server-Sent Events en `/v1/transcriptions/{id}/events`.
¿Qué ocurre con un job fallido?
El estado pasa a `failed` y el campo `errorMessage` contiene una cadena Problem Details conforme a la RFC 7807. Causas habituales: archivo demasiado corto (<1 s), sin audio detectable, formato no admitido. No se cobra por los jobs fallidos.
¿Hay un SDK oficial?
Por ahora ofrecemos la especificación OpenAPI 3.1 en `/openapi.json` – usa `openapi-generator-cli` u `openapi-typescript` para generar un cliente tipado en cualquier lenguaje. Los SDK oficiales para TypeScript y Python están en preparación.
¿Listo para llevarlo a producción?
Crea una cuenta, genera una clave API y a producir. Tres transcripciones gratis para probar. Documentación OpenAPI 3.1 completa en api.deepscript.com/docs.