AI — Transcribe

AI — Transcribe

Tipo: ai-transcribe  ·  Paquete: AI Activities v1.4.1  ·  Salida: string

Desde: v1.3.0

Convierte un archivo de audio en texto: una nota de voz que llegó por WhatsApp, la grabación de una llamada, el audio de una reunión. Devuelve la transcripción como texto, lista para guardarla, buscar en ella o pasársela a AI — Complete o AI — Extract. En el Designer en español aparece como IA — Transcribir.

A diferencia de las otras actividades del paquete, no usa Claude: trabaja con OpenAI o con cualquier servicio que exponga la misma API de transcripción (por ejemplo, un Whisper propio instalado en tus servidores).

Cómo funciona

1. Lee el archivo de path y comprueba que exista, que tenga una extensión de audio admitida y que no pase de 25 MB.
2. Lo envía al servicio de transcripción con el model, el language y el prompt que indiques: con tu credential, directo a tu servicio; sin ella, por la transcripción incluida en tu plan a través de Zoan Cloud.
3. Devuelve el texto transcrito, sin espacios sobrantes al principio ni al final.

Con tu credencial, el servicio se toma de ella: si guarda un campo base_url, la petición va a esa dirección (tu Whisper propio); si no, va a OpenAI. A base_url se le agrega /v1 al final, salvo que la dirección ya termine en un segmento de versión como /v1: http://voz.local:8000 y http://voz.local:8000/v1 llegan al mismo lugar. La clave se lee del valor de la credencial o, en una integración, de sus campos api_key, value, apiKey, key o token.

Esperas y reintentos: timeout es la espera máxima de la transcripción. Con la transcripción incluida, los fallos pasajeros (congestión, error del servicio, tiempo agotado, red) se reintentan hasta 3 veces con esperas crecientes. Con tu propio servicio no hay reintentos automáticos: usa un Retry si lo necesitas.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
path	string	—	Ruta del archivo de audio: .ogg, .oga, .opus, .mp3, .m4a, .mp4, .wav, .webm, .flac, .mpeg o .mpga. Hasta 25 MB.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
credential	credential	—	Tu propia integración de OpenAI (api_key y, si usas un Whisper propio, base_url). Vacía usa la transcripción incluida en tu plan de Zoan Cloud: nada que configurar, y el consumo aparece en Consumo de IA. Opcional desde la versión 1.4.0.
model	string	"gpt-4o-mini-transcribe"	Id del modelo de transcripción. Con la transcripción incluida, vacío usa el modelo predeterminado del plan. Con un Whisper propio, usa whisper-1.
language	string	—	Idioma del audio en código ISO 639-1 ("es", "en", "pt"). Mejora la precisión; vacío detecta el idioma solo.
prompt	string	—	Pista con nombres, siglas o vocabulario que pueden aparecer en el audio.
timeout	int	600	Segundos de espera, entre 1 y 3600.
usageVariable	string	—	Nombre de una variable (declárala como objeto) donde guardar el consumo: { model, bytes, seconds }.

Sin credencial: la transcripción incluida en tu plan

credential es opcional desde la versión 1.4.0:

• Vacía: si tu plan de Zoan Cloud incluye IA, la actividad usa la cuenta de Zoan a través de Zoan Cloud. No creas claves ni contratas un proveedor: el robot trabaja desde la primera ejecución, y lo que consume aparece en Consumo de IA y cuenta en el consumo incluido en tu plan. Funciona en las ejecuciones de Zoan Cloud y en las pruebas del Designer con tu sesión abierta.
• Con tu credencial: la llamada va directo del robot a tu proveedor, con tu clave y tus condiciones. Zoan Cloud registra solo el consumo (modelo y segundos) para que lo veas en el mismo panel; el contenido nunca pasa por Zoan Cloud y ese uso no descuenta del consumo incluido. Un servicio propio que no es la API de OpenAI se registra aparte, para que no se costee como OpenAI.

Con la transcripción incluida puedes usar los modelos de transcripción de OpenAI del catálogo de Zoan Cloud, y cuenta la duración que reporta el servicio de transcripción cuando la da (los modelos Whisper). Con los modelos gpt-4o-*-transcribe, que no la reportan, la duración se mide del propio archivo cuando el formato lo permite y, si no, se estima por su tamaño. El audio viaja por Zoan Cloud hasta el proveedor sin guardarse —solo se registra el consumo.

