DeepSeek Chat Completions API: guia completo com exemplos em cURL, Python e Node.js

A DeepSeek Chat Completions API é o endpoint usado para enviar mensagens a modelos da DeepSeek e receber respostas em formato de conversa. Ela foi feita para backends, chatbots, copilots, agentes, automações e extração estruturada de dados — não para substituir diretamente a interface web/app do DeepSeek. Neste guia, você verá como usar POST /chat/completions, escolher entre deepseek-v4-flash e deepseek-v4-pro, trabalhar com streaming, JSON Output, Tool Calls, Thinking Mode, custos, tokens e erros comuns.

Verificado em 10 de maio de 2026: a DeepSeek documenta compatibilidade com formatos OpenAI/Anthropic, base URL OpenAI-compatible em https://api.deepseek.com, base URL Anthropic-compatible em https://api.deepseek.com/anthropic, e modelos atuais deepseek-v4-flash e deepseek-v4-pro. Os aliases deepseek-chat e deepseek-reasoner estão marcados para depreciação em 24 de julho de 2026.

---

Resposta rápida

Item	Valor prático
Endpoint	POST https://api.deepseek.com/chat/completions
Base URL OpenAI-compatible	https://api.deepseek.com
Base URL Anthropic-compatible	https://api.deepseek.com/anthropic
Modelos atuais	deepseek-v4-flash e deepseek-v4-pro
Campos obrigatórios	model e messages
Use deepseek-v4-flash quando	precisar de velocidade, custo menor, FAQ, classificação, chat simples e automações de alto volume
Use deepseek-v4-pro quando	precisar de raciocínio mais forte, código, agentes, análise longa ou tarefas complexas
Atenção	não comece projetos novos usando deepseek-chat ou deepseek-reasoner como IDs principais

---

O que é DeepSeek Chat Completions?

DeepSeek Chat Completions é a interface de chat da DeepSeek para aplicações. Em vez de enviar apenas um prompt isolado, você envia um array messages com o histórico relevante da conversa. Cada mensagem tem um role, como system, user, assistant ou tool, e um content.

Na prática, isso permite controlar o comportamento do modelo com uma mensagem de sistema, enviar a pergunta do usuário, manter contexto de conversas anteriores e incorporar resultados de ferramentas externas. A documentação oficial define POST /chat/completions como o endpoint que cria uma resposta do modelo para uma conversa, com messages e model como elementos centrais do request.

Em termos técnicos, uma chamada típica segue este fluxo:

1. Seu backend recebe uma pergunta do usuário.
2. Seu backend monta messages.
3. Envia model, messages e parâmetros opcionais para POST /chat/completions.
4. A API retorna choices, contendo a resposta do modelo.
5. A resposta inclui usage, útil para monitorar tokens e custo.

A diferença entre um prompt simples e uma conversa é importante. Em um prompt simples, você manda uma instrução única. Em Chat Completions, você manda um histórico estruturado, o que permite diálogos multi-turn, respostas com ferramentas, extração em JSON e maior controle de comportamento.

---

Endpoint, autenticação e modelos

Item	Valor	Observação prática
Endpoint	https://api.deepseek.com/chat/completions	Use com método POST
Base URL OpenAI-compatible	https://api.deepseek.com	Permite usar SDKs compatíveis com OpenAI
Base URL Anthropic-compatible	https://api.deepseek.com/anthropic	Útil para ecossistema Anthropic
Header Authorization	Authorization: Bearer ${DEEPSEEK_API_KEY}	Nunca exponha a chave no frontend
Campos obrigatórios	model, messages	Sem eles, o request não é válido
Modelos atuais	deepseek-v4-flash, deepseek-v4-pro	IDs recomendados para projetos novos
Aliases legados	deepseek-chat, deepseek-reasoner	Compatibilidade temporária; depreciação em 2026-07-24
Streaming	stream: true	Retorna chunks via SSE
JSON Output	response_format: {"type":"json_object"}	Também peça JSON no prompt
Tool Calls	tools, tool_choice	O modelo sugere chamadas; seu app executa

