Saltar al contenido

API de Voz

La API de Voz convierte en texto la voz en vivo para tu aplicación, por un WebSocket. Habla el protocolo de streaming de nuestro proveedor de voz sin cambios, así que un cliente escrito para el proveedor cambia dos direcciones y una clave, y nada más. Cada sesión se paga con la billetera de tu empresa, por segundo.

Nuestro proveedor de vozAptiveAI
Token (tu servidor)POST https://token.us.assemblyai.com/v1/token, Authorization: <clave del proveedor>POST https://console.aptiveai.io/api/v1/speech/token, Authorization: <clave aak_> (sin prefijo o con Bearer)
Socket (el navegador)wss://streaming.us.assemblyai.com/v3/ws?token=…&<params>wss://console.aptiveai.io/ws/speech?token=…&<params>

Tu clave de API nunca llega a un navegador: tu servidor la cambia por un token de corta duración, y el navegador abre el socket con ese token.

Un propietario de tu empresa crea una clave en AptiveAI Agents, en Ajustes → Claves de API, con API de Voz en Servicios — consulta Claves de API. El interruptor Voz de la propia cuenta, arriba en la misma página, también debe estar activado; lo está salvo que alguien lo haya desactivado. La billetera debe tener al menos $0.05.

Tu servidor llama a la ruta del token con la clave:

POST https://console.aptiveai.io/api/v1/speech/token
Authorization: Bearer aak_…
Content-Type: application/json
{ "expires_in_seconds": 60 }
{ "token": "…", "expires_in_seconds": 60 }
  • expires_in_seconds es la vida del token: de 1 a 600 segundos, 60 si no envías ninguno. Los demás campos del cuerpo, como product, se ignoran.
  • La clave se puede enviar como Authorization: Bearer aak_… o sin prefijo, Authorization: aak_… (el estilo del proveedor), así que un cliente que envía su clave sin prefijo funciona sin cambios.
  • El token es de AptiveAI, no del proveedor. Solo controla la apertura del socket, y se puede usar más de una vez mientras está vigente.
HTTPcodeCuándo
400invalid_requestEl cuerpo no es un objeto JSON, o expires_in_seconds no es un número de segundos
401invalid_api_keyLa clave falta, no se reconoce o está revocada
402insufficient_fundsLa billetera tiene menos de $0.05
403account_unavailableLa empresa está bloqueada o cancelada
403service_not_enabledLa clave no tiene API de Voz, o Voz está desactivada para la cuenta
429rate_limitedMás de 120 solicitudes por minuto con esta clave; consulta Retry-After
503speech_unavailableEl servicio no está disponible

Los errores tienen la forma { "error": { "message", "type", "code" } }, como en la API de Agentes.

El navegador abre el socket con el token y los parámetros de consulta del proveedor:

const params = new URLSearchParams({
token, // from your server
speech_model: 'universal-3-6-pro',
// …and any other parameter of the vendor's, such as sample_rate or encoding
});
const socket = new WebSocket(`wss://console.aptiveai.io/ws/speech?${params}`);
socket.onmessage = (event) => {
const message = JSON.parse(event.data); // the vendor's frames, unchanged
console.log(message.type); // Begin, SpeechStarted, Turn, Termination or Error
};
// Send audio as binary frames: socket.send(pcmChunk)
// To end: socket.send(JSON.stringify({ type: 'Terminate' }))
  • Parámetros. Los parámetros de consulta del proveedor — speech_model, sample_rate, encoding, las palabras clave y el resto — se pasan sin cambios.
  • El audio sube como frames binarios.
  • Lo que baja son los propios frames de texto del proveedor, sin cambios: Begin, SpeechStarted, Turn, Termination, Error.
  • Para terminar, envía {"type":"Terminate"}. La respuesta es Termination y luego un cierre normal.

speech_model debe ser uno para el que AptiveAI tenga tarifa; cualquier otro se cierra con 4400. Las tarifas son por hora de sesión — el tiempo que el socket está abierto. Lo que se cobra a la billetera es la tarifa del proveedor (su precio público de streaming, consultado el 2026-11-17) por 1.3, la tarifa estándar de AptiveAI:

speech_modelTarifa del proveedor por horaLo que pagas por hora (× 1.3)
assemblyai-stt-3-7-realtime$0.30$0.39
assemblyai-stt-3-7-realtime-agent$0.45$0.585
universal-3-6-pro (el predeterminado)$0.45$0.585
universal-streaming-english$0.15$0.195
universal-streaming-multilingual$0.15$0.195
Complemento Medical Mode (domain)+ $0.15+ $0.195
  • Son tarifas de streaming. Las cifras más bajas del proveedor (por ejemplo, $0.21 por hora) son para audio pregrabado, que la API de Voz no ofrece.
  • El modelo predeterminado se envía explícitamente. Una sesión que no indica ningún modelo usa universal-3-6-pro: AptiveAI se lo envía al proveedor por su nombre, así que el modelo que se ejecuta es el modelo que se cobra. El universal-streaming a secas no es un modelo que el proveedor acepte, y se cierra con 4400.
  • Complementos. Una sesión que define domain (Medical Mode, domain=medical-v1) cuesta $0.15 más por hora a la tarifa del proveedor, durante toda la sesión, y la tarifa de AptiveAI se le aplica igual que a la del modelo.
  • Una empresa con una tarifa propia acordada paga la tarifa del proveedor por esa tarifa.
  • Una sesión se mide por segundo, desde el Begin del proveedor hasta el cierre de cualquiera de los dos lados, a la tarifa del modelo (más la de cualquier complemento) más la tarifa de AptiveAI.
  • Se paga solo con la billetera — nunca con la asignación del puesto de una persona ni con crédito promocional —, con un cargo cada 30 segundos y al cerrar.
  • Cuando un cargo no se puede cubrir, el socket recibe {"type":"Error","error_code":4402,"error":"insufficient funds"} y se cierra; los segundos ya usados quedan registrados como adeudados.
  • No se guarda ni se registra ningún audio ni ninguna transcripción.

Para agregar fondos o configurar recargas automáticas, consulta Facturación y puestos.

LímiteValor
Una sesión1 hora (luego se cierra con 4408)
Sesiones a la vez20 por clave, por instancia de servidor de AptiveAI (luego 4429)
Solicitudes de token120 por minuto por clave

Un despliegue de AptiveAI cierra las sesiones en curso con un código de cierre normal: vuelve a conectarte con un token nuevo.

Abajo están los códigos de cierre propios de AptiveAI; los del proveedor pasan sin cambios.

CódigoSignificado
4001No autorizado: un token que falta, no es válido o venció, una clave revocada, o Voz desactivada para la cuenta
4401Durante una sesión: la clave se revocó o perdió API de Voz, la cuenta dejó de estar disponible, o Voz se desactivó para la cuenta. Se envía en el siguiente cargo (en unos 30 segundos), como un frame Error y luego el cierre
4400Solicitud incorrecta: un speech_model desconocido, o demasiado audio antes de Begin
4402Fondos insuficientes, al abrir o a mitad de la sesión
4408El límite de una hora por sesión
4429Demasiadas sesiones a la vez con esta clave
4503El servicio no está disponible
1011No se pudo comunicar con el proveedor de transcripción