El audio no pasa por el enmascarado de datos personales: si eso importa, transcribe primero y procesa el texto con AI — Complete o AI — Extract, que sí enmascaran.

Salida

Devuelve un string con el texto transcrito, sin espacios al principio ni al final. Si el servicio responde sin texto, devuelve una cadena vacía.

Si indicas usageVariable, esa variable recibe además un objeto con el modelo usado (model), el tamaño del archivo en bytes (bytes) y la duración del audio en segundos (seconds, con un decimal). La duración se lee del propio archivo cuando el formato lo permite (Ogg/Opus, WAV, MP4/M4A); en los demás casos es una estimación a partir del tamaño.

El prompt ayuda con las palabras raras

El modelo transcribe bien el lenguaje de todos los días, pero puede equivocarse con nombres propios, marcas, siglas o términos de tu sector. El prompt no es una instrucción, sino una lista de palabras que probablemente aparezcan:

prompt → "Distribuidora Andina, Sra. Valencia, orden de compra, NIT, nota crédito"

Con eso, las siglas y los términos del sector salen bien escritos, y el nombre de la empresa y el apellido de la clienta se escriben como son.

Ejemplo

Transcribir una nota de voz con la transcripción incluida y resumirla:

AI — Transcribe   path     = rutaNotaDeVoz
                  language = "es"
                  → output: transcripcion
AI — Complete     system = "Resume el mensaje en una línea."
                  prompt = transcripcion
                  → output: resumen

Transcribir las grabaciones de una carpeta con tu propia integración y registrar cuántos segundos se procesaron:

For Each   items = grabaciones   itemVariable = audio
 └─ activities:
      AI — Transcribe   credential    = credential("openai")
                        path          = audio
                        usageVariable = consumo
                        → output: texto
      Log   message = "Transcritos " + consumo["seconds"] + " s de " + audio

Indica el idioma si lo conoces

Dejar language vacío funciona, pero en audios cortos o con ruido el modelo puede confundir el idioma. Si todos tus audios están en español, pon "es".

Audios de más de 25 MB

Una nota de voz o una llamada normal quedan muy por debajo; para grabaciones largas, pártelas en trozos o comprímelas (por ejemplo, a .mp3 u .ogg) antes de transcribir.

Errores comunes

Mensaje	Causa y solución
'path' es obligatorio.	No se indicó el archivo.
No se encontró el archivo de audio.	La ruta de path no existe en la máquina donde corre el robot.
Extensión de audio no admitida '…'. Usa .ogg, .opus, .mp3, .m4a, .wav, .webm o .flac.	El archivo no es de un formato admitido. Conviértelo a .mp3, .ogg o .wav.
El audio supera los 25 MB. Divídelo o comprímelo primero.	El archivo es demasiado grande. Pártelo o comprímelo.
'timeout' debe estar entre 1 y 3600 segundos. Recibido: …	Valor de timeout fuera de rango o no entero.
La credencial no contiene una API key. Usa una integración de OpenAI de Centro › Recursos › Integraciones en Zoan Cloud.	La credencial existe pero no guarda la API key.
El servicio de transcripción respondió HTTP 401: …	Con tu credencial: la API key no es válida o fue revocada. Otros códigos traen el detalle del servicio.
Elige una credencial o activa la IA incluida en tu plan. La IA incluida va a través de Zoan Cloud: …	Sin credencial y sin Zoan Cloud en la ejecución (por ejemplo, una prueba sin sesión). Abre tu sesión o usa tu integración.
Elige una credencial o activa la IA incluida en tu plan.	Sin credencial y tu plan no incluye IA.
Se alcanzó el consumo de IA incluido en tu plan este mes. Usa una credencial propia o amplía el plan.	Se usó todo el consumo de IA incluido este mes. Con una credencial propia el robot sigue sin pausa.
El modelo «…» no está disponible en la IA incluida en tu plan. …	Deja model vacío o elige un modelo del catálogo de Zoan Cloud.
La solicitud es demasiado grande para la IA incluida en tu plan (… 25 MB de audio …).	El audio supera el límite del plan. Pártelo o comprímelo.
El proveedor de IA no respondió a tiempo a través de Zoan Cloud. Inténtalo de nuevo o sube 'timeout'.	El servicio tardó más que timeout en todos los intentos. Sube timeout para audios largos.

Actividades relacionadas

• AI — Complete — resumir, clasificar o responder sobre la transcripción.
• AI — Extract — sacar campos concretos de lo que se dijo.