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

DeepSeek V4 Pro: como testar ChatCompletions, Messages e Responses API

DeepSeek-V4-Pro-0813 atingiu disponibilidade geral em 12 de agosto de 2026 e é servido pelo ID de modelo perene deepseek-v4-pro em https://api.deepseek.com. A plataforma também oferece o modelo mais econômico deepseek-v4-flash (Unite.AI cobriu o anúncio de GA). As especificações incluem janela de contexto de 1M de tokens, saída máxima de 384K tokens, chamada de ferramenta, saídas estruturadas e três modos de pensamento que expõem o raciocínio em reasoning_content.

Experimente o Apidog hoje

A particularidade não está apenas nas especificações: o mesmo modelo aceita três dialetos de API:

• OpenAI ChatCompletions
• Anthropic Messages
• DeepSeek Responses API

Na prática, você pode apontar um cliente OpenAI existente, um agente construído para Claude ou um loop de agente no estilo Codex para os mesmos pesos do modelo. O endpoint e o payload mudam; o modelo continua sendo o mesmo.

Este guia mostra uma requisição funcional para cada formato, explica as diferenças que afetam a implementação e apresenta uma forma de testar os três em um único projeto Apidog, usando variáveis de ambiente compartilhadas. Para configurar a conta e fazer a primeira chamada, consulte como usar a API DeepSeek V4.

TL;DR

• deepseek-v4-pro está em GA em https://api.deepseek.com; deepseek-v4-flash compartilha as mesmas interfaces por um preço menor.
• O V4 Pro aceita os formatos OpenAI ChatCompletions, Anthropic Messages e DeepSeek Responses API.
• Especificações: 1M de contexto, até 384K de saída, tool calling, saídas estruturadas e reasoning_content.
• Preço: $0.435/M tokens de entrada em cache miss, $0.003625/M em cache hit e $0.87/M tokens de saída.
• Os formatos diferem no prompt de sistema, em max_tokens, nos esquemas de ferramentas e nos eventos de streaming.
• Use um projeto Apidog com {{DEEPSEEK_API_KEY}} e URLs-base por formato para enviar o mesmo prompt e comparar respostas.

Por que um modelo fala três dialetos?

Cada formato oferece compatibilidade com uma base de ferramentas já existente:

• ChatCompletions é a opção de menor atrito para SDKs, frameworks e integrações compatíveis com OpenAI.
• Anthropic Messages permite reutilizar agentes, harnesses de avaliação e ferramentas construídas para Claude, incluindo Claude Code.
• Responses API atende fluxos de agentes com múltiplas etapas, saída tipada e estado de conversação no servidor.

O V4 Pro também aparece em agregadores, como na página do OpenRouter para deepseek-v4-pro-0813. Este artigo, porém, foca na API proprietária da DeepSeek. Para uma visão geral da família, veja como usar o DeepSeek V4.

Formato 1: OpenAI ChatCompletions

Use este formato se sua aplicação já envia um array messages para APIs compatíveis com OpenAI.

Implementação com SDK Python

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)

O que manter na migração

A estrutura é a conhecida:

• O prompt de sistema entra como a primeira mensagem com role: "system".
• Ferramentas usam o objeto aninhado function.
• Streaming retorna deltas chat.completion.chunk.
• O stream termina com data: [DONE].

Ao usar um modo de pensamento, trate reasoning_content como um campo adicional ao lado de content. Não assuma que a resposta terá apenas o texto final.

Quando usar

Escolha ChatCompletions quando você já usa:

• SDK openai;
• LangChain ou frameworks semelhantes;
• wrappers internos compatíveis com OpenAI;
• coleções e testes construídos para Chat Completions.

A anatomia da requisição é a mesma mostrada em como testar a API ChatGPT com Apidog, trocando apenas host, chave e modelo.

Formato 2: Anthropic Messages

O formato Messages parece semelhante ao ChatCompletions, mas possui diferenças que impedem uma tradução mecânica do payload.

Diferenças importantes

1. O prompt de sistema fica no campo de topo system, fora do array messages.
2. max_tokens é obrigatório.
3. As ferramentas usam name, description e input_schema diretamente, sem o wrapper function.
4. Chamadas de ferramenta retornam como blocos tool_use.
5. Os resultados devem voltar como blocos tool_result em uma mensagem de usuário.

