ChatCompletions vs Anthropic Messages vs Responses API: Análise e Comparativo dos Formatos de API do DeepSeek V4 Pro

DeepSeek-V4-Pro-0813 atingiu disponibilidade geral em 12 de agosto de 2026, sendo servido sob o ID de modelo perene deepseek-v4-pro em https://api.deepseek.com, juntamente com o mais barato deepseek-v4-flash (Unite.AI cobriu o anúncio de GA). As especificações principais são robustas: uma janela de contexto de 1M de tokens, saída máxima de 384K, chamada de ferramenta (tool calling), saídas estruturadas e três modos de pensamento que expõem o rastro de raciocínio do modelo em um campo reasoning_content.

A parte incomum não são as especificações. É que um único modelo responde em três dialetos de API. O V4 Pro aceita requisições OpenAI ChatCompletions, requisições Anthropic Messages e requisições para a própria API Responses da DeepSeek. Aponte seu código SDK OpenAI existente para ele, aponte um agente construído para Claude para ele, ou conecte-o a um loop de agente estilo Codex, os mesmos pesos, três formatos de comunicação.

Ninguém ainda apresentou os três formatos da API DeepSeek V4 Pro lado a lado, então este guia o faz. Você verá uma requisição funcional por formato, onde os formatos realmente diferem, uma tabela de comparação e como testar todos os três a partir de um único projeto Apidog com variáveis de ambiente compartilhadas. Se você deseja a configuração da conta e o passo a passo da primeira chamada, comece com como usar a API DeepSeek V4 e retorne.

TL;DR

• DeepSeek-V4-Pro-0813 está em GA por trás de deepseek-v4-pro em https://api.deepseek.com; deepseek-v4-flash compartilha as mesmas interfaces a um preço mais baixo.
• Ele fala três formatos de API: OpenAI ChatCompletions (funciona com o SDK padrão openai alterando base_url), Anthropic Messages (substituição direta para requisições no formato do SDK anthropic, incluindo Claude Code), e a API Responses da DeepSeek (sua interface mais recente, construída para agentes estilo Codex e fluxos de trabalho com estado).
• Especificações: 1M de contexto, 384K de saída máxima, chamada de ferramenta (tool calling), saídas estruturadas, três modos de pensamento com reasoning_content.
• Preço: $0.435/M tokens de entrada (cache miss), $0.003625/M em um acerto de cache, $0.87/M de saída.
• Os formatos diferem no posicionamento do prompt de sistema, na semântica de max_tokens, na forma do esquema da ferramenta e na forma do evento de streaming; detalhes abaixo.
• Um projeto Apidog com {{DEEPSEEK_API_KEY}} e variáveis de URL base por formato permite que você envie o mesmo prompt para os três e compare as respostas brutas.

Por que um modelo fala três dialetos

Trata-se de uma estratégia de compatibilidade de ecossistema: cada formato de API é uma base instalada de ferramentas que a DeepSeek obtém gratuitamente. ChatCompletions é a língua franca, milhares de SDKs e frameworks podem chamar o V4 Pro com uma mudança de uma linha em base_url. O formato Anthropic Messages visa equipes que construíram sobre Claude: agentes, harnesses de avaliação e ferramentas como Claude Code podem apontar para o V4 Pro sem uma reescrita. E a API Responses é a aposta da DeepSeek em agentes: o deepseek-v4-flash a obteve em julho para compatibilidade estilo Codex, e o V4 Pro é lançado com ela em GA para fluxos de trabalho com estado e multi-etapas.

O V4 Pro também está listado em agregadores (veja a página do OpenRouter para deepseek-v4-pro-0813), mas a história dos três formatos se aplica à API proprietária da DeepSeek, que é o que este artigo testa. Para uma visão mais ampla da família V4, veja como usar o DeepSeek V4.

Formato 1: OpenAI ChatCompletions

Este é o formato que você já conhece: um array messages onde o prompt do sistema vai junto como a primeira mensagem com role: "system", e um limite opcional de tokens máximos. A configuração é a mesma para todos os três formatos, então aqui está uma vez: sua chave de API DeepSeek, a URL base da DeepSeek e o model definido como deepseek-v4-pro (ou deepseek-v4-flash). Apenas o endpoint e o formato do corpo mudam.

from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "You are a precise technical writer."},
        {"role": "user", "content": "Explain idempotency keys in two sentences."}
    ],
)

print(response.choices[0].message.content)

