Atualizado em 17 de abril de 2026: este guia foi reescrito para refletir a documentação oficial atual da API do DeepSeek e remover explicações que ficaram desatualizadas em versões anteriores do artigo.
Construir um aplicativo com a API do DeepSeek hoje é mais simples para quem já trabalha com o ecossistema OpenAI. A documentação oficial atual informa que a API pública usa um formato compatível com OpenAI, aceita https://api.deepseek.com como base_url e expõe dois IDs principais para novas integrações: deepseek-chat e deepseek-reasoner. Na camada pública atual, ambos correspondem ao DeepSeek-V3.2, mas em modos diferentes.
Na prática, isso significa o seguinte: deepseek-chat é o modo non-thinking, indicado para respostas diretas, interfaces conversacionais, extração simples, classificações e rotinas de geração comuns; já deepseek-reasoner é o modo thinking, voltado a raciocínio mais profundo, planejamento, análise multi-etapas, matemática, programação e fluxos avançados com ferramentas.
Neste guia, você vai ver a arquitetura recomendada para produção, um exemplo real com cURL, Python, Node.js e React, além de boas práticas de histórico, segurança, JSON estruturado, Tool Calls, contexto longo, cache e controle de custos. Se você também quiser acompanhar cobrança e mudanças de modelo, consulte em paralelo a página de Preços do DeepSeek e a FAQ.
O que a API do DeepSeek oferece hoje
Antes de começar a integração, vale alinhar a terminologia correta da documentação oficial atual:
- Formato compatível com OpenAI: você pode usar SDKs e clientes compatíveis com OpenAI trocando a chave e a base URL para
https://api.deepseek.com. /v1é opcional para compatibilidade: se a sua biblioteca exigir,https://api.deepseek.com/v1também funciona. Ov1aqui é apenas compatibilidade de rota e não indica a versão do modelo.- Dois IDs principais na API pública:
deepseek-chatedeepseek-reasoner. Hoje eles correspondem ao DeepSeek-V3.2 na API, embora a própria documentação observe que a versão servida no APP/WEB pode diferir da versão da API. - Contexto longo: a documentação atual apresenta limite de contexto de 128K para os dois modos na API pública.
- Saída máxima por modo: no modo non-thinking, a saída padrão é menor e o teto público chega a 8K; no thinking mode, a saída padrão é 32K e o máximo chega a 64K.
- Recursos suportados hoje: JSON Output e Tool Calls estão disponíveis para os dois modos; Chat Prefix Completion continua em Beta.
Em outras palavras: se você está criando um chatbot, um assistente interno, uma automação ou um fluxo de atendimento, o endpoint principal continua sendo /chat/completions. O endpoint /completions existe para FIM Completion em Beta e não deve ser apresentado como o caminho “normal” para a maioria das integrações modernas.
Quando usar deepseek-chat e quando usar deepseek-reasoner
Escolher o modo certo evita custo desnecessário, simplifica a experiência do usuário e deixa o seu aplicativo mais previsível.
Use deepseek-chat quando o foco for velocidade e simplicidade
- Chatbots de atendimento, FAQ, suporte e triagem.
- Resumo curto, classificação, extração simples e reformulação de texto.
- Geração de conteúdo, revisão, tradução e automações de texto em geral.
- Apps que precisam de respostas diretas sem expor uma etapa explícita de raciocínio.
Use deepseek-reasoner quando a tarefa exigir raciocínio mais profundo
- Análise técnica com múltiplas etapas.
- Problemas de lógica, matemática, planejamento e depuração.
- Assistentes de programação com investigação mais detalhada.
- Agentes com Tool Calls em cenários em que o raciocínio intermediário melhora a qualidade do resultado.
Se você já integrou a API usando deepseek-chat, a documentação também permite ativar o thinking mode via parâmetro thinking. Na prática, porém, para a maioria dos produtos é mais claro escolher explicitamente entre deepseek-chat e deepseek-reasoner no campo model.
Arquitetura recomendada para um aplicativo real
Uma arquitetura segura para produção costuma seguir este fluxo:
- O frontend coleta a pergunta do usuário.
- O seu backend valida entrada, aplica regras internas e injeta a chave privada da API.
- O backend chama a API do DeepSeek e devolve ao frontend apenas o que faz sentido expor.
Esse desenho evita expor a sua chave de API no navegador, centraliza validação, limita abuso, ajuda no controle de custos e facilita logs, métricas e moderação. Em produção, evite chamar a API do DeepSeek diretamente do browser com a chave embutida no JavaScript final.
1) Criando sua conta e preparando variáveis de ambiente
Para começar, crie sua conta em platform.deepseek.com, gere sua chave e armazene tudo em variáveis de ambiente. Uma configuração mínima fica assim:
DEEPSEEK_API_KEY=dpsk_xxxxxxxxxxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.comSe a sua biblioteca for estritamente compatível com a rota da OpenAI, você também pode usar https://api.deepseek.com/v1. Para valores de cobrança, descontos e mudanças futuras, trate a página oficial de preços como fonte final de verdade e use a página de Preços do DeepSeek apenas como apoio editorial em português.
2) Sua primeira chamada com cURL
O teste mais rápido é uma chamada simples ao endpoint de chat:
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."},
{"role": "user", "content": "Explique em duas frases o que é a API do DeepSeek."}
],
"stream": false
}'Nesse fluxo, o campo mais importante da resposta costuma ser choices[0].message.content. É ele que você renderiza no seu app.
3) Exemplo em Python com o SDK compatível com OpenAI
Para backends, scripts internos e jobs assíncronos, Python continua sendo um dos caminhos mais práticos:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("DEEPSEEK_API_KEY"),
base_url=os.environ.get("DEEPSEEK_BASE_URL", "https://api.deepseek.com"),
)
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{"role": "system", "content": "Você é um assistente técnico objetivo."},
{"role": "user", "content": "Liste 3 casos de uso da API do DeepSeek para uma empresa SaaS."}
],
stream=False,
)
print(response.choices[0].message.content)Se você precisar explicitamente do modo de raciocínio, a forma mais direta é trocar o modelo:
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=[
{"role": "user", "content": "Compare duas arquiteturas de chatbot e indique a melhor para auditoria interna."}
]
)
print(response.choices[0].message.reasoning_content)
print(response.choices[0].message.content)Você também pode ativar o thinking mode mantendo deepseek-chat e enviando extra_body={"thinking": {"type": "enabled"}}, mas a escolha explícita de modelo costuma ser mais legível em produção.
4) Exemplo de backend seguro em Node.js
Em vez de enviar sua chave para o frontend, crie uma rota no seu servidor. Um exemplo simples com Express:
import express from "express";
import OpenAI from "openai";
const app = express();
app.use(express.json());
const client = new OpenAI({
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: process.env.DEEPSEEK_BASE_URL || "https://api.deepseek.com",
});
app.post("/api/deepseek", async (req, res) => {
try {
const { messages = [], mode = "chat" } = req.body;
const response = await client.chat.completions.create({
model: mode === "reasoner" ? "deepseek-reasoner" : "deepseek-chat",
messages,
stream: false,
});
const message = response.choices[0].message;
res.json({
content: message.content,
reasoning_content: message.reasoning_content ?? null,
usage: response.usage ?? null,
});
} catch (error) {
res.status(500).json({
error: "Falha ao chamar a API do DeepSeek.",
details: error?.message ?? "Erro desconhecido",
});
}
});
app.listen(3001, () => {
console.log("Servidor ativo em http://localhost:3001");
});Esse backend já resolve três problemas de uma vez: protege a chave, permite validar o payload e cria um ponto central para métricas, limites de uso e logs.
5) Exemplo de frontend React consumindo o seu backend
Com a rota pronta, o frontend React fica limpo e seguro. Ele conversa com o seu próprio backend, não com a API do DeepSeek diretamente:
import { useState } from "react";
export default function ChatDeepSeek() {
const [input, setInput] = useState("");
const [messages, setMessages] = useState([
{ role: "system", content: "Você é um assistente útil e direto." }
]);
const [answer, setAnswer] = useState("");
const [loading, setLoading] = useState(false);
async function handleSubmit(e) {
e.preventDefault();
if (!input.trim()) return;
const nextMessages = [...messages, { role: "user", content: input }];
setLoading(true);
setAnswer("");
try {
const resp = await fetch("/api/deepseek", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
messages: nextMessages,
mode: "chat"
})
});
const data = await resp.json();
const assistantMessage = {
role: "assistant",
content: data.content ?? ""
};
setMessages([...nextMessages, assistantMessage]);
setAnswer(data.content ?? "");
setInput("");
} catch (error) {
setAnswer("Erro ao obter resposta.");
} finally {
setLoading(false);
}
}
return (
<div className="chat-container">
<h3>Assistente com DeepSeek</h3>
<form onSubmit={handleSubmit}>
<input
type="text"
value={input}
onChange={(e) => setInput(e.target.value)}
placeholder="Digite sua pergunta"
/>
<button type="submit" disabled={loading}>
{loading ? "Consultando..." : "Enviar"}
</button>
</form>
{answer && (
<div className="resposta-ia">
<strong>Resposta:</strong> {answer}
</div>
)}
</div>
);
}Esse padrão já é suficiente para MVP, atendimento, assistentes internos e muitas automações baseadas em texto. Quando quiser avançar, você pode adicionar streaming, autenticação, rate limit do seu lado, cache próprio e validação mais rígida do payload.
6) Conversa multi-turn: a API é stateless
Um ponto fundamental da documentação oficial é que o endpoint /chat/completions é stateless. Isso significa que o servidor não “lembra” sozinho da conversa anterior. A cada nova chamada, a sua aplicação precisa reenviar o histórico relevante.
Por exemplo, se o usuário fizer uma segunda pergunta dependente da primeira, você deve montar algo assim:
[
{"role": "user", "content": "Qual é a montanha mais alta do mundo?"},
{"role": "assistant", "content": "A montanha mais alta do mundo é o Monte Everest."},
{"role": "user", "content": "E qual é a segunda?"}
]Sem isso, a resposta da IA pode parecer “sem contexto”. Essa regra também impacta custo, porque histórico muito longo aumenta tokens. Por isso, vale combinar o reenvio do histórico com resumo de contexto, poda de mensagens antigas e seleção inteligente do que realmente precisa seguir em cada turno.
7) JSON Output para respostas estruturadas
Se o seu aplicativo precisa extrair dados, preencher campos ou responder em formato estruturado, use JSON Output. O detalhe importante é que não basta enviar response_format={"type":"json_object"}; você também deve instruir o modelo a responder em JSON no prompt.
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{
"role": "system",
"content": "Responda apenas com JSON válido com as chaves nome e email."
},
{
"role": "user",
"content": "Extraia os dados: João Silva, [email protected]"
}
],
response_format={"type": "json_object"}
)
print(response.choices[0].message.content)Esse recurso é especialmente útil para formulários, ETL leve, agentes internos, automação de CRM, classificação de tickets e integrações em que você precisa de saída previsível.
8) Tool Calls: o modelo sugere a ferramenta, o seu backend executa
Tool Calls é o nome atual da funcionalidade que muita gente ainda chama de function calling. A ideia é simples: o modelo pode pedir a execução de uma função externa, mas ele não executa essa função sozinho. Quem executa é o seu backend.
Esse recurso hoje faz sentido em fluxos como:
- consultar estoque, clima, agenda, CRM ou banco de dados interno;
- acionar um conector de busca, ERP, help desk ou sistema financeiro;
- estruturar agentes que planejam uma ação, chamam uma ferramenta e só então devolvem a resposta final.
Se você quiser validação mais rígida de schema, a documentação atual também oferece strict mode em Beta na base URL https://api.deepseek.com/beta. Nesse modo, o schema JSON da ferramenta precisa seguir as restrições aceitas pela API.
Nota importante sobre thinking mode + Tool Calls
Na versão atual da documentação, o thinking mode também suporta Tool Calls. Porém, existe um detalhe operacional importante: quando o modelo estiver no meio de um processo de raciocínio com chamadas de ferramenta, o campo reasoning_content precisa voltar para a API durante as sub-etapas da mesma pergunta. Quando começar um novo turno do usuário, esse reasoning_content anterior deve ser descartado.
Se você pretende construir agentes mais sofisticados, leia também a página de Thinking Mode antes de implementar o loop de ferramentas.
9) Recursos Beta que fazem sentido em casos específicos
Além do fluxo principal de chat, a DeepSeek mantém alguns recursos Beta úteis em cenários mais técnicos:
- Chat Prefix Completion (Beta): permite forçar a continuação de um prefixo no último papel
assistant. É útil quando você quer iniciar uma resposta com um formato muito específico, como um bloco de código. - FIM Completion (Beta): usa o endpoint
/completionscombase_url=https://api.deepseek.com/betapara completar o “meio” entre um prefixo e um sufixo. É um recurso voltado a preenchimento de código e não substitui o fluxo principal de chat.
Se o seu projeto é um chat, um assistente de suporte, um painel interno ou uma automação textual, você provavelmente deve começar por /chat/completions e deixar esses recursos Beta para a segunda fase.
10) Boas práticas para custo, latência e qualidade
- Não exponha a chave no frontend: use backend, serverless function ou API route.
- Reenvie o histórico com critério: a API é stateless, então a aplicação deve decidir o que entra em cada turno.
- Aproveite o Context Caching: prefixes repetidos podem gerar cache hit automaticamente, o que ajuda em conversas e prompts com partes fixas.
- Use o modo certo para o trabalho: comece com
deepseek-chatquando a tarefa não exigir raciocínio aprofundado. - Não fixe preços no conteúdo nem no código: a própria DeepSeek informa que preços podem mudar. Consulte sempre a página oficial antes de estimar custo em produção.
- Faça logs de
usage: acompanhar tokens por rota, usuário ou caso de uso ajuda muito a prever custo e identificar abuso. - Em thinking mode, não dependa de
temperaturee afins: a documentação atual informa que parâmetros comotemperature,top_p,presence_penaltyefrequency_penaltynão produzem efeito nesse modo, embora possam ser aceitos por compatibilidade. - Planeje latência: a documentação atual diz que a API não impõe um rate limit fixo universal, mas sob alta carga a conexão pode permanecer aberta por mais tempo. Streaming, timeouts adequados e retentativas exponenciais ajudam bastante.
- Valide Tool Calls do lado do servidor: o modelo pode sugerir chamadas incorretas; o seu backend deve validar nome da função, parâmetros, permissões e impacto antes de executar qualquer ação.
Erros comuns ao integrar a API do DeepSeek
- Chamar a API direto do React com a chave exposta.
- Assumir que a API lembra a conversa sem reenviar o histórico.
- Tratar
deepseek-chatedeepseek-reasonercomo “endpoints diferentes”, quando na prática eles são valores do campomodel. - Usar JSON Output sem dizer explicitamente ao modelo para responder em JSON.
- Apresentar FIM Completion como fluxo padrão de app, quando ele é um recurso Beta especializado.
- Ignorar o tratamento de
reasoning_contentem fluxos avançados de thinking mode com ferramentas.
Conclusão
A forma mais segura e atual de construir um aplicativo com a API do DeepSeek é esta: usar /chat/completions como endpoint principal, escolher conscientemente entre deepseek-chat e deepseek-reasoner, manter a chave no backend, reenviar histórico de conversa quando necessário e tratar JSON, Tool Calls e recursos Beta como componentes arquiteturais — não como detalhes cosméticos.
Se você quer colocar algo útil no ar rapidamente, comece com um backend pequeno, um frontend simples e deepseek-chat. Se depois precisar de raciocínio mais profundo, agentes com ferramentas e análise em múltiplas etapas, avance para deepseek-reasoner e para o guia oficial de thinking mode. Para acompanhar mudanças futuras, use como base a documentação oficial e, em português, siga também as páginas do seu site sobre DeepSeek API, DeepSeek V3.2, Preços e FAQ.
Nota editorial: o deepseek-portugues.chat é um projeto independente. Para decisões de produção, confirme sempre a documentação oficial, a página oficial de preços e os termos públicos da plataforma.
