DeepSeek API

Se você quer aprender como usar a API do DeepSeek hoje, o caminho mais curto é este: criar uma chave, apontar seu cliente para a base oficial, chamar o endpoint principal de chat e manter a credencial no backend. Este guia foi revisado em 12 de abril de 2026 e resume, em português do Brasil, o estado atual da documentação oficial para quem precisa integrar modelos em produto, automação ou fluxo interno. Para uma visão mais ampla do ecossistema, veja também nosso guia principal do DeepSeek em português.

A documentação oficial da DeepSeek API descreve uma API compatível com o formato OpenAI. Na prática, isso reduz a fricção para quem já trabalha com SDKs, gateways ou stacks que seguem esse padrão. Ao longo deste artigo, você vai ver como obter a chave, escolher entre deepseek-chat e deepseek-reasoner, fazer a primeira chamada com cURL, Python e Node.js, entender preços, reduzir custos com cache e corrigir os erros mais comuns.

Resumo rápido

• A base principal da API é a base oficial mostrada nos exemplos abaixo.
• Na API pública atual, os IDs principais são deepseek-chat e deepseek-reasoner.
• Os dois correspondem hoje ao DeepSeek-V3.2 na API, com 128K de contexto.
• O endpoint central para começar é /chat/completions.
• A cobrança é por uso, com preços por token de entrada e saída.
• O cache de contexto ajuda a reduzir custo quando você reaproveita prefixos estáveis.
• A chave da API deve ficar no servidor, nunca em JavaScript público no navegador.

Como obter a chave da API do DeepSeek

O primeiro passo é acessar o painel oficial de API keys, gerar uma nova chave e armazená-la em variável de ambiente. Em ambiente local, algo como DEEPSEEK_API_KEY já resolve. Em produção, a recomendação é usar o gerenciador de segredos do seu provedor de cloud, com rotação periódica e controle de acesso por equipe.

Evite dois erros comuns logo no início. O primeiro é copiar a chave para o front-end e expô-la em código público. O segundo é registrar a credencial em logs, prints de depuração ou screenshots compartilhadas. O uso correto da API do DeepSeek começa com uma regra simples: o navegador fala com o seu backend, e o seu backend fala com a DeepSeek.

Modelos disponíveis: deepseek-chat vs deepseek-reasoner

Hoje, a API pública trabalha principalmente com dois IDs: deepseek-chat e deepseek-reasoner. Os dois correspondem ao DeepSeek-V3.2 na API, com contexto de 128K. A diferença prática é o modo de resposta: o primeiro opera em modo não pensante, enquanto o segundo é o modo de raciocínio. Se você quiser uma visão editorial resumida dessa geração, consulte também nossa página sobre o DeepSeek V3.2.

Essa distinção importa porque a experiência do app e da web não deve ser confundida com a experiência da API. Para tarefas de atendimento, transformação de texto, classificação, resumo e automação previsível, deepseek-chat costuma ser a escolha inicial. Para perguntas mais ambíguas, síntese de múltiplas evidências, fluxos com análise mais longa ou cenários em que o raciocínio ajuda a qualidade final, deepseek-reasoner tende a fazer mais sentido.

Modelo	Modo	Contexto	Saída padrão	Saída máxima	Quando usar
deepseek-chat	Não pensante	128K	4K	8K	Chat, automação, texto, classificação, respostas curtas e médias
deepseek-reasoner	Pensante	128K	32K	64K	Raciocínio mais longo, reconciliação de fontes, análise mais complexa

Base URL, autenticação e endpoint principal

A base principal da API é a base oficial indicada na documentação. Por compatibilidade com o ecossistema OpenAI, também é possível usar a rota com /v1, mas esse trecho não representa a versão do modelo. Para autenticação, a API usa Bearer token. Em outras palavras: sua chamada precisa levar a chave no cabeçalho Authorization.

Base URL principal: https://api.deepseek.com
Compatibilidade OpenAI: https://api.deepseek.com/v1

