Streaming da Claude API: Principais Recursos Explicados

Se você quer que o Claude pareça rápido, ative o streaming. Em vez de esperar 15–25 segundos por uma resposta completa, os usuários muitas vezes conseguem ver o primeiro token em cerca de 300–800 ms.

Aqui está a versão resumida:

• Eu usaria streaming SSE quando quero que as respostas apareçam à medida que são geradas
• Eu manteria as chamadas ao Claude atrás de um proxy de backend para proteger as chaves de API
• Eu ficaria de olho no TTFT (tempo até o primeiro token), no max_tokens e nas desconexões para controlar a UX e os gastos
• Eu analisaria os eventos transmitidos em ordem: message_start, eventos de bloco de conteúdo, message_delta e, por fim, message_stop
• Eu armazenaria em buffer os fragmentos JSON de ferramentas até o bloco de conteúdo terminar
• Eu me prepararia para conexões interrompidas, porque o Claude não retoma streams nativamente

Alguns números se destacam:

• Haiku 4.5: cerca de 410 ms de TTFT
• Sonnet 4.6: cerca de 720 ms de TTFT
• Opus 4.7: cerca de 980 ms de TTFT
• Timeouts padrão de proxy de 30–60 segundos podem cortar saídas longas
• Timeouts de leitura mais longos, de 120–300 segundos, costumam ser necessários
• Jobs em lote podem custar 50% menos que as taxas padrão por token

Em termos simples: o streaming muda a entrega, não o modelo. A Claude API envia texto em pequenos blocos de eventos por uma conexão ativa, e meu aplicativo reconstrói a resposta final na tela. Para chats, copilotos e assistentes, isso normalmente significa uma sensação melhor para o usuário, menos problemas de timeout por inatividade e mais trabalho nos lados do cliente e do backend.

Aqui está o que mais importa:

Então, se eu fosse configurar isso, pensaria no streaming como uma escolha de UX e infraestrutura, não apenas um flag de API.

Construindo com a Claude API - Parte 4 - Streaming de Respostas

Como o Streaming da Claude API Funciona no Nível do Protocolo

Ativar o streaming não muda o modelo em si. Ele muda como a saída é entregue. Em vez de esperar por uma resposta completa, o Claude envia pequenos blocos à medida que ficam prontos.

Quais configurações de endpoint e de requisição habilitam o streaming

O streaming usa o mesmo endpoint da Claude Messages API, /v1/messages, que uma requisição normal. A única diferença é adicionar "stream": true ao corpo da requisição ^[1][3]. Esse flag muda a conexão de um fluxo padrão de requisição-resposta para Server-Sent Events (SSE), no qual o servidor envia os blocos à medida que são gerados.

Os SDKs oficiais de Python e TypeScript incluem helpers de stream que lidam com a análise de eventos e a montagem da mensagem para você. Quando o stream termina, chamar .get_final_message() em Python ou .finalMessage() em TypeScript retorna a resposta completa, junto com a contagem de tokens e o motivo de parada ^[1][4].

Essas configurações iniciam o stream. A próxima parte é o fluxo de eventos que retorna pela conexão.

Quais eventos chegam durante um stream

Um stream segue uma sequência definida de eventos nomeados. Cada evento carrega os dados que seu cliente precisa para reconstruir a resposta completa da maneira correta.

São esses os dados que seu cliente armazena em buffer e exibe em tempo real. Para saída de texto puro, anexe cada text_delta a um buffer local conforme os eventos chegam. É assim que a string completa da resposta é montada pedaço por pedaço. As entradas de chamadas de ferramentas funcionam de forma um pouco diferente: elas chegam como fragmentos input_json_delta, então você deve armazená-los em buffer primeiro e analisá-los somente após o content_block_stop ^[1][6].

Quando o APIMart é relevante para o streaming do Claude

Se o streaming do Claude fizer parte de um aplicativo multimodelo, o APIMart pode oferecer um único lugar para rotear o acesso ao Claude e o streaming por meio de uma API LLM unificada. Isso costuma importar mais quando você quer o mesmo fluxo de streaming em clientes web e mobile.

Como Adicionar Streaming do Claude a Aplicativos Web e Mobile

SSE, HTTP streaming ou wrappers de WebSocket: qual usar