Nenhum novo SDK, nenhum novo esquema de autenticação. A chamada de ferramenta (tool calling) usa o formato aninhado familiar de function, e o streaming chega como deltas de chat.completion.chunk terminados por data: [DONE], correspondendo à especificação da OpenAI. Um comportamento específico do V4 a ser planejado: com um modo de pensamento ativo, o rastro de raciocínio chega em um campo reasoning_content separado ao lado de content, então os parsers devem tolerar o campo extra.

Quando usá-lo: você possui ferramentas OpenAI existentes, frameworks estilo LangChain ou bibliotecas internas que já "falam" ChatCompletions. É o caminho de menor atrito e o mais fácil de verificar, a anatomia da requisição é idêntica ao que é coberto em testando a API ChatGPT com Apidog, com apenas o host e o modelo trocados.

Formato 2: Anthropic Messages

O formato Messages parece similar à primeira vista e difere de maneiras que quebram a tradução ingênua. Três diferenças importam mais, todas herdadas da especificação Anthropic:

1. O prompt do sistema sai do array. Ele é um parâmetro system de nível superior; o array messages contém apenas turnos alternados de user e assistant.
2. max_tokens é obrigatório, não opcional. Toda requisição declara um orçamento de saída explícito. Com a saída máxima de 384K do V4 Pro, esse limite é generoso, mas você deve declará-lo.
3. As definições de ferramenta são planas. Cada ferramenta possui name, description e um input_schema no nível superior, sem wrapper function aninhado. As chamadas de ferramenta retornam como blocos de conteúdo tool_use, e você retorna os resultados como blocos tool_result dentro de uma mensagem do usuário.

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/anthropic", # Anthropic-compatible base; confirm current path in DeepSeek's docs
)

message = client.messages.create(
    model="deepseek-v4-pro",
    max_tokens=8192,
    system="You are a precise technical writer.",
    messages=[
        {"role": "user", "content": "Explain idempotency keys in two sentences."}
    ],
)

print(message.content[0].text)

As respostas retornam como uma lista de blocos de conteúdo em vez de uma única string, e o streaming usa eventos SSE tipados message_start, content_block_delta, message_stop em vez de blocos uniformes. A autenticação segue as convenções de cabeçalho da especificação Anthropic em vez de um token bearer. Os documentos da API DeepSeek contêm os detalhes atuais da superfície compatível.

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=$DEEPSEEK_API_KEY
export ANTHROPIC_MODEL=deepseek-v4-pro

Quando usá-lo: suas ferramentas foram construídas para Claude. Se sua equipe já envia requisições no formato Messages para modelos Anthropic (a mesma anatomia coberta em nosso guia da API Claude Opus 5), este formato permite que você faça um teste A/B entre DeepSeek e Claude dentro do mesmo ambiente, com os mesmos corpos de requisição e os mesmos manipuladores de streaming.

Formato 3: API Responses da DeepSeek

A API Responses é a interface mais recente da DeepSeek, e a razão de sua existência são os agentes. O V4 Flash a adotou em julho para que agentes estilo Codex pudessem usar modelos DeepSeek; o V4 Pro foi lançado com ela no primeiro dia. O formato da requisição segue a especificação OpenAI Responses: você envia input (uma string ou uma lista de itens tipados) mais instructions de nível superior, em vez de um único array de mensagens.

curl https://api.deepseek.com/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "instructions": "You are an API review agent. Be terse.",
    "input": "Review this OpenAPI diff and list any breaking changes: [diff here]",
    "stream": false
  }'

Três coisas separam este formato dos outros dois, todas seguindo a especificação Responses:

• O estado pode residir no lado do servidor. Em vez de reenviar a conversa completa a cada turno, uma requisição subsequente pode referenciar a resposta anterior por ID (previous_response_id na especificação), o que mantém os loops de agente multi-etapas baratos para orquestrar.
• A saída é uma lista de itens tipados, não uma única mensagem: itens de raciocínio, itens de texto e itens de chamada de ferramenta chegam como entradas distintas, o que é adequado para agentes que agem de forma diferente em cada tipo de item.
• O streaming é semântico. Em vez de deltas de texto brutos, o stream emite eventos nomeados (response.output_text.delta, response.completed e similares), para que um agente possa reagir às mudanças de ciclo de vida sem fazer parsing de chunks com regex.

A chamada de ferramenta (tool calling) também existe aqui, com definições de ferramenta e itens function_call/function_call_output moldados de acordo com a especificação Responses, em vez de qualquer um dos formatos mais antigos. Onde os detalhes de implementação da DeepSeek vão além da especificação, considere api-docs.deepseek.com como a fonte da verdade.