A página oficial de modelos e preços também informa que os modelos atuais suportam 1M de contexto, saída máxima de 384K, JSON Output, Tool Calls e Chat Prefix Completion. Como preços e descontos podem mudar, revise sempre a página oficial antes de tomar decisões de produção.

---

Exemplo mínimo com cURL

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "system",
        "content": "Você é um assistente técnico que responde de forma clara, objetiva e segura."
      },
      {
        "role": "user",
        "content": "Explique em 3 bullets o que é a DeepSeek Chat Completions API."
      }
    ],
    "thinking": { "type": "disabled" },
    "max_tokens": 400,
    "stream": false
  }'

O Authorization envia sua API key. O campo model escolhe o modelo. O array messages representa a conversa. A mensagem system define comportamento, a mensagem user traz a solicitação real. O parâmetro thinking desativado é útil para respostas simples e mais rápidas. max_tokens limita a saída, e stream: false faz a API retornar a resposta completa de uma vez.

---

Estrutura do request: model, messages e parâmetros

A estrutura básica da DeepSeek Chat Completions API é simples:

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "system", "content": "Instruções do sistema" },
    { "role": "user", "content": "Pergunta do usuário" }
  ]
}

Os campos mais importantes são:

Parâmetro	Para que serve
model	Define o modelo: deepseek-v4-flash ou deepseek-v4-pro
messages	Lista de mensagens da conversa
system	Instruções de comportamento, estilo, regras e limites
user	Entrada do usuário final
assistant	Respostas anteriores do modelo, usadas em contexto
tool	Resultado de uma ferramenta externa enviado de volta ao modelo
max_tokens	Limite de tokens gerados na resposta
temperature	Controla aleatoriedade em modo non-thinking
top_p	Alternativa ao ajuste de amostragem
stream	Ativa resposta parcial em chunks
response_format	Solicita saída em texto ou JSON
tools	Define funções externas que o modelo pode chamar
tool_choice	Controla se o modelo pode, deve ou não chamar ferramentas
usage	Mostra tokens usados
finish_reason	Indica por que a geração terminou

Os papéis aceitos em messages incluem system, user, assistant e tool. Para mensagens de ferramenta, o campo tool_call_id conecta o resultado da ferramenta à chamada sugerida pelo modelo.

Role	Quando usar	Exemplo	Erro comum
system	Definir regras globais	“Responda em pt-BR.”	Colocar dados do usuário como regra permanente
user	Enviar solicitação atual	“Resuma este contrato.”	Misturar instruções de sistema e pergunta
assistant	Reenviar respostas anteriores	Resposta do turno anterior	Reenviar histórico enorme sem necessidade
tool	Devolver resultado de função	Status de pedido, clima, estoque	Enviar sem tool_call_id

---

Exemplo em Python com OpenAI SDK

import os
from typing import Final

from openai import OpenAI, APIError, APITimeoutError, RateLimitError

DEEPSEEK_BASE_URL: Final[str] = "https://api.deepseek.com"

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url=DEEPSEEK_BASE_URL,
)

def get_deepseek_answer(prompt: str) -> str:
    if not prompt.strip():
        raise ValueError("O prompt não pode estar vazio.")

    model = os.environ.get("DEEPSEEK_MODEL", "deepseek-v4-flash")

    try:
        response = client.chat.completions.create(
            model=model,
            messages=[
                {
                    "role": "system",
                    "content": "Você é um assistente técnico. Responda em português do Brasil."
                },
                {
                    "role": "user",
                    "content": prompt
                }
            ],
            max_tokens=700,
            stream=False,
            extra_body={
                "thinking": {
                    "type": "disabled"
                }
            },
        )

        content = response.choices[0].message.content
        return content or ""

    except RateLimitError as exc:
        raise RuntimeError("Rate limit atingido. Tente novamente com backoff.") from exc
    except APITimeoutError as exc:
        raise RuntimeError("Timeout ao chamar a DeepSeek API.") from exc
    except APIError as exc:
        raise RuntimeError(f"Erro da API DeepSeek/OpenAI-compatible: {exc}") from exc