Depois de entender como o Claude envia eventos transmitidos, o próximo passo é levar esses eventos aos clientes web e mobile. A pergunta principal é simples: qual transporte se encaixa melhor no seu aplicativo?

Para a maioria dos aplicativos baseados em navegador, o SSE é a escolha padrão. Ele funciona bem com a maioria dos proxies e CDNs, e o suporte dos navegadores é simples.

Os WebSockets ainda podem fazer sentido. Se o seu aplicativo já depende de comunicação bidirecional e ao vivo, eles podem se encaixar bem. Mas para um aplicativo de chat padrão, muitas vezes adicionam mais partes móveis do que valem.

Por que um proxy de backend costuma ser a arquitetura mais segura

Depois de escolher o transporte, coloque o tratamento do stream atrás do seu servidor. Mantenha as requisições ao Claude atrás de um proxy de backend para proteger suas chaves de API para diversos modelos ^[9][5].

Essa camada de proxy também é o lugar certo para:

• injetar system prompts
• impor limites de taxa por usuário
• registrar o tempo do primeiro e do último token

Defina X-Accel-Buffering: no para impedir o buffering do proxy ^[2][8]. Conecte também o sinal de abort do cliente ao stream. Assim, se um usuário interromper a geração, a requisição é cancelada de imediato, em vez de gastar tokens em uma resposta que ninguém vai ler.

Mais uma armadilha: timeouts padrão de 30–60 segundos podem cortar respostas longas ^[9][2]. Em produção, use timeouts de leitura de cerca de 120–300 segundos para gerações mais longas.

Como é uma boa UX no lado do cliente durante uma resposta ao vivo

Uma vez que o stream esteja protegido e retransmitido, o trabalho passa para a interface. É aqui que o streaming parece suave ou desajeitado.

Mostre um indicador de "Pensando..." ou um spinner assim que o usuário enviar um prompt. Isso cobre o atraso do primeiro token. Assim que o primeiro content_block_delta chegar, remova o indicador e comece a renderizar o texto.

Depois, anexe cada text_delta conforme ele chega, para que a resposta apareça com um efeito de máquina de escrever. Para evitar que a interface engasgue, agrupe as atualizações com requestAnimationFrame para não disparar re-renderizações em excesso. A rolagem automática deve acompanhar a resposta enquanto ela é gerada, mas deve recuar se o usuário rolar para cima para ler conteúdo mais antigo.

Inclua sempre um botão de "Parar" ligado ao AbortController para que ele possa cancelar a requisição Fetch. Isso deve encerrar o stream de forma limpa, sem apagar o texto que já está na tela.

Se a conexão cair, mantenha a saída parcial visível. Para a recuperação, guarde esse texto parcial e reinicie com um prompt de continuação, já que o Claude não retoma nativamente um stream interrompido ^[3][1].

Como Gerenciar Latência, Custo e Confiabilidade em Produção

Uma vez que o stream esteja ativo, o trabalho em produção se resume a três controles: latência, gasto e recuperação.

Como o streaming muda a latência percebida

A principal métrica de UX aqui é o Tempo até o Primeiro Token (TTFT): o tempo até a primeira palavra aparecer. Em um aplicativo de streaming, esse primeiro token visível molda toda a sensação do produto. Se ele aparece rápido, o aplicativo parece responsivo. Se demora, os usuários percebem.

Os benchmarks mostram diferenças claras entre os modelos Claude: o Haiku 4.5 atinge cerca de 410 ms de TTFT, o Sonnet 4.6 fica em torno de 720 ms e o Opus 4.7 chega a aproximadamente 980 ms ^[3]. A regra simples é usar o modelo mais rápido que ainda atenda ao seu padrão de qualidade.

O tamanho do prompt também importa. Janelas de contexto maiores podem empurrar o TTFT para 1–3 segundos ^[5]. Então, se o seu system prompt tem instruções extras, regras antigas ou exemplos inflados, cortá-los pode deixar o aplicativo bem mais ágil.

Como acompanhar o uso de tokens e controlar os custos em USD

