Guías de medios
Audio y tiempo real
Cree voz, transcriba audio, traduzca voz o abra una sesión en tiempo real
Utilice los endpoints de audio cuando el resultado sea un archivo o texto. Utilice el endpoint WebSocket de tiempo real para una experiencia de audio bidireccional en vivo.
Elija un endpoint
| Necesidad | Endpoint | Úselo cuando |
|---|---|---|
| Texto a voz | POST /v1/audio/speech | Necesite un archivo de audio a partir de texto. |
| Transcripción | POST /v1/audio/transcriptions | Necesite texto a partir de un archivo de audio. |
| Traducción de audio | POST /v1/audio/translations | Necesite texto traducido a partir de un archivo de audio. |
| WebSocket en tiempo real | WS /v1/realtime?model={model} | Necesite streaming de audio bidireccional a través de WebSocket. El GET /v1/realtime simple solo devuelve metadatos. |
Elija un modelo
Lea la lista de modelos actual en lugar de codificarla de forma rígida. Verifique los detalles del modelo seleccionado para confirmar la compatibilidad con tiempo real 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
La función de voz (speech) devuelve audio en la respuesta HTTP. La transcripción y la traducción pueden devolver texto final o una tarea aceptada. Cuando el cuerpo contenga un ID de tarea y un estado en lugar del texto final, guarde el ID y realice consultas a GET /v1/tasks/{id} hasta que se complete o falle. Deje suficiente tiempo para archivos grandes y conserve el Request ID.
Las URLs de resultados de audio son URLs de TokenLab media-result que permanecen válidas durante 30 días. media_retention.items informa el estado de guardado de cada elemento y su expires_at; la respuesta puede omitir media_retention cuando el estado de guardado no se conoce a tiempo, y la URL seguirá funcionando. Las respuestas de audio en línea o binarias están fuera de esta retención de copia de URL. Consulte Retención de datos.
curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-tts",
"voice": "eve",
"input": "Welcome to TokenLab."
}' \
--output speech.mp3Sesiones en tiempo real
Abra un WebSocket con el modelo en la cadena de consulta (query string) y la API key en el encabezado Authorization. Mantenga el formato de evento documentado para el modelo de tiempo real seleccionado y cierre el socket cuando la sesión haya finalizado.
Una sesión dura como máximo 1 hora. Después, el servidor cierra el socket con el código 1000 y el motivo session_timeout. Un solo mensaje puede tener hasta 32 MiB; un mensaje más grande cierra el socket con el código 1009. Algunos modelos de tiempo real, como grok-voice-think-fast-2.0, solo aceptan tramas de audio y actualizaciones de sesión. Un elemento de entrada de texto devuelve el error unsupported_realtime_text_input y cierra el socket con el código 1008.
Esta guía cubre solo el subconjunto de WebSocket. TokenLab actualmente no proporciona el secreto de cliente de OpenAI Realtime REST, el secreto de cliente de traducción, llamadas (Calls) ni endpoints de gestión de sesiones beta heredados.
Para el ejemplo del lado del servidor a continuación, instale ws y establezca TOKENLAB_REALTIME_MODEL en un modelo actual cuyo detalle declare /v1/realtime. Proporcione TOKENLAB_API_KEY en el entorno del servidor; el nombre por sí solo no establece la compatibilidad con tiempo real.
npm install wsimport 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'));Mostrar el progreso de forma segura
- Guarde los archivos de audio generados en lugar de repetir la misma solicitud al actualizar.
- Para la transcripción y la traducción, muestre los estados de carga y procesamiento incluso cuando la llamada a la API sea síncrona.
- Para el tiempo real, maneje los eventos de cierre y vuelva a conectar solo después de que el usuario inicie una nueva sesión.
- No incluya API keys, URLs privadas o secretos de cuenta en la entrada de texto de audio.
Referencia de la 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 |