DeepSeek Responses API: como usar streaming e ferramentas

A DeepSeek Responses API permite usar parte do formato Responses com a infraestrutura hospedada pela própria DeepSeek. Ela facilita a migração de clientes que já usam responses.create(), mas não oferece paridade integral com a API da OpenAI: o suporte varia por modelo, campo, ferramenta e tipo de entrada.

Situação atual — 23/08/2026: a DeepSeek documenta deepseek-v4-flash, deepseek-v4-pro e deepseek-v4-flash-vision-exp na Responses API. O Vision Exp aceita imagens por input_image, usando image_url ou file_id. O teste autenticado de 05/08 com Pro recebeu HTTP 400 antes do Pro-0813 e permanece abaixo apenas como evidência histórica; ele não descreve o suporte documentado atual e não foi repetido.

Este é um guia independente em português brasileiro. Não somos a DeepSeek nem a OpenAI e não representamos parceria, suporte ou endosso dessas empresas. Para autenticação, modelos e cobrança em todas as interfaces, consulte o guia geral da DeepSeek API.

Resultado histórico em 05/08/2026: Responses API antes do Pro-0813

Entre 16:21 e 16:24 BRT de 05/08/2026, executamos oito chamadas POST autenticadas em https://api.deepseek.com/responses, além de uma consulta GET ao catálogo de modelos. Usamos fetch nativo, sem SDK, com uma chave temporária. Os prompts eram sintéticos, em português do Brasil, e não continham dados pessoais, documentos, credenciais ou segredos.

Teste	Resultado observado	Uso devolvido	Latência desta sessão
Resposta comum, limite 160	HTTP 200; incomplete por max_output_tokens; sem texto final	41 entrada + 160 saída, todos os 160 de reasoning	330 ms
Resposta comum, limite 800	HTTP 200; completed; modelo devolvido deepseek-v4-flash	41 entrada + 308 saída = 349	335 ms
Streaming	124 eventos; sequência crescente; terminal response.completed; sem data: [DONE]	27 entrada + 112 saída = 139	324 ms até headers; 2.008 ms total
Function com tool_choice=required	HTTP 400: Thinking não suporta essa escolha forçada	Sem usage	317 ms
Function em modo automático	HTTP 200; função calcular_frete_demo; argumentos válidos; nenhuma ação externa executada	355 entrada + 102 saída = 457	319 ms
web_search	HTTP 200; quatro itens web_search_call; resposta apontou para a documentação oficial	9.693 entrada, 5.888 em cache, + 892 saída = 10.585	1.363 ms
store:true	HTTP 200; a resposta devolveu store:false	21 entrada + 133 saída = 154	304 ms
V4 Pro	HTTP 400; Responses recusou deepseek-v4-pro naquele momento	Sem usage	307 ms

Conclusão: o V4 Flash completou resposta comum, streaming, function call automática, busca web e a chamada com store:true. O teste também confirmou limites úteis: um orçamento curto pode ser consumido integralmente por reasoning; tool_choice=required falhou com Thinking; store:true não ativou persistência; e o V4 Pro não estava disponível nessa interface.

Metodologia e limites do teste

• Ambiente: requisições HTTPS com fetch nativo; nenhum SDK foi usado.
• A versão exata do runtime não foi registrada, o que impede reprodução byte a byte do ambiente.
• Modelo principal: deepseek-v4-flash; o catálogo autenticado listou Flash e Pro.
• Prompts sintéticos em pt-BR; nenhuma senha, documento, dado pessoal ou segredo foi enviado.
• A função demonstrativa recebeu CEP e peso fictícios e não executou frete, cobrança ou serviço externo.
• O raciocínio bruto não é publicado. Registramos apenas status, tipos de evento, uso, texto final permitido e hashes SHA-256.
• A latência inclui rede e infraestrutura desta sessão. Uma chamada por condição não é benchmark de velocidade, qualidade ou disponibilidade.
• Os HTTP 400 foram testes controlados de compatibilidade. Não provocamos 401, 402, 429, 500 ou 503.

Artefato preservado	SHA-256
Request do streaming	9edff0ef7ff3f699185247bd6cee9abdf8face938680fef280927b2dfa7fe2c5
Stream completo recebido	0b33825383642251027c8ea2092f539f87c92bf84378ad9a94772449b4f8fc61
Request de web search	36fc783d67630d705cb4d08c342b3ecbe52bb1c4085e495d9f98f36df5a3d1ee
Response de web search	7438e6b1fb63d500bb783cc79377305b3512bb50eb3a1ac48f7394108e7d44be
Request com V4 Pro	2b9077e3478266b4342069e47a4a4ee2d13728ea97d06de9ebf22edafe53a1d3
Erro devolvido para V4 Pro	ae0a4906c211c30a2cd54ac052990f03b2396a05e0595f1e15af420b24167f48

