Guias de mídia

Áudio e tempo real

Crie fala, transcreva áudio, traduza fala ou abra uma sessão em tempo real

Use os endpoints de áudio quando o resultado for um arquivo ou texto. Use o endpoint WebSocket de tempo real para uma experiência de áudio bidirecional ao vivo.

Escolha um endpoint

NecessidadeEndpointUse-o quando
Texto para falaPOST /v1/audio/speechVocê precisa de um arquivo de áudio a partir de texto.
TranscriçãoPOST /v1/audio/transcriptionsVocê precisa de texto a partir de um arquivo de áudio.
Tradução de áudioPOST /v1/audio/translationsVocê precisa de texto traduzido a partir de um arquivo de áudio.
WebSocket em tempo realWS /v1/realtime?model={model}Você precisa de streaming de áudio bidirecional via WebSocket. O GET /v1/realtime simples retorna apenas metadados.

Escolha um modelo

Leia a lista de modelos atual em vez de codificá-la fixamente. Verifique os detalhes do modelo selecionado quanto ao suporte a tempo real antes de abrir um 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"

Requisições de áudio

A fala retorna áudio na resposta HTTP. A transcrição e a tradução podem retornar texto final ou uma tarefa aceita. Quando o corpo contiver um ID de tarefa e status em vez do texto final, salve o ID e consulte GET /v1/tasks/{id} até a conclusão ou falha. Reserve tempo suficiente para arquivos grandes e mantenha o Request ID.

URLs de resultados de áudio são URLs de media-result da TokenLab que permanecem válidas por 30 dias. media_retention.items relata o status de salvamento de cada item e expires_at; a resposta pode omitir media_retention quando o status de salvamento não for conhecido a tempo, e a URL ainda funcionará. Respostas de áudio inline ou binárias estão fora desta retenção de cópia de URL. Veja Retenção de dados.

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.mp3

Sessões em tempo real

Abra um WebSocket com o modelo na string de consulta e a chave de API no cabeçalho Authorization. Mantenha o formato de evento documentado para o modelo de tempo real selecionado e feche o socket quando a sessão for concluída.

Uma sessão dura no máximo 1 hora. Após isso, o servidor fecha o socket com o código 1000 e o motivo session_timeout. Uma única mensagem pode ter até 32 MiB; uma mensagem maior fecha o socket com o código 1009. Alguns modelos de tempo real, como grok-voice-think-fast-2.0, aceitam apenas quadros de áudio e atualizações de sessão. Um item de entrada de texto retorna o erro unsupported_realtime_text_input e fecha o socket com o código 1008.

Este guia cobre apenas o subconjunto de WebSocket. A TokenLab atualmente não fornece segredo de cliente REST de tempo real da OpenAI, segredo de cliente de tradução, chamadas (Calls) ou endpoints de gerenciamento de sessão beta legados.

Para o exemplo do lado do servidor abaixo, instale o ws e defina TOKENLAB_REALTIME_MODEL para um modelo atual cujo detalhe declare /v1/realtime. Forneça TOKENLAB_API_KEY no ambiente do servidor; o nome por si só não estabelece suporte a tempo real.

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'));

Exiba o progresso com segurança

  • Salve arquivos de áudio gerados em vez de repetir a mesma requisição ao atualizar.
  • Para transcrição e tradução, exiba estados de upload e processamento mesmo quando a chamada de API for síncrona.
  • Para tempo real, trate eventos de fechamento e reconecte apenas após o usuário iniciar uma nova sessão.
  • Não coloque chaves de API, URLs privadas ou segredos de conta na entrada de texto de áudio.

Referência da API

TópicoReferência
Criar falaCriar fala
Criar transcriçãoCriar transcrição
Criar traduçãoCriar tradução
WebSocket em tempo realWebSocket em tempo real
Listar modelosListar modelos
Faturamento e preçosFaturamento e preços

Nesta página