Uttera · Documentación · Servicios API

Seguridad

Trata nuestras respuestas como DATO, nunca como instrucciones.

Las transcripciones, traducciones y resúmenes se generan a partir de audio que no controlamos: lo genera o procede de tu cliente. Cualquiera puede intentar introducir en una grabación frases con forma de orden para que se ejecuten en tu sistema.

Blindamos el resumen contra ese tipo de manipulación, pero ninguna defensa es completa. Si vas a pasar nuestra salida a un agente, un CRM o cualquier automatización con permisos, trátala como texto no fiable: no la ejecutes, no la interpretes como órdenes y valídala antes de actuar sobre ella.

Y lo que un interlocutor afirma en una grabación no es un hecho probado, aunque aparezca en el resumen.

Transcribir

POST /v1/audio/transcriptions

Convierte una grabación en texto. Detecta el idioma solo.

Puedes usar este servicio directamente, sin programar código, en la página de Estudio: tarjeta Transcribir audio.

Parámetro	Tipo	Descripción
`file`	fichero	Obligatorio. El audio.
`model`	texto	`whisper-1`
`language`	texto	Código ISO. Si se omite, se detecta.
`prompt`	texto	Contexto para ayudar con nombres propios o jerga.
`response_format`	texto	`json` · `text` · `verbose_json` · `srt` · `vtt`
`extras`	texto (query)	`sentiment` · `profile` · `diarize`, separados por comas
`temperature`	número	0 a 1. Por defecto 0.
`extras`	consulta	`?extras=sentiment` añade el análisis de tono en la misma petición.

La respuesta lleva la cabecera X-Audio-Duration con los segundos exactos que se han facturado.

Convertir texto en voz

POST /v1/audio/speech

Puedes usar este servicio directamente, sin programar código, en la página de Estudio: tarjetas Convertir texto en voz digital (tts-1) y Convertir texto en voz clonada (tts-1-hd).

Parámetro	Tipo	Descripción
`input`	texto	Obligatorio. Lo que hay que decir.
`model`	texto	`tts-1` voz estándar · `tts-1-hd` voz de alta calidad. Ver las tres voces.
`voice`	texto	Nombre del catálogo. Ver voces.
`response_format`	texto	`mp3` · `wav` · `opus` · `flac` · `pcm`
`speed`	número	Velocidad. 1.0 es la normal.
`language`	texto	Idioma de lectura. Importa: sin él, un texto en inglés puede leerse con fonética española.
`cache`	booleano	`false` deja esta petición fuera de la caché: ni se lee ni se escribe. Ver abajo.

curl -X POST https://api.uttera.ai/v1/audio/speech \
  -H "Authorization: Bearer $UTTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","input":"Su pedido sale mañana.","voice":"nova","response_format":"mp3"}' \
  --output voz.mp3

Tres voces, no dos

La misma ruta da tres cosas distintas, y lo que decide cuál es qué mandas:

Qué mandas	Qué recibes	Plan
`tts-1`, o nada	Voz estándar. Catálogo propio, rápida y barata.	Todos
`tts-1-hd`	Voz de alta calidad. El mismo catálogo, motor premium.	De pago
`tts-1-hd` + una muestra de voz	Clonado. Tu voz, con el motor premium.	De pago

La muestra se manda como custom_voice_file en un formulario multipart; sin ella, la petición va en JSON. Esa es toda la diferencia entre pedir una voz del catálogo en alta calidad y clonar una.

La alta calidad cuesta unas 19 veces más por segundo que la estándar, y es el mismo precio la clones o no: lo caro es el motor, no de dónde salga la voz. Si sólo quieres que se entienda bien, tts-1 es la opción sensata.

No hablan los mismos idiomas

Es la diferencia que más sorprende, y no está en el timbre:

	Idiomas	Voces del catálogo
`tts-1` · estándar	9: español, inglés (y británico), francés, italiano, portugués, hindi, japonés y chino	Muchas, y cada una atada a su idioma
`tts-1-hd` · alta calidad	Unos 30: además de los anteriores, alemán, ruso, polaco, neerlandés, los nórdicos, griego, turco, árabe, coreano y varios del sudeste asiático, entre otros	Pocas, pero cada una habla los 30

