POST/api/mod/transcripcion/{espacio}/transcripciones

Transcribe un audio

Subes una nota de voz o un audio y te devuelve lo que se dice, en texto. Contesta cuando termina, en la misma petición: no hay nada que consultar después.

PERMISOescribe
CRÉDITOSno gasta
AUTENTICACIÓNBearer bth_…

PARÁMETROS

CAMPO	TIPO	REQUERIDO	QUÉ ES
espacio	string	SÍ	El id del espacio (sale en GET /api/companies). Tiene que tener el módulo Transcripción.

CUERPO · MULTIPART/FORM-DATA

CAMPO	TIPO	REQUERIDO	QUÉ ES
archivo	archivo	SÍ	El audio, uno por petición: hasta 25 MB y 120 segundos. OGG/Opus (las notas de voz de WhatsApp), MP3, M4A, WAV y otros formatos de audio; de un vídeo se transcribe su sonido.
idioma	string	no	El idioma del audio, en código de dos letras: "es", "en", "pt"… Por defecto "es".
duracion_max_s	number	no	Tu propio tope de duración, en segundos (mínimo 1). Un audio más largo da 422 sin transcribirse. Por encima de 120, cuenta 120.

RESPUESTA 200

CAMPO	TIPO	QUÉ ES
texto	string	Lo que se dice en el audio. Vacío si no se oye ninguna palabra.
vacio	boolean	`true` si el audio no tiene voz (silencio o ruido). Es un resultado válido, no un error: no reintentes.
idioma	string \| null	El idioma con el que se transcribió.
duracion_s	number	Lo que dura el audio, en segundos, con dos decimales.
latencia_ms	integer	Lo que tardó la transcripción, en milisegundos.

CÓDIGOS DE ERROR DEL AUDIO

CAMPO	TIPO	QUÉ ES
demasiado_grande	413	El archivo pasa de 25 MB. Recórtalo o comprímelo.
demasiado_largo	422	Dura más de 120 s, o más que tu duracion_max_s. Pide a tu usuario un audio más corto.
no_soportado	422	No se reconoce como audio, o no trae pista de sonido. No reintentes.
audio_invalido	422	Llegó vacío, está dañado o no se pudo leer entero. No reintentes con el mismo.
ocupado	503	Hay muchas transcripciones en curso. Reintenta en unos segundos.
motor_no_listo	503	El servicio está arrancando. Reintenta en un momento.

ERRORES DE ESTA RUTA · SIEMPRE {"detail": …}

STATUS	CUÁNDO	DETAIL LITERAL
403	El espacio no tiene el módulo Transcripción	módulo no habilitado para este espacio.
403	La clave es de solo lectura	Tu cuenta es de solo lectura en este espacio.
413	El archivo pasa de 25 MB	{"codigo": "demasiado_grande", "detalle": "el audio supera 25 MB"}
422	Dura más de 120 s, o más que tu duracion_max_s	{"codigo": "demasiado_largo", "detalle": …}
422	No es audio, o no trae pista de sonido	{"codigo": "no_soportado", "detalle": …}
422	Llegó vacío o no se pudo decodificar	{"codigo": "audio_invalido", "detalle": …}
422	Falta el campo archivo (detail es una lista)	—
503	Hay muchas transcripciones en curso: reintenta en unos segundos	{"codigo": "ocupado", "detalle": "todas las transcripciones en curso; reintente"}
503	El servicio está arrancando: reintenta en un momento	{"codigo": "motor_no_listo", "detalle": …}

Y los de cualquier ruta —clave inválida, cuenta no al día, IP, límites—, en Errores, límites y créditos.

CONVIENE SABER

Los errores del audio traen detail como objeto: codigo, para tu programa, y detalle, una frase. Decide por codigo: ver códigos.
Pide una clave escribe, aunque no cambia nada del espacio: es un POST. No gasta créditos.
Bentho no guarda ni el audio ni el texto: te los devuelve y los olvida. Si quieres conservarlos, guárdalos tú.
Suele tardar unos segundos; un audio de dos minutos, algo más. Para varios audios, una petición por cada uno.