O endpoint principal para começar é a referência oficial de Create Chat Completion, isto é, /chat/completions. É nele que você envia o campo messages, que representa a conversa até aquele ponto. Em geral, system define regras e contexto, user traz a solicitação e assistant pode ser reenviado em conversas multi-turn quando você precisa manter continuidade.

Outro endpoint útil é o endpoint oficial /models, que lista os modelos disponíveis e ajuda a validar IDs antes de colocar seu código em produção. Isso é especialmente útil quando você está preparando CI, testes automatizados ou rollout gradual entre ambientes.

Primeira chamada: exemplos prontos para copiar e colar

cURL

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "Você é um assistente útil e objetivo."},
      {"role": "user", "content": "Explique em uma frase o que é a API do DeepSeek."}
    ],
    "stream": false
  }'

Python com OpenAI SDK atual

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "Você é um assistente útil e objetivo."},
        {"role": "user", "content": "Explique em uma frase o que é a API do DeepSeek."}
    ],
    stream=False
)

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

Node.js com OpenAI SDK atual

import OpenAI from "openai";

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

async function main() {
  const completion = await client.chat.completions.create({
    model: "deepseek-chat",
    messages: [
      { role: "system", content: "Você é um assistente útil e objetivo." },
      { role: "user", content: "Explique em uma frase o que é a API do DeepSeek." }
    ],
    stream: false
  });

  console.log(completion.choices[0].message.content);
}

main();

Repare em três pontos importantes. Primeiro: o exemplo atual usa from openai import OpenAI e client.chat.completions.create(…). Segundo: a chave vem de variável de ambiente. Terceiro: o array messages é o coração da chamada. Em produção, ele precisa ser construído com disciplina para não desperdiçar tokens, não vazar contexto sensível e não gerar instruções conflitantes.

Streaming, JSON Output, Tool Calls e Thinking Mode

Quando stream está como false, a resposta chega completa ao final da inferência. Quando está como true, a API envia deltas em SSE. Isso é útil para interfaces de chat, barras de progresso e experiências em tempo real. Se você estiver processando HTTP manualmente, trate corretamente linhas vazias e comentários de keep-alive.

Para saída estruturada, a DeepSeek oferece JSON Output. Na prática, você define response_format={“type”:”json_object”} e também instrui o modelo, no prompt, a responder em JSON. Vale a pena incluir um exemplo do formato desejado e ajustar max_tokens com bom senso, para não truncar a resposta no meio do objeto.

Tool Calls é o recurso que permite ao modelo pedir o uso de ferramentas externas, como busca, clima, banco de dados ou funções internas do seu produto. O ponto essencial aqui é não superestimar o recurso: o modelo sugere a chamada, mas a execução real da função continua sendo responsabilidade da sua aplicação.

Se você precisa de raciocínio explícito, consulte o guia oficial de Thinking Mode. A forma mais direta é usar deepseek-reasoner. Se estiver trabalhando com OpenAI SDK e quiser controlar isso por parâmetro, envie o objeto thinking em extra_body. Quando houver conteúdo de raciocínio disponível, o campo relevante é reasoning_content, enquanto a resposta final continua em content.

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "user", "content": "Compare duas estratégias de cache para uma API."}
    ],
    extra_body={"thinking": {"type": "enabled"}}
)

Preços da API do DeepSeek em 2026

A cobrança da API é por uso. Na página oficial de Models & Pricing, os valores atuais por 1 milhão de tokens são: US$ 0,028 para input com cache hit, US$ 0,28 para input com cache miss e US$ 0,42 para output. Esses preços se aplicam aos dois IDs públicos centrais da API atual. Para acompanhar mudanças futuras e uma leitura em português do seu site, você também pode consultar nossa página de Preços do DeepSeek.

