Como Construir um Aplicativo com a API do DeepSeek

Como Construir um Aplicativo com a API do DeepSeek é uma das dúvidas mais importantes para quem quer transformar modelos de IA em um produto real: um chatbot, assistente interno, copiloto de programação, ferramenta de análise de documentos ou recurso inteligente dentro de um SaaS.

A boa notícia é que a DeepSeek API segue um formato compatível com SDKs e ferramentas da OpenAI e da Anthropic, o que facilita bastante a integração. Na prática, você cria uma chave de API, configura um backend seguro, envia mensagens para o endpoint de chat e devolve a resposta para o usuário no frontend. A documentação oficial informa que o base_url no formato OpenAI é https://api.deepseek.com, e os modelos atuais para novas integrações são deepseek-v4-flash e deepseek-v4-pro.

Atualizado em 4 de maio de 2026: este tutorial usa os modelos DeepSeek V4. Os nomes deepseek-chat e deepseek-reasoner ainda aparecem em muitos exemplos antigos, mas a própria DeepSeek informa que eles serão descontinuados em 24 de julho de 2026 e que novas integrações devem usar deepseek-v4-flash ou deepseek-v4-pro.

Resposta rápida

Para construir um aplicativo com a API do DeepSeek, crie uma chave de API, guarde-a em uma variável de ambiente no backend, desenvolva uma rota segura que chama /chat/completions e conecte seu frontend React a essa rota. Use deepseek-v4-flash para respostas rápidas e econômicas, ou deepseek-v4-pro para tarefas mais complexas, raciocínio e agentes.

O que você vai construir neste tutorial

Neste guia, vamos montar a base de um aplicativo de chat com IA usando:

• frontend em React;
• backend com Node.js e Express;
• chamada segura à API do DeepSeek;
• exemplo alternativo em Python para testes rápidos;
• gerenciamento de histórico da conversa;
• boas práticas de segurança, custo, privacidade e produção.

O foco não é apenas “fazer a API responder”. O objetivo é criar uma estrutura que possa evoluir para um aplicativo real: um chatbot de suporte, um assistente de vendas, um copiloto interno, um analisador de documentos ou uma feature de IA dentro de um produto existente.

A arquitetura recomendada será:

Usuário
  ↓
Frontend React
  ↓
Backend Node.js / API Route / Serverless Function
  ↓
DeepSeek API
  ↓
Backend
  ↓
Frontend
  ↓
Usuário

Essa separação é essencial porque a chave da API DeepSeek nunca deve ficar exposta no navegador. O frontend deve conversar com o seu backend, e o backend deve conversar com a DeepSeek API.

Como funciona a API do DeepSeek em um aplicativo

A API do DeepSeek permite enviar uma lista de mensagens para um modelo e receber uma resposta gerada por IA. O principal endpoint usado neste tutorial é /chat/completions, que cria uma resposta a partir de uma conversa enviada pelo aplicativo. A referência oficial descreve esse endpoint como responsável por criar uma resposta do modelo para uma conversa de chat.

O fluxo básico é:

1. O usuário digita uma pergunta no aplicativo.
2. O frontend envia a pergunta para o backend.
3. O backend valida os dados e adiciona a chave da API.
4. O backend chama a API do DeepSeek.
5. A resposta volta para o frontend.
6. O usuário visualiza a resposta no chat.

Em Markdown, o fluxo fica assim:

[Usuário]
    |
    v
[React: campo de mensagem]
    |
    v
[POST /api/chat no seu backend]
    |
    v
[Validação + chave da API + chamada ao DeepSeek]
    |
    v
[Resposta do modelo]
    |
    v
[Interface do chat]

Essa arquitetura também facilita adicionar autenticação, limite de uso, logs, cache, cobrança por usuário e monitoramento de custo.

Pré-requisitos

Antes de começar, você precisa de:

