API do Whisper-1: sua primeira transcrição de áudio

Uma primeira solicitação à API do Whisper-1 precisa de um arquivo de áudio, um ID de modelo explícito e um formato de saída. No SeedRouter, você envia a gravação, salva o ID da tarefa retornado e baixa a transcrição quando a tarefa termina. Comece com uma gravação curta cujas palavras você já conhece: isso facilita perceber palavras ausentes e grafias incomuns.

Este guia segue o contrato assíncrono do SeedRouter. Não é um exemplo síncrono do SDK da OpenAI que possa ser usado sem alterações. A página do modelo Whisper-1 tem o Playground e o preço atual; a referência da API lista todos os campos e as verificações de compatibilidade pendentes. ^[1]

Prepare uma gravação

Use fala que você tenha permissão para processar. Um WAV ou MP3 curto é um bom ponto de partida. O limite atual de envio é de 26.214.400 bytes; o arquivo deve conter áudio legível com duração mensurável. A extensão .mp3 não torna um arquivo de texto renomeado um áudio válido. A referência separa os nove formatos de entrada documentados daqueles que passaram por verificações reais. ^[1]

A gravação abaixo é uma criação original de fala sintética em inglês, feita para este tutorial. Sua forma de onda aparece na capa. A frase citada na capa vem do roteiro da gravação, não de uma afirmação de precisão.

Baixe a amostra de 10,31 segundos. O roteiro diz: “This is a sample recording for an audio transcription tutorial. Our meeting starts at nine thirty on Monday. Please bring the project notes and review the final checklist before we begin.”

Guarde uma chave de API em uma variável de ambiente no servidor. Não a coloque em uma página web pública, em um pacote de aplicativo móvel ou em uma captura de tela compartilhada. O exemplo Python abaixo usa requests e lê SEEDROUTER_API_KEY do ambiente.

Envie a solicitação à API do Whisper-1 uma só vez

Escolha json para a primeira solicitação. Assim você pode ler o campo text do resultado baixado sem lidar com códigos de tempo de legendas. A parte multipart file deve conter bytes reais; fornecer uma URL como valor não equivale a enviar o arquivo. Deixe o cliente definir o tipo de conteúdo multipart e o delimitador. ^[1]

Salve este código como transcribe.py. Ele grava um marcador de envio antes do POST e salva depois o ID da tarefa aceita. Ao executar novamente, lê essa tarefa existente. Se o resultado do POST for incerto, o marcador impede que o script crie uma duplicata acidental.

import json
import os
from pathlib import Path

import requests

base = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
state = Path("whisper-task.json")
audio = Path("recording.wav")

if not state.exists():
    if not 0 < audio.stat().st_size <= 26_214_400:
        raise ValueError("Choose a nonempty recording within the upload limit")
    with state.open("x") as marker:
        json.dump({"status": "submission_unconfirmed"}, marker)
    with audio.open("rb") as recording:
        response = requests.post(
            f"{base}/audio/transcriptions",
            headers=headers,
            files={"file": (audio.name, recording, "audio/wav")},
            data={"model": "whisper-1", "response_format": "json"},
            timeout=180,
            allow_redirects=False,
        )
    response.raise_for_status()
    accepted = response.json()
    task_id = accepted.get("id")
    if not isinstance(task_id, str) or not task_id.startswith("task_"):
        raise RuntimeError("Submission could not be confirmed; check task history")
    state.write_text(json.dumps({"id": task_id}), encoding="utf-8")

saved = json.loads(state.read_text(encoding="utf-8"))
if "id" not in saved:
    raise RuntimeError("Check task history before submitting another recording")

response = requests.get(
    f"{base}/tasks/{saved['id']}", headers=headers, timeout=30,
    allow_redirects=False,
)
response.raise_for_status()
task = response.json()
print(task["status"])
if task["status"] == "completed":
    result = requests.get(task["output"]["url"], timeout=60)
    result.raise_for_status()
    print(result.json()["text"])
elif task["status"] == "failed":
    print(task["error"])

Execute python transcribe.py. Se aparecer processing, espere alguns segundos e execute o mesmo comando novamente. Ele lerá o ID salvo em vez de enviar novamente. Guarde um arquivo de estado separado para cada gravação intencionalmente nova. Um timeout do cliente, por si só, não determina uma falha da tarefa.

Leia a transcrição concluída

A resposta de aceitação contém id, model, status e created_at. A conclusão acrescenta output.url e output.format. Essa URL aponta para o arquivo de resultado; não é uma tarefa de geração de mídia que exige outra solicitação paga. Uma GET baixa o resultado. ^[1]