O ponto prático aqui não é só “quanto custa por milhão”. O que realmente move a conta é a forma como você monta prompt, reaproveita contexto, escolhe entre chat e reasoner e define o tamanho da saída. Em outras palavras: arquitetura ruim custa mais do que escolha ruim de modelo.

Context Caching e como reduzir custos

O Context Caching está habilitado por padrão. Isso significa que, quando chamadas consecutivas compartilham o mesmo prefixo, parte do processamento pode ser reaproveitada como cache hit. Na prática, esse é um dos recursos mais importantes para reduzir custo real em sistemas com instruções estáveis, documentos repetidos, políticas fixas ou conversas longas com base comum.

Quatro hábitos ajudam bastante. Mantenha o prompt de sistema estável. Reenvie blocos grandes na mesma ordem sempre que precisar reaproveitá-los. Evite inserir valores aleatórios no início do prompt. E separe o que é prefixo reutilizável do que é pergunta variável do usuário. Quanto mais consistente for esse prefixo, maior a chance de capturar economia de input.

Erros comuns e como corrigir

400

O erro 400 normalmente aponta formato inválido do corpo da requisição. Revise JSON, nomes de campos, tipos, vírgulas e aspas. Em integrações novas, esse é o erro mais comum quando alguém copia um exemplo antigo e mistura sintaxes diferentes.

401

O erro 401 indica falha de autenticação. Em geral, a causa é chave incorreta, variável de ambiente vazia ou cabeçalho Authorization montado de forma errada. Antes de investigar qualquer outra coisa, confirme se o backend realmente recebeu a chave certa.

402

O erro 402 significa saldo insuficiente. Como a API segue lógica de cobrança por uso e recarga, a correção costuma passar por verificar o balanceamento da conta e fazer top-up quando necessário.

429

O erro 429 aparece quando você envia requisições rápido demais ou quando o serviço está sob pressão de tráfego. Em vez de assumir um número fixo de rate limit, trate isso de forma operacional: backoff exponencial, fila, retries controlados e observabilidade. A própria documentação oficial alerta que o comportamento pode variar com a pressão do tráfego.

500 e 503

Os erros 500 e 503 são do lado do serviço. O ideal é implementar retry com limite, registrar incidentes, desacoplar tarefas assíncronas e evitar que um pico transitório derrube seu fluxo inteiro. Se a inferência ainda não começou, a conexão também pode ser encerrada depois de cerca de 10 minutos; por isso, timeouts e tratamento de keep-alive fazem parte de uma integração madura.

Boas práticas de segurança e produção

Não exponha a chave no navegador. Não confie em chamadas diretas do front-end para a API. Use variáveis de ambiente, backend intermediário, rotação de segredo e permissões mínimas. Em logs, registre metadados úteis, mas evite salvar prompts e respostas integrais quando houver risco de dados sensíveis.

Também vale decidir, no nível do produto, quando usar deepseek-chat e quando escalar para deepseek-reasoner. Uma estratégia simples é rotear tarefas previsíveis para chat e reservar reasoner para casos de ambiguidade, reconciliação entre documentos, análise de políticas e respostas em que o custo adicional do raciocínio compense em qualidade.

Por fim, trate a documentação como fonte viva. Modelos, preços e comportamento operacional podem mudar. Sempre que algo impactar custo, latência ou formato de resposta, revise a documentação oficial antes de replicar um snippet em produção.

Perguntas frequentes

Conclusão

Para publicar uma integração hoje, a forma mais segura de como usar a API do DeepSeek é combinar três decisões simples: usar a base oficial correta, escolher o modelo de acordo com a complexidade da tarefa e proteger a chave no backend. Com isso, você já consegue testar, medir custo, ativar JSON quando precisar de estrutura, usar reasoning quando fizer sentido e evoluir para produção com muito menos atrito.

Se o seu objetivo é sair do zero sem cair em exemplos antigos, use esta página como ponto de partida, valide os detalhes críticos na documentação oficial e só depois consolide snippets internos, templates de prompt e política de retries do seu time.