Streaming e lote custam o mesmo por token. A única coisa que muda é quando a saída chega. As contagens de tokens estão incluídas no próprio stream: o evento message_start inclui usage.input_tokens, e o evento message_delta, perto do fim, inclui o usage.output_tokens final acumulado ^[1][4]. Seu backend deve armazenar esses dados finais de uso após o stream terminar, para que o faturamento permaneça preciso.

Defina max_tokens em cada requisição. Isso dá a você um limite rígido e evita que gerações longas aumentem os custos ^[1][11]. Você também deve ficar atento a desconexões do cliente no lado do servidor. Se o usuário foi embora e a geração continua rodando, você ainda está queimando tokens sem motivo ^[5][7].

Para jobs que não precisam de saída ao vivo, a matemática muda. Resumo em lote, processamento offline e geração de relatórios durante a noite são bons exemplos. Nesses casos, a Batch API oferece um desconto de 50% sobre as taxas normais de token ^[5][10].

O Claude 3.5 Sonnet custa cerca de US$ 3,00 por 1 milhão de tokens de entrada e US$ 15,00 por 1 milhão de tokens de saída no streaming padrão ^[8]. Com a Batch API, as cargas de trabalho assíncronas custam metade disso.

Esses números de uso também ajudam no faturamento e no monitoramento de limites de taxa. Para mais estratégias de gerenciamento de requisições de alto volume, veja nossas dicas de custo de API de IA.

Como evitar streams interrompidos e recuperar com segurança

O Claude não tem um recurso de retomada no lado do servidor ^[1][3]. Se um stream cair, envie a saída parcial em uma nova requisição e peça ao Claude para continuar a partir do ponto de interrupção.

Só repita as falhas que provavelmente se resolverão sozinhas.

Depois disso, o passo final é escolher quais recursos de streaming importam mais.

Conclusão: Quais Recursos de Streaming do Claude Importam Mais

Depois de analisar latência, custo e confiabilidade, o streaming do Claude se resume a três coisas: responsividade percebida, sinais de eventos claros e tratamento de erros sólido.

O streaming importa porque a entrega do primeiro token faz o Claude parecer rápido e responsivo.

O fluxo de eventos SSE dá a você deltas de texto, contagens de uso e sinais de erro em tempo real ^[1][3].

Use um proxy de backend para proteger as chaves, desativar o buffering e lidar com desconexões ^[2][8]. Para aplicativos multimodelo, o APIMart pode centralizar o streaming, o log e o faturamento do Claude.

Em produção, um TTFT rápido, o acompanhamento de uso e a resiliência do proxy são o que mais importa.

Perguntas Frequentes

Quando devo usar streaming em vez de uma resposta normal da Claude API?

Use streaming quando seu aplicativo for voltado ao usuário. Ele envia tokens à medida que são gerados, então as respostas parecem quase instantâneas. Essa pequena mudança pode fazer todo o produto parecer mais rápido e fluido.

O streaming funciona melhor para chat em tempo real, respostas longas e fluxos de trabalho de agentes com chamadas de ferramentas. Ele também ajuda a evitar timeouts quando as saídas ficam longas ou os limites de tokens são altos.

Dispense-o para requisições curtas e simples ou jobs em lote, nos quais a taxa de transferência importa mais do que a latência.

O que devo fazer se um stream do Claude for interrompido no meio da resposta?

Se um stream do Claude for interrompido, os Server-Sent Events não retomam sozinhos de onde pararam. Seu aplicativo precisa lidar com essa parte.

Quando a conexão cai, você pode repetir a requisição completa ou mostrar a saída parcial que já salvou. Use um bloco try/except para capturar APIConnectionError ou APIStatusError, e mantenha uma referência ao conteúdo que você acumulou até agora.

Se você quiser que o stream continue com menos atrito, acompanhe o ID do último evento e reproduza manualmente o stream a partir desse ponto.

Como posso reduzir os custos de streaming sem prejudicar a UX?

Foque no ajuste de prompts e no manejo eficiente das sessões. Defina limites rígidos de max_tokens, mantenha os prompts curtos e adicione uma opção de cancelamento antecipado para que os usuários possam parar a geração assim que tiverem o que precisam.

Para cargas de trabalho em lote que não precisam de troca imediata, use o modo sem streaming. Para um acompanhamento de custos preciso, espere o evento final message_stop em vez de estimar a partir de blocos intermediários.