Esse exemplo usa variável de ambiente para proteger a API key, define base_url para DeepSeek, usa fallback para deepseek-v4-flash e trata erros comuns. No OpenAI SDK para Python, a documentação da DeepSeek mostra o uso de extra_body para passar thinking.

---

Exemplo em Node.js/TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com",
});

type ChatMessage = {
  role: "system" | "user" | "assistant" | "tool";
  content: string;
};

export async function getDeepSeekAnswer(prompt: string): Promise<string> {
  if (!process.env.DEEPSEEK_API_KEY) {
    throw new Error("DEEPSEEK_API_KEY não configurada.");
  }

  if (!prompt.trim()) {
    throw new Error("Prompt vazio.");
  }

  const model = process.env.DEEPSEEK_MODEL ?? "deepseek-v4-flash";

  const messages: ChatMessage[] = [
    {
      role: "system",
      content: "Você é um assistente técnico. Responda em português do Brasil.",
    },
    {
      role: "user",
      content: prompt,
    },
  ];

  const request = {
    model,
    messages,
    max_tokens: 700,
    stream: false,
    thinking: { type: "disabled" },
  } as any;

  const completion = await client.chat.completions.create(request);

  return completion.choices[0]?.message?.content ?? "";
}

Não chame a API oficial diretamente do navegador. Em aplicações web, envie a pergunta ao seu backend e deixe o backend chamar a DeepSeek API. Isso evita expor DEEPSEEK_API_KEY, facilita logs, retries, rate limiting e auditoria.

---

Streaming: quando usar stream=true

Use stream: true quando a experiência do usuário melhora ao ver a resposta aparecendo aos poucos: chat UI, copilots, respostas longas, agentes e assistentes de programação. Quando o streaming está ativo, a API envia deltas como server-sent events e termina com data: [DONE]. Também é possível usar stream_options.include_usage para receber estatísticas de tokens antes do encerramento do stream.

Streaming em Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Responda em português do Brasil."},
        {"role": "user", "content": "Crie um checklist para integrar DeepSeek em um SaaS."}
    ],
    stream=True,
    stream_options={"include_usage": True},
    extra_body={"thinking": {"type": "disabled"}},
)

for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)

    if getattr(chunk, "usage", None):
        print("\n\nUso de tokens:", chunk.usage)

Streaming em Node.js/TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com",
});

const stream = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "system", content: "Responda em português do Brasil." },
    { role: "user", content: "Explique streaming em APIs de chat." },
  ],
  stream: true,
  stream_options: { include_usage: true },
  thinking: { type: "disabled" },
} as any);

for await (const chunk of stream) {
  const delta = chunk.choices?.[0]?.delta?.content;
  if (delta) process.stdout.write(delta);

  if ((chunk as any).usage) {
    console.log("\nUso de tokens:", (chunk as any).usage);
  }
}

---

Conversas multi-turn: a API é stateless

A DeepSeek /chat/completions API é stateless. Isso significa que o servidor não guarda automaticamente o histórico da conversa. Seu aplicativo precisa reenviar as mensagens relevantes a cada request. A documentação oficial recomenda concatenar o histórico necessário e passá-lo novamente à API.

messages = [
    {"role": "system", "content": "Responda em português do Brasil."},
    {"role": "user", "content": "Qual é a função do endpoint /chat/completions?"}
]

response_1 = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    extra_body={"thinking": {"type": "disabled"}}
)

assistant_message = response_1.choices[0].message
messages.append(assistant_message)