Limite da verificação pública: os corpos completos permanecem no arquivo editorial interno e não são publicados porque o stream inclui reasoning bruto. Os hashes permitem detectar alterações nos arquivos preservados, mas não reconstroem o conteúdo nem reproduzem a sessão. A metodologia e os exemplos podem ser repetidos em outra conta, com resultados potencialmente diferentes.

Resumo rápido: suporte documentado em 23/08/2026

Item	Situação atual
Base URL	https://api.deepseek.com
Operação no SDK	client.responses.create()
Modelos	deepseek-v4-flash, deepseek-v4-pro e deepseek-v4-flash-vision-exp
Estado no servidor	Stateless; previous_response_id, conversation e store não oferecem persistência
Texto	Suportado nos três modelos
Imagens	Suportadas com Vision Exp em input_image, por image_url ou file_id
Arquivos genéricos	Não suportados; a Files API atual armazena imagens, não PDFs ou documentos para RAG
Papéis de mensagem	user, assistant, system e developer; developer é tratado como user
Ferramentas	function e web_search; apply_patch é o único nome de ferramenta custom aceito
Streaming	Eventos SSE tipados; termina em response.completed, response.incomplete ou response.failed, sem data: [DONE]
Uso	Entrada, cache, saída e reasoning no objeto usage

O teste de 05/08 acima continua válido apenas como registro histórico anterior ao Pro-0813 e ao Vision Exp. Não use a matriz antiga “Status em 05/08/2026” como descrição do suporte atual.

Responses API ou Chat Completions?

Critério	Responses API	Chat Completions
Operação	responses.create()	chat.completions.create()
Modelos documentados	Flash, Pro e Vision Exp	Flash, Pro e Vision Exp
Entrada principal	input e instructions	messages
Imagem	input_image com Vision Exp	image_url ou file com Vision Exp
Estado hospedado	Não	A aplicação também reenvia o histórico necessário
Final do streaming	response.completed, incomplete ou failed	data: [DONE]

Use Responses quando seu cliente espera eventos e itens desse formato e todos os recursos necessários aparecem na matriz oficial. Use Chat Completions quando sua integração já trabalha com messages ou precisa do formato específico dessa interface. A escolha não é determinada pelo Pro: Flash, Pro e Vision Exp estão documentados nas duas interfaces.

Primeira chamada em Python

import os
from openai import OpenAI

api_key = os.environ.get("DEEPSEEK_API_KEY")
if not api_key:
    raise RuntimeError("Defina DEEPSEEK_API_KEY no servidor.")

client = OpenAI(
    api_key=api_key,
    base_url="https://api.deepseek.com",
)

response = client.responses.create(
    model="deepseek-v4-flash",
    instructions="Responda em português do Brasil.",
    input="Explique cache de contexto em duas frases.",
    max_output_tokens=800,
)

if response.status != "completed":
    raise RuntimeError(f"Resposta não concluída: {response.status}")

print(response.output_text)
print(response.usage)

O primeiro teste desta revisão usou max_output_tokens=160 e terminou como incomplete, porque todo o orçamento de saída foi consumido pelo reasoning. A repetição com 800 concluiu. Isso não define um número universal: trate os três estados terminais e ajuste limites com base na tarefa.

Exemplo com imagem

Com deepseek-v4-flash-vision-exp, envie um item input_image com image_url ou file_id. Os dois campos são mutuamente exclusivos. Imagens são permitidas em mensagens user ou developer; em system ou assistant, a API retorna 400.

Use file_id somente para uma imagem enviada à Files API. PDFs e outros documentos genéricos não são entradas documentadas dessa interface. Veja o exemplo oficial de Vision na Responses API.

Streaming: eventos, ordem e término

Com stream:true, a API devolve eventos SSE com type e sequence_number. No teste, os 124 números de sequência cresceram sem regressão. O fluxo passou por eventos de criação, reasoning, texto final e terminou em response.completed; não apareceu o sentinela data: [DONE].

• response.created e response.in_progress iniciaram o fluxo.
• response.reasoning_text.delta apareceu no stream, mas não é publicado nem deve ser exibido como resposta final.
• response.output_text.delta transportou o texto destinado ao usuário.
• response.completed, response.incomplete ou response.failed deve encerrar o processamento.

Function calls e busca web

