Transcripción con Scribe One: de voz a texto en una petición

Scribe One es el endpoint más pequeño de la plataforma y aquel sobre el que más a menudo se construye lo que no toca. Recibe un archivo de audio y devuelve las palabras que contiene. No un archivo de subtítulos, ni una transcripción con hablantes etiquetados, ni un stream: las palabras. Casi todo el trabajo de una función de transcripción consiste en organizar tu lado del pipeline en torno a ese hecho, así que aquí tienes el endpoint tal como es y el flujo de trabajo que le encaja.

La petición completa

Un POST multipart, sin job que consultar y sin webhook:

curl https://eroq.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -F model=eroq-scribe-one \
  -F [email protected]

Y la respuesta completa:

{
  "model": "eroq-scribe-one",
  "text": "That noise is the reactor missing its coolant flush.",
  "usage": { "audio_seconds": 4.2, "credits_spent": 1, "credits_remaining": 882 }
}

La parte file tiene que ser wav o mp3. Los demás contenedores se rechazan con unsupported_format en lugar de transcodificarse en silencio, así que si capturas desde un navegador, graba WAV con WebAudio o recodifica en el cliente antes de subir: un .ogg o un .m4a recién salido de una grabadora será rechazado. La lista completa de parámetros está en la referencia de transcripción.

Un crédito por minuto

Scribe One cobra 1 crédito por minuto de audio iniciado. La duración se lee del propio archivo antes de transcribir, y la respuesta la indica junto al cargo como usage.audio_seconds, así que siempre puedes contrastar la factura con el audio que enviaste.

Lo que eso significa en la práctica:

• Un mensaje de voz de cuatro segundos cuesta 1 crédito. Uno de 59 segundos, lo mismo; 61 segundos son 2 créditos.
• Una hora de audio son 60 créditos, la envíes como la envíes. Dividir solo cuesta el redondeo: cada petición redondea hacia arriba su último minuto, así que veinte clips de 30 segundos son 20 créditos, mientras que esos mismos diez minutos en un solo archivo serían 10 créditos.
• Las notas de voz son el caso barato por diseño. Una bandeja de entrada llena de mensajes cortos cuesta un crédito por mensaje, y eso es lo que hace asequible transcribirlo todo por si acaso: cada nota de voz, cada clip de una biblioteca.

Detección automática del idioma, y cuándo indicarlo tú

El idioma se detecta a partir del audio. No hay ningún parámetro obligatorio ni un modelo por idioma que elegir, así que una bandeja de entrada multilingüe funciona sin lógica de enrutamiento por tu parte.

El campo opcional language acepta un código ISO (en, fr, de) como pista, no como restricción. Merece la pena enviarlo exactamente en dos situaciones: cuando ya conoces el idioma por el contexto (el ajuste del perfil de un usuario, un canal que siempre está en el mismo idioma) y cuando un audio corto o con ruido se detecta mal. Un clip de cuatro palabras le da muy poco material al detector, y una pista lo arregla gratis.

El tope de 8 MB, y cómo quedarte por debajo

Las subidas tienen un tope de 8 MB, que la documentación calcula en unos ocho minutos de audio comprimido. Está pensado a propósito para material de la duración de un mensaje de voz, no para archivos enteros de grabaciones, y es la restricción en torno a la que diseñas.

El bitrate es la palanca. Ocho megas son unos ocho minutos al bitrate típico de un podcast; recodifica a 64 kbps mono y en los mismos 8 MB cabe aproximadamente el doble, sin pérdida apreciable para la voz. Así, una grabación larga se convierte en unas pocas peticiones:

ffmpeg -i episode.mp3 -c:a libmp3lame -b:a 64k -ac 1 \
  -f segment -segment_time 600 part%02d.mp3

Los segmentos de diez minutos a 64 kbps mono rondan los 4.8 MB cada uno: holgadamente dentro del tope y con margen de sobra. Un episodio de cuarenta minutos son cuatro peticiones de exactamente diez minutos, así que 40 créditos en total, lo mismo que costaría de una sola pieza, porque los segmentos de minutos enteros no dejan redondeo que pagar.

Una advertencia sobre la segmentación de duración fija: un corte puede caer en mitad de una palabra, y cada mitad se transcribirá como algo ligeramente erróneo. Si la costura importa, segmenta por silencios en lugar de por tiempo, o solapa los segmentos uno o dos segundos y elimina el solapamiento al unir el texto.