Quando usá-lo: integrações de agentes e estilo Codex, fluxos de trabalho longos e multi-etapas, ou qualquer sistema onde o estado de conversação gerenciado pelo servidor e os itens de saída tipados simplificam seu código de orquestração. Para uma simples conclusão de chat, é mais complexidade do que você precisa.

Os três formatos lado a lado

Mesmo modelo, mesmo preço, três contratos. As diferenças estão inteiramente no nível de comunicação (wire level), que é exatamente o tipo de diferença mais fácil de verificar empiricamente em vez de apenas pela memória.

Teste os três em um único projeto Apidog

Observar o mesmo prompt produzir três respostas com formatos diferentes revela detalhes de implementação que nenhuma tabela de comparação pode. A configuração repetível:

1. Crie um projeto, três pastas: chat-completions, anthropic-messages, responses, cada uma contendo uma requisição salva por cenário (conclusão simples, chamada de ferramenta, streaming).
2. Compartilhe credenciais através de variáveis de ambiente. Defina {{DEEPSEEK_API_KEY}}, {{BASE_URL}} e {{ANTHROPIC_BASE}} uma vez; girar uma chave ou mudar para deepseek-v4-flash se torna uma alteração de um único campo.
3. Dispare o prompt idêntico através de cada formato e compare os corpos brutos: choices[0].message.content versus uma lista de blocos content versus itens de saída tipados.
4. Inspecione os streams com stream: true. A visualização SSE integrada torna as diferenças vívidas: chunks anônimos terminados por [DONE], eventos Messages nomeados, eventos de ciclo de vida Responses. Se a depuração SSE é nova para você, como fazer streaming de respostas da API com SSE cobre a mecânica.
5. Adicione asserções nos campos que sua integração realmente lê (caminho do conteúdo, localização do ID da chamada de ferramenta, motivo de finalização) e execute novamente a coleção sempre que a DeepSeek lançar uma atualização de snapshot.

O projeto de três pastas funciona como documentação viva: “como é o esquema da ferramenta Messages novamente?” se torna uma requisição salva com uma resposta real capturada.

Notas de migração

Mover o código existente para o V4 Pro é deliberadamente tedioso, e esse é o ponto.

Do OpenAI: altere três valores: base_url para https://api.deepseek.com, a chave da API e o modelo para deepseek-v4-pro. Sua construção de mensagens, definições de ferramentas e manipuladores de streaming permanecem. Duas verificações antes de implantar: confirme se quaisquer parâmetros além da especificação principal se comportam como você espera (execute-os através de sua coleção de testes em vez de assumir), e certifique-se de que sua análise de resposta tolera reasoning_content aparecendo ao lado de content.

Do Anthropic: troque a URL base para o caminho compatível com Anthropic, troque a chave e defina o modelo. Como o formato Messages é mantido, os max_tokens obrigatórios, os blocos de conteúdo e os eventos de stream tipados, um cliente compatível com a especificação não precisa de alterações na lógica. Para agentes que leem variáveis de ambiente, a migração são as três linhas export mostradas anteriormente.

Para a API Responses: esta é uma reescrita da sua camada de requisição, e não uma mudança de configuração, já que nenhum dos formatos mais antigos se traduz mecanicamente. Adote-a quando quiser o que ela oferece de forma única, estado no lado do servidor e itens de saída tipados, e não apenas por ser a mais nova.

Em todas as direções, o conselho é o mesmo: migre a configuração e, em seguida, execute novamente sua coleção de regressão antes de confiar nela. A esses preços, uma tarde de tráfego de verificação custa menos que o café que você toma durante ela.

FAQ

Qual formato um novo projeto deve escolher? Por padrão, ChatCompletions para o suporte mais amplo de ferramentas. Escolha Messages se sua stack for nativa de Claude. Escolha a API Responses se você estiver construindo um agente multi-etapas e quiser estado gerenciado pelo servidor.

Posso apontar o Claude Code para o DeepSeek V4 Pro? Sim. Defina ANTHROPIC_BASE_URL para o endpoint compatível com Anthropic da DeepSeek, use sua chave DeepSeek como token de autenticação e defina o modelo como deepseek-v4-pro. Esse é o benefício prático do suporte ao formato Messages.

A chamada de ferramenta (tool calling) e as saídas estruturadas funcionam em todos os formatos? O modelo suporta ambos, e cada dialeto expõe a chamada de ferramenta no formato de sua própria especificação: objetos de função aninhados, ferramentas input_schema ou itens estilo Responses. Verifique seus esquemas específicos contra cada interface em uma coleção de testes antes de implantar; casos de borda de formato de esquema são exatamente onde as implementações compatíveis divergem.