Requisito	Para que serve
Conta na plataforma DeepSeek	Criar e gerenciar sua chave de API
Chave de API DeepSeek	Autenticar as requisições
Node.js instalado	Rodar o backend e o frontend
Editor de código	VS Code ou outro editor
Conhecimento básico de JavaScript	Entender React e Express
Noções de React	Criar a interface do chat
Python opcional	Testar chamadas simples à API

Também é recomendável abrir a documentação oficial da DeepSeek API enquanto desenvolve, porque nomes de modelos, preços, limites e recursos podem mudar com o tempo. A própria página de preços da DeepSeek recomenda revisar os valores mais recentes antes de tomar decisões de orçamento.

Modelos DeepSeek: v4-flash, v4-pro e nomes legados

A escolha do modelo afeta custo, latência e qualidade da resposta. Para novas integrações, use deepseek-v4-flash ou deepseek-v4-pro.

Segundo a documentação oficial, os dois modelos DeepSeek V4 suportam contexto de 1M, modos thinking e non-thinking, JSON Output, Tool Calls e Chat Prefix Completion beta. A página de modelos e preços lista deepseek-v4-flash e deepseek-v4-pro como modelos atuais, com deepseek-chat e deepseek-reasoner tratados como nomes legados.

Modelo	Melhor uso	Observação
deepseek-v4-flash	Chatbots rápidos, FAQ, suporte, respostas simples, classificação, automações leves	Melhor ponto de partida para MVPs e apps com alto volume
deepseek-v4-pro	Tarefas complexas, análise técnica, programação, agentes, raciocínio multi-etapas	Mais indicado quando qualidade e raciocínio importam mais que latência
deepseek-chat	Projetos antigos	Nome legado; corresponde temporariamente ao modo non-thinking do deepseek-v4-flash
deepseek-reasoner	Projetos antigos com raciocínio	Nome legado; corresponde temporariamente ao modo thinking do deepseek-v4-flash

Qual modelo escolher?

Para a maioria dos aplicativos, comece com deepseek-v4-flash. Ele tende a ser a melhor opção para validar produto, criar um chatbot simples e controlar custos. Use deepseek-v4-pro quando o usuário pedir análise detalhada, geração de código, planejamento complexo, uso de ferramentas ou tarefas em que uma resposta superficial prejudicaria a experiência.

No momento da revisão deste artigo, a página oficial informa preços por 1 milhão de tokens e destaca que os valores podem mudar. Para deepseek-v4-flash, a documentação lista US$ 0,14 por 1M tokens de entrada cache miss, US$ 0,0028 por 1M tokens de entrada cache hit e US$ 0,28 por 1M tokens de saída. Para deepseek-v4-pro, há desconto temporário informado até 31 de maio de 2026, com valores promocionais na página oficial. Sempre confirme na página oficial de modelos e preços da DeepSeek antes de publicar valores no seu site.

Arquitetura segura para produção

O erro mais grave ao integrar DeepSeek em um app é chamar a API diretamente do navegador. Isso expõe sua chave de API no código JavaScript, no DevTools, no tráfego de rede ou em builds públicos.

A arquitetura correta é:

Frontend → Backend → DeepSeek API

O backend funciona como uma camada de proteção. Ele recebe a mensagem do usuário, valida o conteúdo, adiciona a chave da API em ambiente seguro e decide qual modelo usar.

Boas práticas importantes:

Prática	Por que importa
Guardar a chave em variável de ambiente	Evita exposição no frontend e no repositório
Usar backend ou serverless function	Permite controlar autenticação, logs e custos
Implementar rate limit	Reduz abuso e ajuda a evitar erro 429
Validar entrada do usuário	Evita prompts gigantes, vazios ou malformados
Limitar histórico	Controla tokens e custo
Registrar erros	Facilita suporte e depuração
Autenticar usuários	Impede uso público descontrolado
Não enviar dados sensíveis sem necessidade	Reduz risco de privacidade e compliance
Monitorar uso por usuário	Ajuda a detectar abuso e controlar cobrança