Leia as palavras enquanto escuta a gravação. Confira nomes, números e limites das frases antes de usar o texto como legenda ou citação exata. Uma transcrição é um rascunho do que foi dito, e as marcações de tempo não eliminam a necessidade de revisão.

As verificações locais de ponta a ponta em 19 de outubro de 2026 concluíram os cinco formatos de transcrição e uma tradução com entrada em inglês. Elas estabelecem o comportamento de entrega e cobrança para as gravações testadas. Não estabelecem um percentual de precisão nem a qualidade de tradução entre idiomas.

Escolha texto, marcações de tempo ou legendas

Para marcações de tempo por palavra, envie response_format=verbose_json e um campo multipart repetido chamado timestamp_granularities[] com valor word. Acrescente outra parte com valor segment se precisar de ambos. No Python requests, use uma lista de pares (name, value) para campos repetidos. Cada marcação de tempo está em segundos. ^[2]

Marcações de tempo por palavra e identificação de falantes são saídas diferentes. O Whisper-1 não transforma uma reunião em uma transcrição com falantes identificados só porque você solicita segmentos. Também não transmite texto parcial: stream é ignorado neste modelo. Omita chunking_strategy para o fluxo verificado; selecionar auto explicitamente não passou na verificação real de compatibilidade. ^[1]

Acrescente idioma e contexto de grafia quando necessário

Um language=en opcional informa à solicitação de transcrição que a entrada está em inglês. Omita se quiser detecção. Se o nome de um produto puder ser confundido ao ouvir, coloque a grafia correta em prompt, usando o mesmo idioma do áudio. Prompts do Whisper fornecem contexto; não funcionam como instruções de chat que imponham um formato específico de maneira confiável. ^[3]

Mantenha o contexto relevante para o trecho. O Whisper considera apenas os últimos 224 tokens do próprio tokenizador. Enviar um documento longo não dá à gravação um glossário ilimitado, e contar caracteres não substitui essa regra de tokens de forma confiável.

Para traduzir para o inglês, mude o endpoint para /audio/translations. Os cinco campos da solicitação são file, model, prompt, response_format e temperature. A tradução produz inglês; não há seletor de idioma de destino. Use um prompt em inglês se fornecer um. ^[4]

Confira o custo antes de ampliar o fluxo de trabalho

A tabela de preços atuais abaixo usa a duração medida do áudio. Uma transcrição mais longa não aumenta a cobrança por duração da mesma gravação. A duração de cada arquivo é arredondada para cima em segundos inteiros e depois convertida em unidades de medição de áudio. A referência da API inclui o cálculo exato, e o Playground mostra uma estimativa quando consegue ler a duração da gravação. Solicitações que falham não são cobradas.

Antes de processar muitos arquivos, valide uma gravação representativa e examine o resultado. Guarde o ID da tarefa de cada gravação para se recuperar de uma interrupção de conexão consultando o estado existente. Veja a referência completa dos parâmetros antes de acrescentar legendas ou combinações de formatos menos testadas.

Perguntas da primeira integração

Posso usar o exemplo do SDK Python da OpenAI sem alterações?

Não. Os campos de entrada multipart são conhecidos, mas o SeedRouter retorna um ID de tarefa assíncrono. Um cliente síncrono que espera text na resposta POST precisa de adaptação. O exemplo deixa explícitos o envio e a leitura do resultado.

Por que meu resultado JSON não tem marcações de tempo por palavra?

O formato padrão json é uma resposta voltada a texto. Solicite verbose_json junto com a granularidade de tempo word. Os tempos dos segmentos, sozinhos, não criam uma entrada por palavra.

Devo enviar outro POST depois de um timeout?

Confira primeiro o ID da tarefa salvo ou o histórico de tarefas. A resposta pode ter se perdido após a aceitação. Ler uma tarefa existente evita criar outra solicitação para a mesma gravação.

O Whisper-1 será desativado?

A OpenAI anunciou 26 de fevereiro de 2027 como data de desativação do Whisper em sua própria API. Esse aviso não estabelece uma data de desativação para este serviço. Inclua avisos de ciclo de vida na sua lista de manutenção ao criar uma integração. ^[5]

Fontes

[1] Referência da API Whisper-1 do SeedRouter e status de verificação, verificados em 19 de outubro de 2026.

[2] Referência de transcrição da OpenAI.

[3] Guia de prompts do Whisper da OpenAI.

[4] Referência de tradução da OpenAI.

[5] Aviso de descontinuação dos modelos de transcrição da OpenAI.