Implementação com SDK Python

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/anthropic",  # Confirme o caminho atual na documentação da DeepSeek
)

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)

Configuração por variáveis de ambiente

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

Como tratar a resposta e o streaming

Ao contrário de ChatCompletions, o conteúdo é retornado como uma lista de blocos:

for block in message.content:
    print(block)

No streaming, espere eventos SSE tipados, como:

message_start
content_block_delta
message_stop

A autenticação segue as convenções de cabeçalho da especificação Anthropic, não o padrão bearer token de ChatCompletions. Consulte a documentação da API DeepSeek para os detalhes atuais da interface compatível.

Quando usar

Escolha Messages quando sua stack já é nativa de Claude:

• agentes compatíveis com Anthropic;
• Claude Code;
• harnesses de avaliação para Claude;
• clientes que já manipulam blocos de conteúdo e eventos SSE tipados.

O formato corresponde à anatomia explicada no guia da API Claude Opus 5, permitindo testar DeepSeek e Claude com corpos de requisição equivalentes.

Formato 3: DeepSeek Responses API

A Responses API é a interface voltada a agentes. Em vez de enviar um único array messages, você combina:

• instructions para instruções de alto nível;
• input como string ou lista de itens tipados;
• opcionalmente, referências a respostas anteriores para manter estado no servidor.

Requisição básica com cURL

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
  }'

O que muda em relação aos outros formatos

1. Estado no lado do servidor

Em vez de reenviar todo o histórico, uma requisição posterior pode apontar para uma resposta anterior usando previous_response_id, conforme a especificação Responses.

Isso reduz a complexidade de loops de agentes com várias etapas.

2. Saída tipada

A resposta não é uma única mensagem. Ela pode conter itens distintos para:

• raciocínio;
• texto;
• chamadas de ferramenta;
• resultados de ferramentas.

Seu orquestrador pode processar cada item conforme seu tipo, em vez de inferir tudo a partir de uma string.

3. Streaming semântico

Em vez de deltas genéricos, espere eventos de ciclo de vida como:

response.output_text.delta
response.completed

Isso é útil quando o agente precisa reagir a eventos específicos sem interpretar manualmente chunks SSE.

Tool calling na Responses API

As ferramentas e seus resultados usam itens compatíveis com a especificação Responses, incluindo:

• function_call
• function_call_output

Antes de implantar, valide o formato exato suportado pela DeepSeek em api-docs.deepseek.com.

Quando usar

Escolha a Responses API para:

• agentes no estilo Codex;
• fluxos de trabalho longos e multi-etapas;
• orquestradores que se beneficiam de itens de saída tipados;
• aplicações que querem delegar o estado da conversa ao servidor.

Para uma conclusão simples de chat, ChatCompletions normalmente exige menos código.

Os três formatos lado a lado

	OpenAI ChatCompletions	Anthropic Messages	DeepSeek Responses API
Endpoint	POST /chat/completions em api.deepseek.com	POST /v1/messages na base compatível com Anthropic (/anthropic)	POST /responses em api.deepseek.com
Formato da requisição	Array messages; sistema como primeira mensagem	system no topo + mensagens alternadas	instructions no topo + input como string ou lista
Limite de saída	Opcional	max_tokens obrigatório	Opcional conforme a especificação Responses
Definições de ferramenta	Objeto function aninhado com parameters	input_schema plano por ferramenta	Entradas planas no formato Responses
Resultado de ferramenta	Mensagem com role: "tool"	Bloco tool_result	Item function_call_output
Streaming	Deltas chat.completion.chunk, finalizados por [DONE]	Eventos message_start, content_block_delta e message_stop	Eventos semânticos, como response.output_text.delta
Estado da conversa	Cliente reenvia o histórico	Cliente reenvia o histórico	Referência opcional a resposta anterior
Melhor para	Ferramentas OpenAI existentes	Ferramentas e agentes nativos de Claude	Agentes com estado e fluxos estilo Codex

Mesmo modelo, mesmo preço, três contratos de comunicação. Por isso, valide o comportamento com requisições reais em vez de depender apenas da compatibilidade declarada.

Teste os três em um único projeto Apidog