Para um MVP, você pode começar com Express local. Para produção, pode migrar para uma API route em Next.js, uma função serverless, um container ou um serviço backend tradicional.

Configurando variáveis de ambiente

Crie um arquivo .env na raiz do backend:

DEEPSEEK_API_KEY=sua_chave_aqui
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash
PORT=3001

Adicione .env ao .gitignore:

.env
node_modules
dist
build

Nunca envie esse arquivo para o GitHub. Em produção, configure as variáveis diretamente no provedor de hospedagem, como Vercel, Render, Railway, Fly.io, AWS, Google Cloud ou Azure.

Primeira chamada com cURL

Antes de criar o app inteiro, teste a API com cURL. Esse teste confirma se sua chave funciona, se há saldo disponível e se o modelo está respondendo.

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 útil e objetivo."
      },
      {
        "role": "user",
        "content": "Explique em uma frase o que é a API do DeepSeek."
      }
    ],
    "thinking": {
      "type": "disabled"
    },
    "stream": false
  }'

A documentação oficial mostra exemplos de chamada com cURL, Python e Node.js usando o formato OpenAI, Authorization: Bearer ${DEEPSEEK_API_KEY} e o endpoint https://api.deepseek.com/chat/completions.

Use thinking: { "type": "disabled" } quando quiser respostas rápidas e diretas. Para tarefas mais complexas, você pode ativar o modo thinking, como veremos mais adiante.

Exemplo com Python e OpenAI SDK

A DeepSeek API é compatível com o SDK da OpenAI. Isso facilita testes rápidos em Python:

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-v4-flash",
    messages=[
        {
            "role": "system",
            "content": "Você é um assistente técnico claro e prático."
        },
        {
            "role": "user",
            "content": "Crie uma explicação curta sobre APIs de IA."
        }
    ],
    stream=False,
    extra_body={
        "thinking": {
            "type": "disabled"
        }
    }
)

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

Se quiser usar o modo thinking no Python, use deepseek-v4-pro, reasoning_effort="high" e extra_body={"thinking": {"type": "enabled"}}. A documentação oficial mostra esse padrão no exemplo com OpenAI SDK.

Construindo o backend com Node.js e Express

Agora vamos criar uma API segura. O frontend React vai chamar essa rota, e essa rota vai chamar a DeepSeek API.

Crie uma pasta para o backend:

mkdir deepseek-app-backend
cd deepseek-app-backend
npm init -y
npm install express cors dotenv openai express-rate-limit zod

No package.json, adicione:

{
  "type": "module",
  "scripts": {
    "dev": "node server.js"
  }
}

Crie o arquivo server.js:

import express from "express";
import cors from "cors";
import rateLimit from "express-rate-limit";
import { z } from "zod";
import OpenAI from "openai";
import "dotenv/config";

const app = express();

app.use(express.json({ limit: "1mb" }));

app.use(
  cors({
    origin: process.env.FRONTEND_ORIGIN || "http://localhost:5173"
  })
);

const limiter = rateLimit({
  windowMs: 60 * 1000,
  limit: 30,
  standardHeaders: true,
  legacyHeaders: false
});

app.use("/api", limiter);

if (!process.env.DEEPSEEK_API_KEY) {
  throw new Error("DEEPSEEK_API_KEY não foi definida no ambiente.");
}

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

const MessageSchema = z.object({
  role: z.enum(["user", "assistant"]),
  content: z.string().min(1).max(4000)
});

const ChatRequestSchema = z.object({
  messages: z.array(MessageSchema).min(1).max(20)
});

