Transcripción de audio
Convierte notas de voz en texto con el SDK, en una sola llamada para audios cortos o como tarea en segundo plano con progreso para los largos.
Actualizado el . 3 min de lectura
Incluido en los planes Profesional y Avanzado. Ver precios
La transcripción convierte en texto una nota de voz: la persona explica su problema hablando y tu aplicación recibe el texto para rellenar un formulario o un mensaje. Hay tres formas de pedirla, según lo largo que sea el audio y si quieres enseñar el progreso. Funciona con la clave de tu aplicación externa, siempre desde tu servidor.
Todas exigen el scope support:tickets:ai, además del aplicativo Tickets de soporte y la capacidad «Tickets propios» en el plan. El audio va en base64, con su nombre y extensión (webm, mp4, mp3 o wav).
Tres formas de transcribir
transcribe
En una llamada
streamTranscription
En tiempo real
requestTranscription
Paso a paso
Si además quieres que la IA proponga el ticket, no hace falta transcribir antes: manda el audio directamente a las sugerencias con IA y el resultado traerá la transcripción y la propuesta.
En una llamada
transcribe espera a tener el texto y lo devuelve: { transcription } en JavaScript y el texto directamente en Python.
Máximo de 10 MB
La llamada directa rechaza los audios de más de 10 MB con un 400 y errorCode AI_AUDIO_TOO_LARGE. Para archivos mayores usa la tarea en segundo plano, cuyo límite es el de la petición: 50 MB de cuerpo, teniendo en cuenta que el audio en base64 ocupa un tercio más que el original.
import { readFile } from 'node:fs/promises';
const audioBase64 = (await readFile('./nota-de-voz.webm')).toString('base64');
const { transcription } = await sdk.ai.transcribe(audioBase64, 'nota-de-voz.webm');
console.log(transcription);En tiempo real
streamTranscription encola la tarea, abre una conexión de eventos (Server-Sent Events) y devuelve el texto cuando termina: { transcription } en JavaScript y el texto en Python. A diferencia de las sugerencias, no ofrece cancelación. Opciones: función de progreso (onProgress, on_progress), función para errores no fatales (onError, on_error) y tiempo máximo, 120 s por defecto (timeout, en milisegundos en JavaScript y en segundos en Python con SseStreamOptions).
En Node.js necesitas un polyfill de EventSource (por ejemplo, eventsource asignado a globalThis.EventSource). La conexión lleva la credencial en la dirección: úsala solo desde tu servidor.
const { transcription } = await sdk.ai.streamTranscription(audioBase64, 'reunion.webm', {
onProgress: (p) => console.log(`Transcribiendo: ${p}%`),
timeout: 180000, // 3 minutos para audios largos
});Paso a paso
requestTranscription encola la tarea y devuelve su identificador ({ jobId } en JavaScript, el texto del identificador en Python). getTranscriptionStatus devuelve el estado (pending, processing, completed o failed), el progreso de 0 a 100 y, al terminar, transcription o error.
const { jobId } = await sdk.ai.requestTranscription(audioBase64, 'entrevista.mp3');
let status = await sdk.ai.getTranscriptionStatus(jobId);
while (status.status === 'pending' || status.status === 'processing') {
await new Promise((r) => setTimeout(r, 1000));
status = await sdk.ai.getTranscriptionStatus(jobId);
}
if (status.status === 'completed') console.log(status.transcription);
else console.error(status.error);Si consumes los eventos sin el SDK, ten en cuenta que todos llegan con el tipo genérico message y el tipo real va en el campo event del JSON. El formato está en Endpoints de transcripción.