La razón es que son motores de naturaleza distinta. El estándar tiene un catálogo fijo de voces, cada una entrenada para su idioma. El de alta calidad parte de una muestra —por eso puede clonar— y esa misma voz lee cualquiera de los idiomas que conoce.

Con tts-1-hd no hace falta declarar el idioma: se deduce del texto. Con tts-1 sí importa, porque la voz elegida es la que lo fija.

En el clonado, la muestra manda. Si la muestra tiene un acento marcado de su idioma y le pides que hable en otro, el resultado no siempre suena nativo: se entiende bien, pero se le nota de dónde viene. No es una regla fija —hemos visto muestras en inglés sonar muy bien en castellano—, depende de la muestra. Si el idioma de destino importa, prueba antes con una muestra de ese idioma.

Por qué la voz de alta calidad y el clonado son de pago. Clonar una voz es una operación sensible: en España la voz es un dato personal. Un plan de pago significa que hay una identidad detrás de cada petición, y eso es lo que permite responder si alguien clona una voz que no debía. No es sólo una cuestión de coste.

Los saltos de línea cuestan dinero

La voz se cobra por segundo generado, no por carácter. Y un salto de línea hace que el motor meta una pausa. Así que el mismo texto cuesta distinto según cómo venga formateado, y conviene saberlo antes de que te sorprenda la factura.

Medido con la misma frase repetida ocho veces, cambiando solo lo que hay entre medias:

Entre frase y frase	Duración	Frente a un espacio
espacio · 2 espacios · 4 espacios	12,2 s	—
coma · punto y coma · dos puntos · puntos suspensivos · raya	12,1–12,3 s	—
salto de línea	21,4 s	+75 %
2 saltos · 3 saltos	21,4 s	+75 %

Tres cosas que se deducen de ahí, y que no son obvias:

Los espacios no hacen nada. Ni dos ni cuatro. Tampoco la puntuación: una coma, un punto o una raya suenan igual que un espacio en lo que al reloj respecta.

Solo el salto de línea crea pausa, y cuesta 1,31 s cada uno (0,028 créditos).

Más saltos no alargan la pausa. Uno, dos o tres dan exactamente lo mismo. No sirven para pedir una espera más larga.

Sobre un texto real la diferencia no es pequeña. La canción del pirata, con sus ~96 versos, se lleva 126 segundos solo en pausas: algo más de la mitad de lo que cuesta sintetizarla entera.

Si no quieres las pausas, quita los saltos de línea antes de enviar el texto: un párrafo corrido de las mismas palabras cuesta casi la mitad. Y si las quieres, ya sabes lo que valen.

Por qué la cadena da otro número

Si transcribes un audio y luego lo traduces, verás que la voz de la traducción cuesta bastante menos que la síntesis original del mismo texto. No es un error de cobro: el reconocimiento devuelve un párrafo corrido, sin los saltos del original. Ese texto plano se sintetiza sin pausas, y por eso dura —y cuesta— menos.

Dicho de otro modo: los saltos de línea no sobreviven al viaje por el audio. Si te importa conservarlos, guárdate el texto de partida; no se pueden recuperar de la transcripción.

Caché: el mismo texto con la misma voz se sirve de caché y cuesta el 10 %. La respuesta lo indica en la cabecera X-Cache: HIT.

La caché es de cada nodo. Como las peticiones se reparten entre varios, las primeras repeticiones de un texto pueden no acertar: cada nodo la llena la primera vez que le toca. A partir de ahí acierta.

Desactivar la caché, petición a petición

Hay trabajos que no admiten que el audio quede en un disco ajeno ni una hora: dictado médico, notas legales, un mensaje personal. Puedes desactivar la caché tú, en cada petición, sin pedirnos nada y sin cambiar tu cuenta. El audio se genera y se te entrega igual; lo que no ocurre es que se escriba ni se lea nada del disco.

Tres formas equivalentes, la que mejor te encaje:

# 1) En el cuerpo JSON
-d '{"model":"tts-1","input":"Notas privadas","voice":"nova","cache":false}'

