Audio y tiempo real

Las cargas de audio tienen dos formas. Usa los endpoints de audio para solicitudes tipo archivo como texto a voz, transcripción y traducción de audio. Usa el endpoint WebSocket en tiempo real cuando la experiencia necesite audio interactivo de baja latencia o eventos multimodales.

Elegir El Flujo

Flujo	Endpoint	Úsalo cuando
Texto a voz	`POST /v1/audio/speech`	Necesites un archivo de audio a partir de texto.
Transcripción	`POST /v1/audio/transcriptions`	Necesites texto a partir de un archivo de audio.
Traducción de audio	`POST /v1/audio/translations`	Necesites texto traducido desde un archivo de audio.
Sesión en tiempo real	`GET /v1/realtime`	Necesites audio bidireccional en streaming o eventos multimodales en tiempo real.

Descubrir Modelos

Consulta el catálogo de modelos antes de fijar un modelo. Usa listas recomendadas para voz y transcripción, y confirma soporte realtime en los detalles del modelo antes de abrir un socket.

curl "https://api.tokenlab.sh/v1/models?recommended_for=tts" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models?recommended_for=stt" \
  -H "Authorization: Bearer sk-your-api-key"

Solicitudes De Audio Síncronas

La síntesis devuelve audio en la respuesta HTTP. La transcripción y la traducción pueden devolver texto final o una tarea aceptada. Si la respuesta contiene un ID y estado de tarea, guarda el ID y consulta poll_url hasta completar o fallar. Permite suficiente tiempo para archivos grandes y conserva el Request ID.

curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1-hd",
    "voice": "nova",
    "input": "Welcome to TokenLab."
  }' \
  --output speech.mp3

Sesiones En Tiempo Real

Abre un WebSocket con el modelo en la query string y la API key en el encabezado Authorization. Usa el formato de eventos documentado para el modelo realtime elegido y cierra el socket al terminar la sesión. Esta guía cubre solo el WebSocket subset. TokenLab no proporciona actualmente endpoints REST de OpenAI Realtime para client secret, translation client secret, Calls ni gestión legacy beta session. Para el ejemplo de servidor, instala ws y define TOKENLAB_REALTIME_MODEL con un modelo actual cuyos detalles declaren /v1/realtime. Proporciona TOKENLAB_API_KEY en el entorno del servidor; el nombre no demuestra compatibilidad realtime.

npm install ws

import WebSocket from 'ws';

const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
socket.on('message', (event) => console.log(event.toString()));
socket.on('error', (error) => console.error(error.message));
process.once('SIGINT', () => socket.close(1000, 'Client stopped'));

Manejo De Estado

Guarda los archivos de audio generados en lugar de repetir la misma solicitud al refrescar.
Para transcripción y traducción, muestra estados de subida y procesamiento aunque la llamada sea síncrona.
Para realtime, maneja eventos de cierre y reconecta solo cuando el usuario inicia una nueva sesión.
No pongas API keys, URLs privadas ni secretos de cuenta en el texto de audio.

Referencia API

Tema	Referencia
Crear Voz	Crear Voz
Crear Transcripción	Crear Transcripción
Crear Traducción	Crear Traducción
WebSocket En Tiempo Real	WebSocket En Tiempo Real
Listar Modelos	Listar Modelos
Facturación y precios	Facturación y precios

Primeros pasos

Guías principales

Guías de medios

Audio y tiempo real

Elegir El Flujo

Descubrir Modelos

Solicitudes De Audio Síncronas

Sesiones En Tiempo Real

Manejo De Estado

Referencia API

​Elegir El Flujo

​Descubrir Modelos

​Solicitudes De Audio Síncronas

​Sesiones En Tiempo Real

​Manejo De Estado

​Referencia API

Elegir El Flujo

Descubrir Modelos

Solicitudes De Audio Síncronas

Sesiones En Tiempo Real

Manejo De Estado

Referencia API