app.post("/api/chat", async (req, res) => {
  try {
    const parsed = ChatRequestSchema.safeParse(req.body);

    if (!parsed.success) {
      return res.status(400).json({
        error: "Formato inválido. Envie uma lista de mensagens válida."
      });
    }

    const userMessages = parsed.data.messages;

    const systemPrompt = {
      role: "system",
      content:
        "Você é um assistente útil, claro e seguro. Responda em português do Brasil."
    };

    const messages = [
      systemPrompt,
      ...userMessages.slice(-12)
    ];

    const completion = await deepseek.chat.completions.create({
      model: process.env.DEEPSEEK_MODEL || "deepseek-v4-flash",
      messages,
      max_tokens: 900,
      stream: false,
      thinking: {
        type: "disabled"
      }
    });

    const answer = completion.choices?.[0]?.message?.content || "";

    return res.json({
      answer,
      usage: completion.usage || null
    });
  } catch (error) {
    console.error("Erro ao chamar DeepSeek:", error);

    const status = error?.status || 500;

    if (status === 401) {
      return res.status(401).json({
        error: "Falha de autenticação com a API do DeepSeek."
      });
    }

    if (status === 402) {
      return res.status(402).json({
        error: "Saldo insuficiente na conta da DeepSeek."
      });
    }

    if (status === 429) {
      return res.status(429).json({
        error: "Muitas requisições. Tente novamente em alguns instantes."
      });
    }

    return res.status(500).json({
      error: "Erro ao gerar resposta com IA."
    });
  }
});

const port = process.env.PORT || 3001;

app.listen(port, () => {
  console.log(`Backend rodando em http://localhost:${port}`);
});

Rode o backend:

npm run dev

Esse backend já inclui validação básica com Zod, limite de requisições, leitura da chave por variável de ambiente e tratamento de erros comuns.

Criando o frontend em React

Agora crie o frontend com Vite:

npm create vite@latest deepseek-app-frontend -- --template react
cd deepseek-app-frontend
npm install
npm run dev

Substitua o conteúdo principal do src/App.jsx por:

import { useState } from "react";
import "./App.css";

export default function App() {
  const [messages, setMessages] = useState([
    {
      role: "assistant",
      content: "Olá! Como posso ajudar?"
    }
  ]);

  const [input, setInput] = useState("");
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState("");

  async function sendMessage(event) {
    event.preventDefault();

    const text = input.trim();

    if (!text || loading) return;

    setError("");

    const nextMessages = [
      ...messages,
      {
        role: "user",
        content: text
      }
    ];

    setMessages(nextMessages);
    setInput("");
    setLoading(true);

    try {
      const response = await fetch("http://localhost:3001/api/chat", {
        method: "POST",
        headers: {
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          messages: nextMessages.filter((message) => message.role !== "assistant" || message.content)
        })
      });

      const data = await response.json();

      if (!response.ok) {
        throw new Error(data.error || "Erro ao chamar o backend.");
      }

      setMessages([
        ...nextMessages,
        {
          role: "assistant",
          content: data.answer
        }
      ]);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }

  return (
    <main className="chat-page">
      <section className="chat-card">
        <h1>Chat com DeepSeek</h1>

        <div className="messages">
          {messages.map((message, index) => (
            <div key={index} className={`message ${message.role}`}>
              <strong>{message.role === "user" ? "Você" : "Assistente"}</strong>
              <p>{message.content}</p>
            </div>
          ))}

          {loading && (
            <div className="message assistant">
              <strong>Assistente</strong>
              <p>Gerando resposta...</p>
            </div>
          )}
        </div>

        {error && <p className="error">{error}</p>}

        <form onSubmit={sendMessage} className="chat-form">
          <input
            value={input}
            onChange={(event) => setInput(event.target.value)}
            placeholder="Digite sua mensagem..."
          />

          <button type="submit" disabled={loading}>
            {loading ? "Enviando..." : "Enviar"}
          </button>
        </form>
      </section>
    </main>
  );
}

E um CSS simples em src/App.css:

.chat-page {
  min-height: 100vh;
  display: flex;
  justify-content: center;
  padding: 40px 16px;
  background: #f5f5f5;
  font-family: Arial, sans-serif;
}

.chat-card {
  width: 100%;
  max-width: 760px;
  background: #ffffff;
  border-radius: 16px;
  padding: 24px;
  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.08);
}

.messages {
  display: flex;
  flex-direction: column;
  gap: 12px;
  margin: 24px 0;
}

.message {
  padding: 12px 14px;
  border-radius: 12px;
  line-height: 1.5;
}

.message.user {
  background: #e8f0ff;
  align-self: flex-end;
}

.message.assistant {
  background: #f1f1f1;
  align-self: flex-start;
}

.message p {
  margin: 6px 0 0;
}

.chat-form {
  display: flex;
  gap: 8px;
}

.chat-form input {
  flex: 1;
  padding: 12px;
  border: 1px solid #cccccc;
  border-radius: 8px;
}

.chat-form button {
  padding: 12px 18px;
  border: 0;
  border-radius: 8px;
  cursor: pointer;
}

.error {
  color: #b00020;
}

O React não chama a API do DeepSeek diretamente. Ele chama apenas o seu backend local. Essa separação é o que permite proteger a chave da API, aplicar autenticação e controlar custo por usuário.

Mantendo o histórico da conversa

A API /chat/completions da DeepSeek é stateless. Isso significa que o servidor da API não guarda automaticamente o histórico das mensagens anteriores. Se você quer que o modelo entenda o contexto, seu aplicativo precisa reenviar as mensagens relevantes a cada nova requisição.

Exemplo simples:

const messages = [
  {
    role: "system",
    content: "Você é um assistente de suporte."
  },
  {
    role: "user",
    content: "Meu pedido atrasou."
  },
  {
    role: "assistant",
    content: "Sinto muito pelo atraso. Você pode informar o número do pedido?"
  },
  {
    role: "user",
    content: "É o pedido 12345."
  }
];

Mas cuidado: reenviar histórico infinito aumenta custo, latência e risco de exceder limites de contexto.

Boas práticas:

Problema	Solução
Conversa longa demais	Enviar apenas as últimas mensagens
Contexto importante no começo	Criar um resumo da conversa
System prompt repetido	Mantê-lo curto e fixo
Mensagens irrelevantes	Remover antes da chamada
Dados sensíveis	Evitar envio ou mascarar informações
Custo alto	Limitar tokens de entrada e saída

Uma boa estratégia é manter as últimas 8 a 12 mensagens e gerar um resumo quando a conversa passar de determinado tamanho.

Streaming de respostas

Streaming faz a resposta aparecer aos poucos, como em um chat moderno. Em vez de esperar a resposta completa, o backend recebe tokens parciais e envia para o frontend gradualmente.

A referência da API informa que, quando stream é ativado, os deltas de mensagem são enviados por Server-Sent Events, com encerramento em data: [DONE].

Use streaming quando:

• as respostas forem longas;
• a experiência do usuário importar muito;
• você quiser reduzir a sensação de espera;
• estiver criando um chatbot em tempo real.

Evite streaming no primeiro MVP se isso complicar demais. Comece com stream: false, valide o produto e depois implemente streaming.

Exemplo básico no Node.js:

const stream = await deepseek.chat.completions.create({
  model: "deepseek-v4-flash",
  messages,
  stream: true,
  thinking: {
    type: "disabled"
  }
});

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

Em produção, você precisará encaminhar esses deltas para o frontend usando SSE, WebSocket ou streaming HTTP.

JSON Output para respostas estruturadas

O JSON Output é útil quando você não quer apenas texto, mas dados estruturados. Por exemplo:

• classificar tickets;
• extrair campos de um documento;
• preencher formulários;
• gerar objetos para automações;
• integrar respostas com banco de dados;
• criar regras para sistemas internos.