Use uma coleção única no Apidog para comparar os formatos de forma repetível.

1. Crie três pastas

Organize as requisições por formato:

deepseek-v4/
├── chat-completions/
│   ├── simple-completion
│   ├── tool-calling
│   └── streaming
├── anthropic-messages/
│   ├── simple-completion
│   ├── tool-calling
│   └── streaming
└── responses/
    ├── simple-completion
    ├── tool-calling
    └── streaming

2. Defina variáveis compartilhadas

Crie variáveis de ambiente:

DEEPSEEK_API_KEY
BASE_URL=https://api.deepseek.com
ANTHROPIC_BASE=https://api.deepseek.com/anthropic
MODEL=deepseek-v4-pro

Assim, alternar entre deepseek-v4-pro e deepseek-v4-flash exige mudar apenas uma variável.

3. Envie o mesmo prompt

Use o mesmo prompt em cada formato e compare a resposta bruta:

• ChatCompletions: choices[0].message.content
• Messages: lista content
• Responses: itens de saída tipados

Essa comparação mostra onde sua camada de parsing precisa mudar.

4. Compare os streams

Ative stream: true em cada requisição e observe os eventos SSE:

• ChatCompletions: chunks que terminam em [DONE];
• Messages: eventos nomeados por bloco;
• Responses: eventos de ciclo de vida.

Se você ainda não depurou SSE, consulte como fazer streaming de respostas da API com SSE.

5. Adicione asserções de regressão

Valide os campos que sua integração realmente consome:

• caminho do texto final;
• ID da chamada de ferramenta;
• motivo de finalização;
• presença de reasoning_content;
• formato dos eventos de streaming.

Execute a coleção novamente sempre que a DeepSeek publicar uma atualização de snapshot.

Essa estrutura de três pastas também se torna documentação viva: quando surgir uma dúvida sobre input_schema, tool_result ou eventos de stream, consulte uma requisição salva com uma resposta real.

Notas de migração

De OpenAI para DeepSeek V4 Pro

Altere apenas:

1. base_url para https://api.deepseek.com;
2. a chave da API;
3. o modelo para deepseek-v4-pro.

Mantenha mensagens, definições de ferramenta e handlers de streaming. Antes de implantar:

• execute os parâmetros não essenciais na sua coleção de testes;
• faça seu parser aceitar reasoning_content ao lado de content.

De Anthropic para DeepSeek V4 Pro

Altere:

1. a URL-base para o endpoint compatível com Anthropic;
2. a chave de autenticação;
3. o modelo.

Como o formato Messages é preservado, clientes que seguem a especificação devem manter:

• max_tokens obrigatório;
• blocos de conteúdo;
• ferramentas com input_schema;
• eventos SSE tipados.

Para ferramentas configuradas por ambiente, a migração pode ser apenas as três linhas export mostradas anteriormente.

Para a Responses API

A migração para Responses não é uma troca de configuração. Você precisa adaptar a camada de requisição e parsing, pois ela não se traduz mecanicamente de ChatCompletions ou Messages.

Adote-a quando precisar especificamente de:

• estado de conversação gerenciado pelo servidor;
• itens de saída tipados;
• eventos de streaming orientados ao ciclo de vida;
• orquestração de agentes multi-etapas.

Em qualquer direção, migre a configuração e execute a coleção de regressão antes de confiar no tráfego de produção.

FAQ

Qual formato um projeto novo deve escolher?

Use ChatCompletions por padrão, devido ao suporte amplo de ferramentas. Escolha Messages se sua stack já for nativa de Claude. Escolha a Responses API para agentes multi-etapas que se beneficiem de estado no 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 a chave DeepSeek como token de autenticação e configure:

export ANTHROPIC_MODEL=deepseek-v4-pro

Esse é o benefício prático da compatibilidade com o formato Messages.

Tool calling e saídas estruturadas funcionam nos três formatos?

O modelo suporta ambos. Cada formato expõe ferramentas segundo sua própria especificação:

• funções aninhadas em ChatCompletions;
• ferramentas com input_schema em Messages;
• itens de função no estilo Responses.

Teste seus esquemas em cada interface antes de implantar. Diferenças nos formatos de schema são um dos pontos mais comuns de divergência entre APIs compatíveis.