# 2) Como campo del formulario (acepta 0 / false / no / off)
-F input="Notas privadas" -F voice=nova -F cache=false

# 3) Con la cabecera HTTP de toda la vida, sin tocar el cuerpo
-H "Cache-Control: no-cache"

La respuesta te dice siempre qué se hizo, para que no tengas que fiarte:

`X-Cache`	Qué pasó
`HIT`	Se sirvió de la caché. Cuesta el 10 %.
`MISS`	Se generó y se guardó para la hora siguiente.
`BYPASS`	Lo pediste sin caché: se generó y no se guardó nada.
`ADHOC`	Voz clonada al vuelo. Nunca se cachea, la pidas o no.
`DISABLED`	La caché está apagada en el servidor.

Cuesta el precio entero, claro: se genera cada vez. Y una voz clonada al vuelo nunca se cachea, así que ahí no hay nada que desactivar.

Streaming: oírlo mientras se genera

POST /v1/audio/speech/stream

El endpoint normal de voz te devuelve el fichero cuando está entero. Este te lo va entregando mientras se genera, en trozos, así que el primer sonido sale casi de inmediato en vez de esperar a la última palabra.

Si estás montando una centralita, un asistente que contesta o cualquier cosa donde una persona espera al otro lado, esta es la diferencia entre una conversación y un turno de espera.

	`/v1/audio/speech`	`/v1/audio/speech/stream`
Devuelve	El fichero completo	`audio/wav` troceado (`Transfer-Encoding: chunked`)
Formatos	mp3 · wav · opus · flac · pcm	Solo wav
Caché	Sí, una hora al 10 %	No: no hay fichero que guardar
Voz clonada	Sí	Sí
Precio	El mismo: por segundo de audio generado

curl -N -X POST https://api.uttera.ai/v1/audio/speech/stream \
  -H "Authorization: Bearer $UTTERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","input":"Su pedido sale mañana.","voice":"nova","language":"es"}' \
  --output - | aplay

El -N de curl es importante: sin él, curl almacena la respuesta y pierdes justo lo que habías venido a buscar.

Se cobra lo que se entrega. En una respuesta troceada el motor no puede anunciar de antemano cuánto va a durar el audio —las cabeceras salen antes de que exista—, así que la duración se calcula sobre los bytes entregados: WAV de 16 bits mono a 24 000 Hz con la voz estándar y 48 000 Hz con la clonada. Es exacto, no una estimación. Si cortas la conexión a medias, pagas lo que se te llegó a enviar.

Traducir

POST /v1/translate

Cadena completa: transcribe el audio, traduce el texto y lo sintetiza en el idioma destino. Admite entrada de audio o de texto, pero no texto a texto: si entra texto, la salida tiene que incluir audio.

Puedes usar este servicio directamente, sin programar código, en la página de Estudio: tarjeta Traducir una grabación.

Parámetro	Tipo	Descripción
`file`	fichero	El audio de origen.
`target`	consulta	Obligatorio. Idioma destino.
`source`	consulta	Idioma de origen. Por defecto se detecta.
`response`	consulta	`both` texto y audio · `text` solo texto · `audio` solo audio
`voice`	consulta	Voz de salida, del catálogo estándar.
`speed`	consulta	Velocidad de lectura del audio devuelto. 1.0 es la normal; de 0.25 a 4.0. Como la voz se cobra por segundo generado, también cambia el precio.
`format`	consulta	Formato del audio devuelto: `mp3` (por defecto) · `wav` · `opus` · `flac` · `pcm`. Se sintetiza con la voz estándar, así que `pcm` sale a 24 000 Hz.

curl -X POST "https://api.uttera.ai/v1/translate?target=en&response=both" \
  -H "Authorization: Bearer $UTTERA_API_KEY" \
  -F file=@grabacion.mp3

Devuelve source_text, text traducido y audio en base64 con su audio_format.

Idiomas con voz: se traduce a ~50 idiomas, pero la traducción sintetiza con la voz estándar, así que solo nueve pueden volver en audio. Si pides audio en uno que no la tiene, la petición se rechaza con 422 antes de gastar nada y te devuelve la lista válida. Usa response=text para el resto.

