Autenticación

Cabecera Authorization: Bearer sk-echo-... en todas las peticiones. La clave se muestra una sola vez al crearla: guárdala. Si la pierdes, revócala y crea otra.

Restringir una clave a unas IPs

Cada clave puede limitarse a las direcciones desde las que tiene sentido que se use. Si tu integración vive en un servidor con IP fija, una clave robada deja de servir de nada fuera de él.

Se configura en tu cuenta, en la columna IPs permitidas de cada clave. Se admiten direcciones sueltas y redes:

203.0.113.7, 198.51.100.0/24, 192.0.2.10

En blanco, la clave funciona desde cualquier sitio, que es el comportamiento por defecto.

Una petición desde una IP que no está en la lista recibe 403 con el código ip_not_allowed y, en el cuerpo, la IP que hemos visto — que es justo lo que necesitas para añadirla si te has dejado una:

{
  "error": "ip_not_allowed",
  "message": "This API key is restricted to a list of IP addresses and this request does not come from one of them",
  "client_ip": "203.0.113.55"
}

La restricción cubre todos los endpoints autenticados, incluido /v1/usage/last. Quien roba una clave no siempre quiere gastarla; a veces le basta con ver cuánto gasta su dueño.

Análisis en la misma petición

Una transcripción puede traer análisis de voz sin subir el audio otra vez. Se piden en la cadena de consulta, separados por comas:

curl https://api.uttera.ai/v1/audio/transcriptions?extras=sentiment,profile,diarize \
  -H "Authorization: Bearer $UTTERA_API_KEY" \
  -F file=@grabacion.m4a \
  -F model=whisper-1

Los tres corren en paralelo sobre el mismo audio, así que pedir los tres tarda casi lo mismo que pedir uno. Cada uno se cobra aparte, y solo si se ejecuta: si un análisis falla, la transcripción llega igual y la respuesta trae un array errors diciendo cuál faltó — y ese no se factura.

Para sentiment con nivel por segmentos o dimensional (valencia, activación, dominancia), use el endpoint suelto /v1/audio/sentiment: en extras va siempre el nivel global.

Formatos e idiomas

Audio de entrada: wav, mp3, flac, ogg, opus, aiff, m4a y webm. webm es lo que graba un navegador y m4a lo que graba un móvil, así que ambos sirven tal cual para transcribir.

Audio de salida (response_format de voz): wav, mp3, opus, flac y pcm. pcm es PCM crudo sin cabecera, así que por la webapp no se ofrece —no lo reproduce un navegador— y al usarlo por API hay que decirle al decodificador los cuatro parámetros, porque el fichero no los lleva:

La frecuencia es la nativa de cada voz y no se remuestrea: la HD genera a 48 kHz y se entrega tal cual. Lo único que cambia entre los dos es la frecuencia; decodificarlo con la que no toca no suena peor, suena al doble o a la mitad de velocidad. Con wav, flac u opus esto no aplica: el fichero lo declara solo.

# voz estándar
ffmpeg -f s16le -ar 24000 -ac 1 -i voz.pcm voz.wav
# voz HD
ffmpeg -f s16le -ar 48000 -ac 1 -i voz.pcm voz.wav

Cualquier otro valor de response_format devuelve 422 con la lista válida.

Tamaño: hasta 150 MB por petición y 2 horas de audio. Un WAV sin comprimir de 2 horas no cabe: para audios largos, envíelo comprimido. El detalle, en tamaños y duración.

Transcripción: detecta el idioma automáticamente y cubre los que soporta Whisper.

Voz: depende del motor, y la diferencia es grande. La voz estándar (tts-1) habla los nueve de la tabla de abajo. La voz de alta calidad (tts-1-hd) habla unos 30 —además de esos nueve, alemán, ruso, polaco, neerlandés, los nórdicos, griego, turco, árabe, coreano y varios del sudeste asiático, entre otros— y no hace falta declarar el idioma: se deduce del texto. Está explicado en Tres voces, no dos.

Traducción: ~50 idiomas de texto. La cadena sintetiza con la voz estándar, así que con voz son estos nueve:

Catálogo de voces

Voces estándar disponibles con model: tts-1:

alloy · echo · fable · nova · onyx · shimmer

El catálogo ampliado está en revisión; se publicará cuando esté cerrado.

Créditos

Cada servicio cobra por lo que consume. Estos son los coeficientes vigentes:

Cómo se compone cada servicio

Ejemplo real

Una grabación de 40 minutos (2.424 s) traducida al inglés con voz:

transcripción     79,22   2.424,5 s x 0,032673
voz               43,18   2.055,8 s x 0,021004   (el inglés sale ~15 % más corto)
traducción       193,96   2.424,5 s x 0,080000
                 ──────
                 316,36 créditos

Planes y límites

Los créditos se renuevan en la fecha de tu suscripción, no el día 1. Si cambias de plan a uno menor, conservas los créditos ya pagados hasta que venza el periodo.

Límites por segundo

Cada respuesta lleva X-RateLimit-Remaining-Second y X-Credits-Remaining-Monthly para que no tengas que adivinar.

