Escolha o modelo e as informações adicionais
Arquivos e áudio ao vivo usam endpoints próprios. Toda transcrição contém text, inclusive uma string vazia em caso de silêncio. timestamps fica desativado por padrão; marcações de tempo só aparecem em segments quando pedidas expressamente. No momento, nenhum modelo oferece identificação de falantes, por isso diarize=true é recusado. Opções e códigos de idioma não suportados são recusados com HTTP 422 antes da chamada paga ao provedor.
| Modelo | Arquivo | Ao vivo | Informações adicionais |
groq/whisper-large-v3-turbo | Sim | Não | Marcações de tempo |
groq/whisper-large-v3 | Sim | Não | Marcações de tempo |
openai/gpt-transcribe | Sim | Não | Texto |
ionos/openai/whisper-large-v3 | Sim | Não | Marcações de tempo, hospedado na UE (Berlim) |
openai/gpt-live-transcribe | Não | Sim | Texto |
A transcrição de arquivos e a ao vivo são liberadas separadamente. Use somente modelos da sua resposta atual de GET /models. Ali, transcription.modes, transcription.languages e os campos de opções descrevem as capacidades. pricing.variants traz as combinações disponíveis de modo e marcações de tempo, com preços em EUR por minuto e, quando aplicável, por milhão de tokens de áudio ou texto. Um preço ausente impede o início; não há troca automática de provedor.
Arquivos e trabalhos em segundo plano
Envie o arquivo como multipart/form-data diretamente para POST /audio/transcriptions. Um file_id enviado anteriormente não é aceito aqui. Os exemplos na área de código iniciam um trabalho em segundo plano. Omita background ou defina como false se quiser trabalhar de forma síncrona. Deixe o cabeçalho multipart, incluindo o boundary, por conta do seu cliente HTTP.
- Síncrono: no máximo 24 MiB e dez minutos, HTTP 200 com o resultado.
- Em segundo plano:
background=true, em geral no máximo 200 MiB e oito horas, HTTP 202 com o ID do trabalho. Os limites do modelo também se aplicam.
Consulte GET /audio/transcriptions/{id} até status ter o valor completed, cancelled ou failed. Antes disso são possíveis queued e processing. progress fica entre 0 e 1. O resultado também contém model, usage, flowai_request_id e expires_at. Com marcações de tempo solicitadas, start e end se referem à gravação inteira, mesmo que ela seja processada em partes.
POST /audio/transcriptions/{id}/cancel impede novas partes; uma chamada ao provedor já paga ainda pode terminar. Em caso de erro ou cancelamento, pode haver resultados parciais confirmados. DELETE /audio/transcriptions/{id} exclui somente trabalhos concluídos. Gravações grandes do Groq, da OpenAI e da IONOS são divididas em partes limitadas e reagrupadas na ordem original.
Criar e conectar uma sessão ao vivo
POST /audio/transcription-sessions espera model e source: push para áudio do seu aplicativo ou url com um stream de áudio HTTP(S) público e direto em url. language, timestamps, diarize e max_seconds são opcionais. A duração padrão é de duas horas, a máxima de oito horas. É possível ter no máximo três sessões ativas por equipe ao mesmo tempo.
A resposta com HTTP 201 traz id, websocket_url, ticket e ticket_expires_at. O tíquete vale 60 segundos, está vinculado à sessão e é consumido uma única vez ao conectar. Envie-o como subprotocolo WebSocket flowai-ticket.TICKET. POST /audio/transcription-sessions/{id}/connection-ticket emite um novo tíquete e substitui o anterior. Chaves do FlowModels e dos provedores não entram na URL do WebSocket.
Aplicativos enviam frames binários em PCM16 little-endian, mono, 24 kHz. Isso equivale a 48.000 bytes por segundo. Cada frame deve conter um número par de bytes e no máximo 48.000 bytes; envie na velocidade de reprodução. Em fontes de URL, o servidor decodifica o áudio e o cliente recebe apenas eventos. Destinos em redes privadas, credenciais em URLs, playlists HLS e páginas de plataforma não são suportados. Streams MP4/M4A precisam de metadados antes dos dados de áudio ou de MP4 fragmentado; arquivos com metadados no final devem ir para o endpoint de arquivos.
Com {"type":"audio.commit"} você encerra um trecho de fala da OpenAI; o servidor faz isso no máximo a cada dez segundos de áudio. {"type":"session.stop"} ou POST /audio/transcription-sessions/{id}/stop encerra a gravação e processa os resultados pendentes. Os estados são waiting, running, stopping e, em seguida, completed ou failed.
Eventos e reconexão
session.ready: A conexão do cliente está pronta. O áudio pode ser armazenado brevemente em buffer durante o início do provedor.transcript.partial: Substitua o rascunho anterior da mesma section_id por text. Estados intermediários não são armazenados de forma permanente.transcript.final: Texto confirmado com id estável, sequence contínua e segments opcionais. Remova o rascunho correspondente e evite duplicatas usando o ID.connection.interrupted: Interrupção com reason e audio_replayed:false.usage: Duração de áudio até o momento e status de cobrança. O valor exato em EUR vem da chamada REST.session.completed: Encerramento com status, eventualmente error, e a duração do áudio.
Guarde o último número de sequência confirmado. Após uma reconexão do cliente, consulte GET /audio/transcription-sessions/{id}?after_sequence=N. Cada página contém no máximo 1.000 trechos confirmados; siga next_after_sequence até last_sequence. text contém o texto dessa página. Eventos WebSocket e a chamada REST podem se sobrepor, por isso você precisa eliminar duplicatas por ID.
Você pode reconectar uma conexão push interrompida em até 30 segundos com um novo tíquete; depois disso, a gravação é encerrada. Conexões da OpenAI são renovadas de forma controlada após 50 minutos. A ordem dos trechos e a posição na gravação são preservadas. Áudio processado com resultado incerto não é reenviado automaticamente de forma paga. Áudio ainda não enviado fica em buffer por no máximo cinco segundos; ao exceder esse limite, a sessão é encerrada de forma controlada.
Observar um stream de áudio direto
Este exemplo roda com Node.js 22 ou superior. Defina FLOWMODELS_BASE_URL, FLOWMODELS_API_KEY e FLOWMODELS_AUDIO_URL no seu backend. Ele observa o stream por 30 segundos e depois solicita o encerramento.
const response = await fetch(`${process.env.FLOWMODELS_BASE_URL}/audio/transcription-sessions`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FLOWMODELS_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openai/gpt-live-transcribe', source: 'url',
url: process.env.FLOWMODELS_AUDIO_URL, language: 'de',
}),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const session = await response.json();
const socket = new WebSocket(session.websocket_url, [`flowai-ticket.${session.ticket}`]);
let timer;
socket.addEventListener('open', () => {
timer = setTimeout(() => socket.send(JSON.stringify({type: 'session.stop'})), 30000);
});
socket.addEventListener('message', ({data}) => {
const event = JSON.parse(data);
console.log(event);
if (event.type === 'session.completed') socket.close();
});
socket.addEventListener('close', () => clearTimeout(timer));
socket.addEventListener('error', () => console.error('WebSocket connection failed'));
Cobrança, retenção e erros
Trabalhos de arquivo reservam o custo total estimado antes da primeira chamada ao provedor. Sessões ao vivo reservam primeiro 60 segundos e ampliam a reserva antes de transmitir mais áudio. Os preços dependem do modelo, do modo arquivo ou ao vivo e de opções adicionais pagas. O silêncio também pode ser cobrado; o Groq cobra no mínimo dez segundos por chamada ao provedor, também por parte de arquivo. Os tokens reais informados pelo provedor são considerados. usage.cost e usage.cost_micro_eur mostram os custos cobrados, não as reservas ainda abertas.
Use um Idempotency-Key na criação e, diante de uma resposta incerta, repita a mesma requisição com a mesma chave. Uma renovação de tíquete recebe uma nova chave de idempotência. Saldo, bloqueios de chave e limites de equipe também valem durante o processamento. Erros incertos do provedor podem deixar uma reserva aberta até o consumo ser esclarecido.
Os resultados prontos ficam disponíveis por 24 horas após a conclusão. expires_at descreve esse período de retenção; ticket_expires_at, apenas a validade do tíquete. Uploads e arquivos de trabalho são excluídos após a conclusão, o cancelamento ou um erro. Você exclui sessões ao vivo concluídas com DELETE /audio/transcription-sessions/{id}.
Erros típicos: HTTP 422 para opções, limites ou fontes inadequados; HTTP 429 para sessões paralelas demais; HTTP 503 com audio_disabled, audio_model_unavailable ou audio_pricing_unavailable quando a função, o modelo ou o preço não estão disponíveis. Um upgrade de WebSocket com tíquete inválido, expirado ou já usado é recusado. Em trabalhos e sessões aceitos, verifique também status e error; uma consulta de status bem-sucedida ainda não significa uma transcrição bem-sucedida.
Disponibilidade da transcrição ao vivo
A transcrição ao vivo é liberada separadamente e só está disponível para modelos que GET /models lista com o valor live em transcription.modes. A tabela acima mostra qual modo um modelo sabe operar em geral; o que vale para sua integração é a sua lista atual de modelos.