messages.append({
    "role": "user",
    "content": "Agora explique como usar isso em um chatbot SaaS."
})

response_2 = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    extra_body={"thinking": {"type": "disabled"}}
)

Históricos longos aumentam custo, latência e risco de ultrapassar limites. Em produção, use pruning, resumo de conversa, recuperação semântica ou janelas de contexto com apenas as mensagens realmente úteis.

---

Thinking Mode: enabled ou disabled?

O Thinking Mode controla se o modelo usa raciocínio antes da resposta final. Em formato OpenAI, a DeepSeek documenta thinking: {"type":"enabled"} ou thinking: {"type":"disabled"}; o modo thinking é padrão, e reasoning_effort aceita high ou max. A documentação também informa que, em Thinking Mode, parâmetros como temperature e top_p não têm efeito, embora possam não gerar erro por compatibilidade.

Use disabled para:

• FAQ.
• Classificação.
• Respostas curtas.
• Chat simples.
• Rotas sensíveis a custo e latência.

Use enabled para:

• Raciocínio complexo.
• Código.
• Agents.
• Análise de documentos longos.
• Planejamento multi-etapas.

Caso de uso	Thinking recomendado	Modelo sugerido
FAQ de produto	disabled	deepseek-v4-flash
Classificação de tickets	disabled	deepseek-v4-flash
Geração de SQL simples	disabled ou enabled	deepseek-v4-flash
Debug de código complexo	enabled, high	deepseek-v4-pro
Agent com múltiplas ferramentas	enabled, high ou max	deepseek-v4-pro
Análise de contrato extenso	enabled, high	deepseek-v4-pro

---

JSON Output com DeepSeek Chat Completions

Use JSON Output quando sua aplicação precisa fazer parse da resposta: extração de dados, classificação, enrichment, scoring, criação de objetos estruturados ou integração com bancos de dados.

A DeepSeek orienta três cuidados principais: definir response_format como {"type":"json_object"}, incluir a palavra “json” no prompt e fornecer exemplo do formato desejado, além de configurar max_tokens de forma suficiente para evitar truncamento. A documentação também alerta que JSON Output pode ocasionalmente retornar conteúdo vazio e que prompts melhores podem mitigar o problema.

import json
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

system_prompt = """
Você extrai dados de tickets de suporte.

Responda sempre em json válido neste formato:
{
  "categoria": "billing | technical | account | other",
  "prioridade": "low | medium | high",
  "resumo": "string curta",
  "precisa_humano": true
}
"""

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "Não consigo acessar minha conta e já tentei redefinir a senha."}
    ],
    response_format={"type": "json_object"},
    max_tokens=400,
    extra_body={"thinking": {"type": "disabled"}},
)

raw = response.choices[0].message.content or "{}"
data = json.loads(raw)

required_fields = {"categoria", "prioridade", "resumo", "precisa_humano"}
missing = required_fields - set(data.keys())

if missing:
    raise ValueError(f"Campos ausentes no JSON: {missing}")

print(data)

Erros comuns em JSON Output:

Erro	Como evitar
Esquecer a palavra “json” no prompt	Diga explicitamente “responda em json válido”
max_tokens muito baixo	Reserve tokens suficientes para o objeto completo
Não validar a resposta	Use json.loads e validação de campos
Tratar JSON Output como schema validation completa	Valide no seu backend
Ignorar finish_reason: length	Refaça a chamada ou aumente o limite

---

Tool Calls / Function Calling

Tool Calls permite que o modelo solicite uma função externa, mas ele não executa a função sozinho. Seu aplicativo recebe a chamada sugerida, valida os argumentos, executa a função real e envia o resultado de volta como mensagem tool. A documentação oficial deixa claro que a funcionalidade da função precisa ser fornecida pelo usuário/aplicação, não pelo modelo.

Fluxo típico:

1. Usuário pergunta algo.
2. Modelo retorna tool_call.
3. Aplicação valida argumentos.
4. Aplicação executa a função.
5. Aplicação envia resultado como role: "tool".
6. Modelo responde ao usuário em linguagem natural.

Exemplo simplificado:

import json
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Obtém o status de um pedido pelo ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "ID do pedido, por exemplo BR12345."
                    }
                },
                "required": ["order_id"]
            }
        }
    }
]

def get_order_status(order_id: str) -> str:
    allowed = {"BR12345": "enviado", "BR99999": "em processamento"}
    return allowed.get(order_id, "pedido não encontrado")

messages = [
    {"role": "system", "content": "Responda em português do Brasil."},
    {"role": "user", "content": "Qual é o status do pedido BR12345?"}
]

first = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking": {"type": "disabled"}},
)

assistant_msg = first.choices[0].message
messages.append(assistant_msg)

if assistant_msg.tool_calls:
    tool_call = assistant_msg.tool_calls[0]
    args = json.loads(tool_call.function.arguments)

    order_id = args.get("order_id")
    if not isinstance(order_id, str) or not order_id.startswith("BR"):
        raise ValueError("order_id inválido.")

    result = get_order_status(order_id)

    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": result
    })

    final = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=messages,
        extra_body={"thinking": {"type": "disabled"}},
    )

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

A API também oferece strict mode em beta para Tool Calls, com base_url="https://api.deepseek.com/beta" e strict: true nas funções. Mesmo assim, valide argumentos no backend antes de executar qualquer ação externa.

---

Como escolher entre deepseek-v4-flash e deepseek-v4-pro

Escolha deepseek-v4-flash quando o objetivo for velocidade, eficiência e custo. Ele é uma boa opção para chat simples, FAQ, classificação, extração curta, atendimento inicial, automações repetitivas e alto volume de requisições.

Escolha deepseek-v4-pro quando a tarefa exigir mais raciocínio: análise de código, agentic workflows, interpretação de documentos extensos, planejamento, debugging, geração complexa ou decisões multi-etapas.

A própria DeepSeek descreve deepseek-v4-flash como opção rápida, eficiente e econômica, enquanto deepseek-v4-pro é posicionado para capacidades mais fortes, incluindo agentes e raciocínio. Ambos mantêm o mesmo base_url, bastando alterar o campo model.

Necessidade	Modelo recomendado
Baixa latência	deepseek-v4-flash
Custo menor por alto volume	deepseek-v4-flash
Chatbot de suporte nível 1	deepseek-v4-flash
Copilot de programação	deepseek-v4-pro
Agent com ferramentas	deepseek-v4-pro
Análise longa e complexa	deepseek-v4-pro

---

Custos, tokens e context caching

A DeepSeek cobra com base em tokens de entrada e saída. A fórmula geral é:

custo = número de tokens × preço por token

Como a página oficial apresenta preços por 1M tokens e informa que preços podem variar, use sempre a tabela oficial atualizada antes de estimar custo de produção. Verificado em 10 de maio de 2026, a documentação também mostra campos como prompt_tokens, completion_tokens, total_tokens, prompt_cache_hit_tokens, prompt_cache_miss_tokens e reasoning_tokens em usage.

O context caching é habilitado por padrão para usuários da DeepSeek API. Quando requests posteriores reutilizam prefixos já persistidos, parte do prompt pode contar como cache hit. A resposta inclui prompt_cache_hit_tokens e prompt_cache_miss_tokens para monitorar isso. O cache funciona em regime best-effort e não garante 100% de hits.

Checklist para reduzir custo:

• Use deepseek-v4-flash para tarefas simples.
• Limite max_tokens.
• Remova histórico irrelevante.
• Resuma conversas longas.
• Reutilize prefixos estáveis quando fizer sentido.
• Monitore usage.total_tokens.
• Acompanhe prompt_cache_hit_tokens.
• Desative Thinking Mode quando não precisar de raciocínio.
• Faça batch lógico apenas quando não prejudicar latência.
• Tenha alertas de consumo por cliente, rota ou workspace.