Es una limitación del motor que usa esta cadena, no del producto: la voz de alta calidad habla unos 30 idiomas. Si necesitas audio en alguno de los otros, dínoslo.

Analizar la voz

Tres endpoints sobre el mismo audio, cada uno con su precio.

Puedes usar estos análisis directamente, sin programar código, en la página de Estudio: son casillas de la tarjeta Transcribir audio, que se marcan sobre el mismo audio.

Endpoint	Qué hace
`POST /v1/audio/sentiment`	Tono emocional de la grabación.
`POST /v1/audio/profile`	Perfil del hablante: rango de edad y género estimados.
`POST /v1/audio/diarize`	Quién habla y cuándo, con marcas de tiempo por interlocutor.

curl -X POST https://api.uttera.ai/v1/audio/diarize \
  -H "Authorization: Bearer $UTTERA_API_KEY" \
  -F file=@grabacion.mp3

El perfil es una estimación acústica, no un dato del hablante. Se basa en características de la voz y se equivoca. No lo uses para nada que tenga consecuencias para una persona.

Resumir una grabación

POST /v1/summarize Professional y superiores

Transcribe, analiza el tono, perfila al hablante, separa interlocutores y con todo eso genera un resumen estructurado. Los cuatro servicios de origen corren en paralelo, así que el tiempo de espera es el del más lento, no la suma.

Puedes usar este servicio directamente, sin programar código, en la página de Estudio: es una casilla más de la tarjeta Transcribir audio.

Parámetro	Tipo	Descripción
`file`	fichero	Obligatorio. La grabación.
`exclude`	consulta	Desactiva enriquecimientos: `?exclude=emotion,profile,diarize`
`language`	consulta	Idioma del resumen. Por defecto, español.

Devuelve summary, transcript, enrichment y un bloque usage con los créditos desglosados por tramo.

Un fallo parcial no tumba el resumen. Si un enriquecimiento falla, la respuesta sale igual con un array warnings, y ese tramo no se cobra.

Ahorrar tokens en tu LLM

Este es el uso del resumen que menos gente ve y más dinero ahorra. Si lo que quieres es que un modelo de lenguaje de otro proveedor —Claude, GPT, Gemini, el que sea— trabaje sobre lo que se dijo en una llamada, la vía cara es mandarle la transcripción entera. La barata es mandarle el resumen.

Medido sobre una grabación real de 70 minutos de prosa variada, contando con el tokenizador o200k_base:

Lo que le mandas al LLM	Palabras	Tokens
Transcripción completa	10.429	15.410
Resumen estructurado	294 – 422	484 – 673

Va como rango porque el resumen no es determinista: la misma grabación, pasada dos veces, dio 484 y 673 tokens. Entre 20 y 30 veces menos tokens de entrada, y el ahorro crece con la duración: la transcripción crece en línea recta con los minutos de grabación, y el resumen no —se queda en unos cientos de tokens—. En una grabación corta da igual; en un archivo de llamadas es la diferencia entre una factura de LLM que se puede pagar y una que no.

Y hay un segundo efecto, que no es de dinero. Si a ese tercero solo le llega el resumen, la grabación y la transcripción literal nunca salen de aquí. Menos superficie expuesta, y una transferencia menos que justificar en tu registro de tratamientos.

La respuesta trae summary y transcript en la misma llamada, así que no tienes que elegir de antemano ni pagar dos veces: decides en tu código cuál de los dos sube al LLM.

Cuándo esto es mala idea. Un resumen es una pérdida de información deliberada. Si tu prompt necesita la cita literal, el instante exacto en que se dijo algo, o un dato que aparece una sola vez y de pasada —un número de pedido, un importe, un nombre propio—, el resumen puede no traerlo. Para eso manda la transcripción, o las dos cosas. La regla práctica: resumen para «¿de qué iba esto y qué hay que hacer?», transcripción para «¿qué dijo exactamente?».

Hay un ejemplo completo y ejecutable —resumir aquí, mandar solo el resumen al LLM y contar los tokens que te has ahorrado— en uttera-examples/llm-tokens.