A documentação oficial informa que, para ativar JSON Output, você deve definir response_format como { "type": "json_object" }, incluir a palavra “json” no prompt e fornecer um exemplo do formato esperado. Ela também recomenda definir max_tokens de forma razoável para evitar truncamento.

Exemplo:

const response = await deepseek.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    {
      role: "system",
      content:
        "Responda sempre em json válido. Use o formato: {\"categoria\":\"string\",\"prioridade\":\"baixa|media|alta\",\"resumo\":\"string\"}"
    },
    {
      role: "user",
      content:
        "Cliente diz que não consegue acessar a conta e precisa resolver hoje."
    }
  ],
  response_format: {
    type: "json_object"
  },
  max_tokens: 500,
  thinking: {
    type: "disabled"
  }
});

const json = JSON.parse(response.choices[0].message.content);
console.log(json);

Mesmo com JSON Output, valide o resultado no backend antes de salvar no banco ou executar qualquer ação. Um modelo pode gerar um campo inesperado, uma categoria fora do padrão ou um valor que precisa ser normalizado.

Tool Calls: conectando o modelo a funções externas

Tool Calls permitem que o modelo solicite a execução de uma função. Isso é útil quando o aplicativo precisa consultar dados externos.

Exemplos:

• consultar estoque;
• buscar dados no CRM;
• verificar agenda;
• consultar banco de dados;
• buscar clima;
• abrir ticket de suporte;
• calcular frete;
• verificar status de pedido.

Um ponto essencial: o modelo não executa a função sozinho. Ele sugere a chamada da ferramenta, e o seu backend executa a função real. A documentação oficial deixa claro que a função precisa ser fornecida pelo usuário e que o modelo em si não executa funções específicas.

Exemplo simplificado:

const tools = [
  {
    type: "function",
    function: {
      name: "consultar_pedido",
      description: "Consulta o status de um pedido pelo número.",
      parameters: {
        type: "object",
        properties: {
          numero_pedido: {
            type: "string",
            description: "Número do pedido do cliente"
          }
        },
        required: ["numero_pedido"]
      }
    }
  }
];

const response = await deepseek.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [
    {
      role: "user",
      content: "Qual é o status do pedido 12345?"
    }
  ],
  tools,
  tool_choice: "auto",
  thinking: {
    type: "enabled"
  },
  reasoning_effort: "high"
});

Depois disso, seu backend precisa verificar se há tool_calls, validar os argumentos e chamar sua função real:

const toolCalls = response.choices[0].message.tool_calls;

if (toolCalls?.length) {
  for (const toolCall of toolCalls) {
    if (toolCall.function.name === "consultar_pedido") {
      const args = JSON.parse(toolCall.function.arguments);

      // Valide os argumentos antes de executar
      const status = await consultarPedidoNoBanco(args.numero_pedido);

      // Envie o resultado da ferramenta de volta ao modelo
    }
  }
}

Para produção, nunca execute uma tool call sem validação. Verifique permissões, autenticação, schema, limites e se o usuário realmente pode acessar aquele recurso.

Thinking Mode: quando ativar e quando evitar

O Thinking Mode permite que o modelo faça raciocínio antes de produzir a resposta final. Segundo a documentação da DeepSeek, o modo thinking é suportado pelos modelos e pode ser controlado com thinking: { "type": "enabled" } ou thinking: { "type": "disabled" }. No formato OpenAI, o controle de esforço usa reasoning_effort, e o modo thinking vem habilitado por padrão.

Use Thinking Mode para:

• programação;
• depuração de código;
• análise técnica;
• tarefas com várias etapas;
• agentes com ferramentas;
• planejamento;
• decisões que exigem comparação;
• análise de documentos longos.

Evite Thinking Mode para:

• FAQ simples;
• respostas curtas;
• mensagens de atendimento repetitivas;
• classificação básica;
• autocomplete;
• fluxos em que latência importa mais que profundidade.

Exemplo com deepseek-v4-pro:

const completion = await deepseek.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [
    {
      role: "system",
      content: "Você é um arquiteto de software experiente."
    },
    {
      role: "user",
      content: "Analise os riscos de migrar um monólito para microsserviços."
    }
  ],
  thinking: {
    type: "enabled"
  },
  reasoning_effort: "high",
  stream: false
});

Em aplicativos para usuário final, normalmente você mostra apenas a resposta final. Evite expor raciocínio interno sensível, prompts de sistema, regras internas ou detalhes de segurança.

Custos, tokens e Context Caching

A cobrança da DeepSeek API é baseada em tokens de entrada e saída. A documentação descreve tokens como unidades básicas usadas pelos modelos para representar texto e também como unidade de cobrança. A página de preços explica que o custo é calculado a partir do número de tokens multiplicado pelo preço correspondente.

Em termos práticos:

• prompt maior = mais tokens de entrada;
• resposta maior = mais tokens de saída;
• histórico longo = custo maior;
• thinking mode pode gerar mais tokens;
• tool calls podem criar múltiplas rodadas;
• respostas em streaming também consomem tokens normalmente.

A DeepSeek também oferece Context Caching ativado por padrão. Quando requisições têm prefixos sobrepostos, partes repetidas podem ser recuperadas do cache, contando como cache hit. Isso pode reduzir custo e latência em cenários com prompts ou contextos repetidos.

Fator que aumenta custo	Como reduzir
Histórico de conversa muito longo	Enviar só mensagens recentes ou resumo
System prompt gigante	Tornar instruções mais curtas
Modelo avançado para tarefa simples	Usar deepseek-v4-flash
Thinking Mode em tudo	Ativar apenas em tarefas complexas
Respostas longas sem necessidade	Definir max_tokens
Repetição de documentos grandes	Aproveitar padrões que favorecem Context Caching
Usuários abusivos	Usar autenticação e limite por conta
Falta de monitoramento	Salvar usage e acompanhar consumo

Uma boa prática é registrar o campo usage retornado pela API. A referência oficial mostra estatísticas como prompt_tokens, completion_tokens, prompt_cache_hit_tokens, prompt_cache_miss_tokens e total_tokens.

Tratamento de erros comuns

Erros de API são normais em produção. O importante é tratá-los bem para que o usuário não veja mensagens técnicas e para que sua equipe consiga corrigir o problema.

A documentação oficial da DeepSeek lista códigos como 400, 401, 402, 422, 429, 500 e 503, com causas e soluções recomendadas.

Código	Causa provável	Solução prática
400	Corpo da requisição inválido	Verifique JSON, mensagens, parâmetros e schema
401	Chave incorreta ou ausente	Confira DEEPSEEK_API_KEY e header Bearer
402	Saldo insuficiente	Verifique saldo e recarregue a conta
422	Parâmetros inválidos	Remova parâmetros incompatíveis ou ajuste o modelo
429	Muitas requisições	Aplique retry com backoff, fila e rate limit
500	Erro interno no servidor	Tente novamente após breve espera
503	Servidor sobrecarregado	Aplique retry e fallback temporário

A página de rate limit informa que a DeepSeek limita dinamicamente a concorrência com base na carga do servidor e retorna HTTP 429 quando o limite é alcançado. Ela também observa que, se uma requisição não iniciar inferência após 10 minutos, o servidor fecha a conexão.

Exemplo de retry simples:

async function withRetry(fn, attempts = 3) {
  let lastError;

  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;

      if (![429, 500, 503].includes(error?.status)) {
        throw error;
      }

      const delay = 500 * Math.pow(2, i);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }

  throw lastError;
}

Não faça retry infinito. Isso pode aumentar custo, piorar congestionamento e prejudicar a experiência do usuário.

Checklist antes de publicar o aplicativo

Antes de colocar seu aplicativo com DeepSeek em produção, revise:

• A chave da API está em variável de ambiente.
• O arquivo .env está fora do Git.
• O frontend não chama a DeepSeek API diretamente.
• Existe rate limit no backend.
• Usuários são autenticados quando necessário.
• Entradas são validadas.
• Prompts muito longos são bloqueados ou resumidos.
• O histórico de conversa é limitado.
• max_tokens foi configurado.
• Erros 400, 401, 402, 422, 429, 500 e 503 são tratados.
• O uso de tokens é registrado.
• Há monitoramento de custo.
• Existe fallback para indisponibilidade.
• Tool Calls são validadas antes de executar funções.
• Respostas JSON são validadas antes de serem usadas.
• Dados sensíveis não são enviados sem necessidade.
• A política de privacidade explica o uso de IA quando aplicável.
• O modelo escolhido faz sentido para o caso de uso.

Exemplos de casos de uso

Você pode integrar DeepSeek em vários tipos de aplicativo:

Caso de uso	Modelo recomendado
Chatbot de suporte	deepseek-v4-flash
FAQ inteligente	deepseek-v4-flash
Assistente interno	deepseek-v4-flash ou deepseek-v4-pro
Resumo de documentos	deepseek-v4-pro para documentos complexos
Copiloto de programação	deepseek-v4-pro
Classificação de tickets	deepseek-v4-flash com JSON Output
Geração de respostas para atendimento	deepseek-v4-flash
Análise de contratos ou relatórios	deepseek-v4-pro, com cuidado de privacidade
Agente com ferramentas internas	deepseek-v4-pro com Tool Calls
Busca assistida em base de conhecimento	deepseek-v4-flash para respostas simples, deepseek-v4-pro para análise

Para um primeiro produto, escolha um caso de uso estreito. Por exemplo: “responder dúvidas sobre pedidos” é melhor que “fazer atendimento inteiro da empresa”. Quanto mais específico o problema, mais fácil medir qualidade, custo e segurança.

Erros que você deve evitar

Evite estes erros ao integrar DeepSeek em um aplicativo:

1. Colocar a chave no frontend
   Qualquer pessoa pode copiar sua chave e usar sua conta.
2. Usar modelo avançado para tudo
   Muitas tarefas simples funcionam bem com deepseek-v4-flash.
3. Reenviar histórico enorme
   Isso aumenta custo e latência.
4. Ignorar erro 429
   Sem rate limit e retry adequado, seu app pode falhar sob carga.
5. Não validar entrada
   Prompts vazios, gigantes ou maliciosos prejudicam o sistema.
6. Confiar cegamente em JSON gerado
   Sempre valide antes de salvar ou executar ações.
7. Executar Tool Calls sem permissão
   O backend deve validar argumentos e autorização.
8. Não monitorar custo
   Um usuário abusivo pode consumir muito saldo.
9. Não revisar a documentação
   Modelos, preços e recursos mudam.
10. Usar nomes legados em novo projeto
    Prefira deepseek-v4-flash e deepseek-v4-pro.

Conclusão

Construir um aplicativo com a API do DeepSeek é relativamente simples do ponto de vista técnico, principalmente porque a API usa formato compatível com SDKs conhecidos. O desafio real está em criar uma arquitetura segura, controlar custos, escolher o modelo certo e preparar o app para produção.

Comece com um MVP: React no frontend, Node.js no backend, deepseek-v4-flash como modelo padrão e uma rota /api/chat protegida. Depois, evolua com streaming, JSON Output, Tool Calls, Thinking Mode, autenticação e monitoramento de uso.

Se o seu aplicativo precisa de respostas rápidas e econômicas, deepseek-v4-flash tende a ser o melhor início. Se precisa de raciocínio profundo, análise técnica ou agentes, teste deepseek-v4-pro. Em ambos os casos, mantenha a chave protegida, valide tudo no backend e acompanhe a página oficial de modelos e preços antes de escalar.

FAQ