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 — los mismos para transcribir y para analizar. webm es lo que graba un navegador y m4a lo que graba un móvil, así que ambos sirven tal cual.

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 400 MB por petición y 3 horas de audio, con un tope de 100 MB de fichero en transcripción. Un WAV de 3 horas pesa unos 346 MB y no pasa ese tope: para audios largos, envíelo comprimido.

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.

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.