Uma function call é uma solicitação estruturada, não autorização. Ao forçar tool_choice="required" com Thinking, a API retornou HTTP 400. Sem a escolha forçada, o V4 Flash chamou calcular_frete_demo com {"cep":"01001-000","peso_kg":2.5}. Validamos o JSON localmente e encerramos o teste sem executar função externa.

Na busca web, uma pergunta sobre o título da documentação oficial gerou quatro itens web_search_call e consumiu 10.585 tokens no fluxo. O resultado encontrou “Using the Responses API” e o domínio oficial. A observação confirma a ferramenta nesse caso, não precisão universal da busca. Cada chamada e resumo adicional pode elevar o consumo.

Estado, armazenamento e privacidade

A implementação é documentada como stateless. previous_response_id e conversation não são suportados. No teste, enviar store:true produziu HTTP 200, mas o objeto devolvido manteve store:false. Uma resposta bem-sucedida não prova que um campo ignorado produziu efeito.

Se o produto precisa de continuidade, o backend deve armazenar e reenviar somente o contexto autorizado e necessário. Não envie senhas, chaves, prontuários, dados bancários ou segredos comerciais. Defina autenticação, autorização, retenção e exclusão no seu próprio sistema.

Preços atuais: as tarifas de pico e fora de pico estão em vigor desde 16/08/2026, às 16:00 UTC. O pico ocorre das 01:00 às 04:00 UTC e das 06:00 às 10:00 UTC, de segunda a sexta-feira; todos os demais horários são fora de pico. O custo observado em 05/08 abaixo permanece calculado com a tarifa vigente naquela data e não foi recalculado retroativamente. Consulte o guia de preços atualizado.

Tokens e custo observado

As seis respostas com HTTP 200 reportaram 11.885 tokens no total. Aplicamos as tarifas regulares do V4 Flash verificadas em 05/08/2026 — US$ 0,0028 por 1M tokens de entrada com cache, US$ 0,14 sem cache e US$ 0,28 de saída — ao usage de cada chamada. O total calculado foi US$ 0,0010950464.

O valor exclui as duas respostas 400, que não devolveram usage, além de impostos, câmbio, infraestrutura e conferência de fatura. A DeepSeek anunciou a mudança para 16/08/2026 às 16:00 UTC; custos desta coleta permanecem calculados com a tarifa vigente em 05/08. Veja a metodologia de preços e o estudo de tokens em português brasileiro.

Checklist antes de usar em produção

• Use deepseek-v4-flash ou deepseek-v4-pro para texto; use deepseek-v4-flash-vision-exp para imagem. Confirme a matriz oficial no dia do deploy.
• Mantenha a chave no backend ou em um secret manager.
• Envie somente conteúdo autorizado e necessário. Para imagens, valide formato, tamanho, origem, permissões e retenção; a Files API pode manter um upload permanentemente quando nenhuma expiração é definida.
• Defina allowlist de parâmetros, ferramentas e funções.
• Trate argumentos do modelo como entrada não confiável.
• Processe completed, incomplete e failed.
• Registre versão do cliente, data, modelo solicitado e devolvido, usage, custo e erros.
• Não exponha reasoning bruto, credenciais, headers ou conteúdo sensível em logs e prints.

Para diagnóstico, consulte os códigos de erro da DeepSeek API. Para clientes e agentes, consulte a matriz de IDEs, CLIs e ferramentas de terceiros.

Perguntas frequentes

A DeepSeek Responses API é igual à API da OpenAI?

Não. A DeepSeek oferece compatibilidade com parte do formato Responses, mas publica uma matriz própria de campos suportados, parciais, ignorados e não suportados.

O V4 Pro funciona na Responses API?

Sim, ele consta na documentação atual. O HTTP 400 observado por este site em 05/08/2026 antecede o lançamento GA do Pro-0813 e foi preservado como resultado histórico; a chamada ainda não foi repetida por este site.

Posso enviar imagens ou PDFs?

Imagens, sim: use deepseek-v4-flash-vision-exp e um bloco input_image com image_url ou file_id. PDFs e outros arquivos genéricos não são entradas documentadas da Responses API. A Files API atual aceita imagens; para um PDF autorizado, extraia e valide o texto no seu próprio pipeline.

A API guarda a conversa?

A interface é stateless. previous_response_id e conversation não funcionam, e store:true devolveu store:false no teste.

Fontes oficiais

• Using the Responses API
• Responses API reference
• Models & Pricing
• Thinking Mode
• Integrate with Codex

Transparência editorial: a documentação foi reconferida em 23 de agosto de 2026. Os testes autenticados, custos, hashes e latências desta página permanecem datados de 5 de agosto de 2026.

Fontes desta atualização: Vision e Files API.