La transcripción comparte el límite de frecuencia de los medios (6 peticiones por minuto y por clave en un espacio de trabajo gratuito, multiplicado según tu plan), que es mucho más de lo que necesita un episodio segmentado y conviene conocer si vas a transcribir un archivo antiguo entero. Las peticiones fallidas se reembolsan solas, así que un corte de red a mitad del proceso no te deja pagando por nada.

Subtitular tu propia narración

El caso habitual: tienes un MP3 y ningún guion. Quizá lo grabaste tú, quizá es un episodio antiguo, quizá es una nota de voz que ahora quieres en texto. Transcríbelo y luego haz la sincronización en la herramienta que ya maneja tu línea de tiempo.

Ten clara la división del trabajo, porque aquí es donde se espera demasiado. Scribe One devuelve un bloque de texto. No devuelve un SRT, ni un VTT, ni tiempos por palabra, así que no puede colocar subtítulos en una línea de tiempo por sí solo. Lo que te da es el texto exacto, que es justo lo que peor hacen las herramientas de subtítulos y lo que más te cuesta teclear. Pégalo en el alineador de subtítulos de tu editor y deja que él haga la pasada de sincronización.

Si divides el audio tú mismo, obtienes una sincronización aproximada gratis: un segmento que empieza en el minuto 10 produce texto que va en el minuto 10. La precisión a nivel de cada subtítulo sigue viniendo del alineador, pero los marcadores de capítulo, las notas del episodio y un índice con búsqueda solo necesitan el anclaje por segmento que ya tienes.

La dirección contraria cierra el círculo: transcribe el mensaje de voz de un usuario, respóndelo con una chat completion y devuelve la respuesta en audio con /v1/audio/speech. Voz de entrada, razonamiento en texto y voz de salida son tres llamadas sin infraestructura de streaming; TTS para personajes de IA cubre la parte de la voz y sus trucos de latencia.

Los límites, sin rodeos

Construye alrededor de ellos, no contra ellos:

• Sin diarización. La respuesta no tiene etiquetas de hablante ni límites de turno. Si necesitas saber quién habló, graba a los participantes en pistas separadas, transcribe cada una y luego intercálalas por marca de tiempo por tu lado.
• Sin marcas de tiempo por palabra ni por segmento. La respuesta es text. La sincronización sale de cómo cortas el audio, o de un alineador posterior.
• Sin archivo de subtítulos. Ni SRT, ni VTT, ni lista de subtítulos en JSON.
• Sin streaming ni transcripción en tiempo real. Es una petición y una respuesta sobre un archivo terminado, no un socket en vivo.
• Sin comando de CLI. La CLI de eroq cubre imagen, video y voz; la transcripción es un curl o una llamada del SDK.

Nada de esto es una pista sobre la hoja de ruta: es lo que hace el endpoint hoy, y diseñar una función sobre suposiciones que no cumple es la forma más cara de descubrirlo. Si tu producto necesita etiquetas de hablante en una llamada de grupo, la respuesta honesta son pistas separadas, no un parámetro.

Para ver todo lo que ofrece la parte de voz de la API, la página de la plataforma de voz reúne los endpoints en un solo sitio, voz a texto es la definición en un párrafo y en precios están los paquetes de créditos si estás calculando una transcripción masiva.

Preguntas frecuentes

¿Cuánto cuesta la transcripción con Scribe One?

1 crédito por minuto de audio iniciado, con un mínimo de un minuto por petición. Una nota de voz cuesta 1 crédito; una hora de audio, 60 créditos. La duración medida vuelve como usage.audio_seconds, y una petición fallida se reembolsa sola.

¿Qué formatos de audio acepta el endpoint de transcripción?

Solo WAV y MP3. Cualquier otro formato devuelve unsupported_format en lugar de convertirse, así que recodifica antes por tu lado: grabar WAV con WebAudio en el navegador es la solución habitual para un pipeline de captura.

¿Puedo obtener marcas de tiempo o etiquetas de hablante?

No. La respuesta contiene el texto transcrito y el bloque de uso, sin tiempos por palabra, sin segmentos y sin diarización. Corta el audio en desfases conocidos para una sincronización aproximada, usa pistas separadas por hablante cuando necesites etiquetas y pasa un alineador después cuando los subtítulos tengan que ir al fotograma exacto.

¿Detecta el idioma automáticamente?

Sí, la detección del idioma es automática y no necesita ningún parámetro. Puedes pasar un código ISO en language como pista cuando el audio es corto o tiene ruido, o cuando ya conoces el idioma por el contexto del usuario, lo que mejora la precisión sin pagar nada más.

¿Tienes un archivo de audio y una clave? Un curl te da el texto. Consigue una clave de API y los primeros 50 créditos cubren cincuenta minutos de audio antes de que gastes nada.