Tamaños y duración máximos

Grabaciones largas: cómo las resume

Una grabación larga no cabe de una vez en el contexto del modelo. En vez de resumir un trozo, la partimos, resumimos cada pieza y luego fusionamos — y la fusión no es un resumen de resúmenes, que perdería información dos veces: se le pide que ordene y una las piezas, conservando todas las cifras, fechas y nombres.

Así que el resumen no tiene un límite propio más corto: lo que se puede transcribir se puede resumir. Medido de punta a punta sobre una grabación de cuatro horas con tono, perfil y diarización: seis minutos, entero, con el principio y el final presentes.

Si alguna vez un resumen volviera cortado, la respuesta lo dice en truncated. No es algo que debas ver, y preferimos decírtelo a darte un resumen recortado que se lee como uno entero.

Dos horas tienen que caber en 150 MB

Los dos límites son independientes y hay que cumplir los dos. Para dos horas completas, eso significa no pasar de 175 kbps:

Para voz, un mp3 de 64 kbps no pierde nada que nos importe y te deja sitio de sobra. Si envías wav sin comprimir, cuenta con que dos horas no caben.

Texto a voz: el límite depende de la voz

No hay un límite único, porque las dos voces las genera maquinaria distinta:

Voz estándar (tts-1). Se puede pedir de dos formas:

• Respuesta completa (/v1/audio/speech): devolvemos el audio entero cuando está terminado. Como tiene que existir todo a la vez, el tope son 250.000 caracteres —del orden de cuatro a cinco horas de voz—. El «del orden de» es a propósito: cuánto audio da un carácter depende mucho del texto, y medido sobre prosa real va de 12,6 a 17,5 caracteres por segundo. El tope es del texto, no de la duración.
• Streaming (/v1/audio/speech/stream): enviamos el audio según se genera. Aquí no hay límite de longitud, porque no se acumula nada.

Para una locución larga, el streaming sigue siendo mejor camino. Empiezas a oír el resultado en segundos en vez de esperar al final, y no hay que meter nada entero en una sola respuesta.

Voz de alta calidad y voz clonada (tts-1-hd). El tope es 2.000 caracteres por petición, unos dos minutos y medio de voz. Es bastante menos, y es una limitación del modelo que da esa voz, no una decisión comercial. Para esta voz el streaming no sirve para textos largos: úsala en fragmentos de un par de miles de caracteres y encadénalos.

Errores

Consultar el consumo

El cargo se calcula después de enviarte la respuesta, así que no viene dentro de ella. Para saber lo que te ha costado exactamente una petición:

GET /v1/usage/last
GET /v1/usage/last?endpoint=/v1/summarize

Devuelve los créditos cobrados y el desglose por tramo:

{
  "endpoint": "/v1/summarize",
  "credits": 108.978,
  "breakdown": { "stt": 3.1255, "diarize": 2.0029,
                 "profile": 0.1946, "llm": 103.655 },
  "audio_seconds": 95.66,
  "input_tokens": 2776, "output_tokens": 1230
}

Guarda los diez últimos cargos durante una hora. Es para comprobar al momento, no un histórico de facturación.

Cuánto tarda cada cosa

Números medidos, no promesas. Varían con el nodo que atienda y con la carga del momento:

Lo que de verdad hay que configurar bien es el tiempo de espera de tu cliente: el servidor mantiene la conexión hasta 7200 segundos, y el fallo más común al integrar es un cliente con 30 segundos por defecto que corta trabajos que iban perfectamente. Está explicado en Integración.

Versionado y cambios

Lo que integras hoy tiene que seguir funcionando mañana. Este es el compromiso:

Para que eso signifique algo, hace falta decir qué cuenta como romper y qué no:

De ahí sale la regla práctica para tu código: ignora los campos que no conozcas en vez de fallar al encontrarlos. Un cliente que revienta porque la respuesta trae una clave nueva se romperá solo, sin que nadie haya roto nada.

Los precios son caso aparte: no son la interfaz, pero sí tu factura. Una subida de coeficientes se anuncia con treinta días y no se aplica a un ciclo ya pagado. Una bajada se aplica en cuanto está.

Estado del servicio

Si algo va mal, lo primero es saber si es tuyo o nuestro.

GET https://api.uttera.ai/health responde sin necesidad de clave y dice si la API está en pie. Es la comprobación que puedes automatizar.

curl -s https://api.uttera.ai/health

Cada respuesta lleva además una cabecera X-Request-Id. Guárdala cuando algo falle: con ese identificador podemos decirte exactamente qué pasó con tu petición, y sin él la conversación empieza por reconstruir cuál era.

Para cualquier incidencia, escríbenos con el X-Request-Id, la hora aproximada y qué esperabas que pasara.

En estudio

Cosas que nos piden, que tienen sentido y que todavía no están. Las ponemos aquí porque enterarte de que algo no existe después de integrarlo es peor que saberlo ahora:

Si alguna de ellas te bloquea, dínoslo: lo que nos piden los clientes es lo que decide el orden.