---

Erros comuns e como corrigir

Erro	Causa provável	Como corrigir
400 Invalid Format	Body malformado	Corrija JSON, roles e estrutura de messages
401 Authentication Fails	API key errada ou ausente	Verifique DEEPSEEK_API_KEY
402 Insufficient Balance	Saldo insuficiente	Recarregue a conta ou reduza consumo
422 Invalid Parameters	Parâmetro inválido	Revise model, messages, tools, response_format
429 Rate Limit Reached	Muitas requisições	Use fila, backoff e controle de concorrência
500 Server Error	Falha do servidor	Tente novamente com backoff
503 Server Overloaded	Alta carga	Retry com espera e fallback
finish_reason: length	Saída truncada	Aumente max_tokens ou reduza prompt
JSON vazio	Prompt fraco ou caso do JSON Output	Reforce instrução JSON e exemplo
Tool arguments inválidos	Modelo gerou argumentos ruins	Faça parse e validação antes de executar
Expor API key no browser	Chamada direta do frontend	Use backend/proxy seguro
Usar aliases antigos	Projeto novo com deepseek-chat	Migre para deepseek-v4-flash ou deepseek-v4-pro

A lista oficial de erros da DeepSeek inclui 400, 401, 402, 422, 429, 500 e 503, com causas e soluções recomendadas.

---

Boas práticas de produção

Para usar DeepSeek Chat Completions em produção, trate a API como parte crítica da sua infraestrutura:

• Guarde API keys em variáveis de ambiente ou secret manager.
• Nunca chame a API oficial diretamente do frontend.
• Use retry com exponential backoff e jitter.
• Configure timeouts por rota.
• Registre logs úteis sem gravar dados sensíveis.
• Valide argumentos de Tool Calls.
• Limite max_tokens.
• Monitore usage.
• Acompanhe custo por usuário, tenant ou feature.
• Use idempotência em ações externas, como pagamentos ou alterações de conta.
• Atualize periodicamente IDs de modelos e documentação.
• Tenha fallback para respostas críticas.
• Separe prompts de produção por versão.
• Teste JSON Output com dados reais e casos extremos.

Uma boa arquitetura mantém a DeepSeek API atrás de um backend próprio. O backend aplica autenticação, autorização, limites de uso, observabilidade e validação antes de encaminhar a resposta ao usuário final.

---

DeepSeek Chat Completions vs Completions API vs Anthropic API

Interface	Melhor para	Endpoint/base	Observação
Chat Completions	Chatbots, copilots, agentes, conversas multi-turn	POST /chat/completions	Principal escolha para apps conversacionais
Completions/FIM	Fill-in-the-middle e casos beta específicos	/completions beta	Útil para certos fluxos de código
Anthropic API	Ferramentas compatíveis com ecossistema Anthropic	https://api.deepseek.com/anthropic	Permite integrar DeepSeek com SDKs/formatos Anthropic

A DeepSeek informa suporte ao formato Anthropic com base_url específico, permitindo integrar capacidades da DeepSeek ao ecossistema Anthropic por configuração.

---

FAQ sobre DeepSeek Chat Completions

---

Conclusão

A forma básica de usar DeepSeek Chat Completions é simples: escolha um model, monte messages e envie para POST /chat/completions. Para começar, teste o exemplo em cURL. Depois, implemente Python ou Node.js com variável de ambiente, tratamento de erros e monitoramento de usage.

Em produção, o diferencial não é apenas chamar a API. O diferencial é controlar custo, latência, segurança, histórico, validação, Tool Calls, JSON Output e fallback. Para projetos novos, prefira deepseek-v4-flash em fluxos rápidos e econômicos, e deepseek-v4-pro em tarefas que exigem raciocínio mais forte.