DeepSeek API Docs: guia completo da DeepSeek API em português

A DeepSeek API permite integrar modelos de IA da DeepSeek em aplicações, agentes, backends, produtos SaaS, automações e ferramentas internas. Este guia funciona como uma versão prática em português brasileiro do que muitos desenvolvedores procuram por DeepSeek API Docs ou DeepSeek Documentation: como criar uma API key, escolher o modelo, fazer a primeira chamada, usar Python e Node.js, entender preços, ativar JSON Output, usar Tool Calls, controlar Thinking Mode, lidar com erros e preparar a integração para produção.

Segundo a documentação oficial consultada em 10 de maio de 2026, a DeepSeek API usa um formato compatível com OpenAI e Anthropic; no formato OpenAI, o base_url é https://api.deepseek.com, e no formato Anthropic é https://api.deepseek.com/anthropic. Os modelos atuais listados são deepseek-v4-flash e deepseek-v4-pro, enquanto deepseek-chat e deepseek-reasoner aparecem como nomes legados com aposentadoria programada para 24 de julho de 2026.

Resumo rápido

• 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.
• Autenticação: Authorization: Bearer ${DEEPSEEK_API_KEY}.
• Endpoint principal: POST /chat/completions.
• Recursos importantes: Thinking Mode, JSON Output, Tool Calls, streaming, Context Caching e suporte a formato Anthropic.
• Cuidado importante: deepseek-chat e deepseek-reasoner são nomes antigos; para novos projetos, prefira os modelos V4 atuais.

O que é a DeepSeek API?

A DeepSeek API é a interface programática usada para enviar prompts, mensagens, instruções, ferramentas e configurações a modelos da DeepSeek. Em vez de abrir uma interface de chat no navegador, você chama a API a partir do seu backend e recebe uma resposta estruturada para usar no seu produto.

A diferença prática é simples: a interface de chat serve para uso manual; a API serve para integração. Com a API, você pode criar um assistente dentro de um SaaS, classificar tickets, resumir documentos, gerar respostas para atendimento, extrair dados em JSON, acionar ferramentas externas, criar agentes de código ou processar grandes volumes de tarefas.

A documentação oficial informa que, ao alterar a configuração do cliente, é possível usar SDKs compatíveis com OpenAI ou Anthropic para acessar a DeepSeek API. Isso reduz bastante a curva de aprendizado para quem já usa chat.completions, messages, model, stream, tools e response_format.

Onde encontrar o DeepSeek API Docs oficial?

O DeepSeek API Docs oficial é a documentação mantida pela própria DeepSeek. Ela cobre Quick Start, Models & Pricing, Token Usage, Rate Limit, Error Codes, API Guides, API Reference, News, FAQ e Change Log. Essa documentação deve ser sempre a fonte principal para confirmar preços, modelos, parâmetros e mudanças recentes.

Este artigo não substitui a documentação oficial. Ele organiza as informações essenciais em português brasileiro e adiciona contexto prático para quem está implementando a API em projetos reais. A recomendação é usar este guia para entender o fluxo e consultar o DeepSeek API Docs oficial antes de publicar qualquer integração em produção.

DeepSeek API: visão geral técnica

Segundo a documentação oficial consultada em 10 de maio de 2026, estes são os pontos técnicos mais importantes para começar:

Item	Valor atual	Observação
Base URL OpenAI-compatible	https://api.deepseek.com	Use com OpenAI SDK ou clientes compatíveis.
Base URL Anthropic-compatible	https://api.deepseek.com/anthropic	Use com SDKs e ferramentas compatíveis com Anthropic.
Autenticação	Bearer Auth	A chave deve ser enviada no header Authorization.
Endpoint de chat	POST /chat/completions	Endpoint principal para conversas.
Modelos atuais	deepseek-v4-flash, deepseek-v4-pro	Modelos recomendados para novas integrações.
Context length	1M tokens	Conforme tabela oficial de modelos e preços.
Max output	384K tokens	Limite máximo informado na tabela oficial.
Recursos	JSON Output, Tool Calls, Thinking Mode, streaming, Context Caching	Nem todo recurso deve ser usado em todos os casos.
Preços	Por 1M tokens	Revise a página oficial antes de produção.
Modelos antigos	deepseek-chat, deepseek-reasoner	Devem ser aposentados em 24 de julho de 2026.

A página oficial de Models & Pricing informa que os preços são listados por 1 milhão de tokens, que a cobrança considera tokens de entrada e saída, e que os preços podem mudar; por isso, a própria DeepSeek recomenda revisar a página de preços regularmente.

Como criar uma DeepSeek API key

Para usar a API, você precisa criar uma DeepSeek API key na plataforma da DeepSeek. A referência oficial da API informa que é necessário criar uma chave antes de usar a DeepSeek API, e que a autenticação usa Bearer Auth.

Passo a passo recomendado:

1. Acesse a plataforma da DeepSeek.
2. Faça login ou crie uma conta.
3. Vá até a área de API keys.
4. Gere uma nova chave.
5. Salve a chave como variável de ambiente.
6. Use a chave apenas no backend.
7. Nunca exponha a chave no frontend.

Exemplo de variável de ambiente:

export DEEPSEEK_API_KEY="sua-chave-aqui"

Em produção, use um gerenciador de segredos, como o secret manager da sua nuvem, Vault, Doppler, Infisical ou a solução nativa da sua plataforma.

Boas práticas de segurança:

• Não coloque a API key no navegador.
• Não envie a chave para o frontend.
• Não publique a chave no GitHub.
• Não registre a chave em logs.
• Não inclua a chave em mensagens de erro.
• Use variáveis de ambiente.
• Separe chaves de desenvolvimento, staging e produção.
• Rotacione a chave imediatamente se houver vazamento.

Primeira chamada na DeepSeek API com cURL

O jeito mais rápido de testar a DeepSeek API é usar curl. O exemplo abaixo usa o formato OpenAI-compatible, o endpoint /chat/completions, autenticação Bearer e o modelo deepseek-v4-flash.

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

A documentação oficial mostra a mesma estrutura básica: URL base, header Content-Type, header Authorization: Bearer, corpo JSON com model, messages, opção de thinking, reasoning_effort e stream.

Para um primeiro teste, stream: false é mais simples. Para interfaces de chat, stream: true costuma melhorar a percepção de velocidade, porque a resposta pode aparecer em partes enquanto o modelo gera tokens.

Como usar DeepSeek API com Python

A DeepSeek API pode ser usada com o OpenAI SDK em Python alterando o base_url para https://api.deepseek.com. A documentação oficial mostra esse padrão no Quick Start.

Instale o SDK:

pip install openai

Exemplo em Python:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {
            "role": "system",
            "content": "Você é um especialista em APIs para desenvolvedores brasileiros."
        },
        {
            "role": "user",
            "content": "Crie uma checklist curta para integrar a DeepSeek API em produção."
        },
    ],
    reasoning_effort="high",
    extra_body={
        "thinking": {
            "type": "enabled"
        }
    },
    stream=False,
)

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

O que cada parte faz:

• api_key: lê a chave da variável de ambiente.
• base_url: direciona o OpenAI SDK para a DeepSeek API.
• model: escolhe o modelo.
• messages: envia o histórico da conversa.
• reasoning_effort: controla o esforço de raciocínio quando Thinking Mode está ativo.
• extra_body: envia parâmetros específicos aceitos pela DeepSeek.
• stream: define se a resposta será recebida completa ou em partes.

Para tarefas simples e de alto volume, considere deepseek-v4-flash. Para raciocínio, coding, agentes e problemas mais complexos, teste deepseek-v4-pro.

Como usar DeepSeek API com Node.js ou TypeScript

No Node.js, você também pode usar o pacote openai e alterar baseURL.

Instalação:

npm install openai

Exemplo:

import OpenAI from "openai";

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

async function main() {
  const completion = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages: [
      {
        role: "system",
        content: "Você responde de forma clara e prática."
      },
      {
        role: "user",
        content: "Liste 5 boas práticas para usar LLMs em um SaaS."
      }
    ],
    thinking: { type: "disabled" },
    stream: false,
  });

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

main().catch(console.error);

A lógica é parecida com Python: configurar apiKey, trocar o baseURL, escolher o model e enviar messages. A documentação oficial também apresenta exemplo em Node.js usando o OpenAI SDK com baseURL: 'https://api.deepseek.com'.

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

A escolha do modelo deve considerar custo, latência, qualidade e complexidade da tarefa. Segundo a página oficial de lançamento do DeepSeek V4, o deepseek-v4-pro é descrito como o modelo mais forte, com foco em agentes, coding e raciocínio; o deepseek-v4-flash é apresentado como opção rápida, eficiente e econômica.

Critério	deepseek-v4-flash	deepseek-v4-pro
Custo	Mais econômico	Mais caro, mas com desconto oficial até a data informada pela DeepSeek
Velocidade	Melhor para alto volume e baixa latência	Melhor para tarefas complexas, com maior custo/latência
Qualidade	Boa para tarefas gerais	Melhor para raciocínio, coding e agentes
Tarefas indicadas	Chat simples, classificação, resumo, extração, suporte interno	Agentes, programação, análise técnica, workflows longos
Volume	Indicado para escala	Use quando qualidade compensa o custo
Raciocínio/coding/agents	Funciona, mas deve ser testado	Melhor escolha inicial para tarefas difíceis

Para produção, o ideal é testar os dois modelos com seus próprios dados. Use métricas como taxa de acerto, custo por tarefa, latência média, taxa de erro, satisfação do usuário e necessidade de retry.

DeepSeek API Pricing: como entender custos e tokens

Segundo a documentação oficial consultada em 10 de maio de 2026, os preços da DeepSeek API são listados por 1 milhão de tokens. Token é a unidade usada para processar texto e calcular cobrança. A DeepSeek informa que a despesa é calculada como número de tokens multiplicado pelo preço, e que os valores são deduzidos do saldo da conta.

Tabela oficial consultada em 10 de maio de 2026:

Modelo	Input cache hit / 1M tokens	Input cache miss / 1M tokens	Output / 1M tokens
deepseek-v4-flash	US$ 0.0028	US$ 0.14	US$ 0.28
deepseek-v4-pro	US$ 0.003625 com desconto	US$ 0.435 com desconto	US$ 0.87 com desconto

A documentação oficial informa que o preço de cache hit de entrada foi reduzido para 1/10 do preço de lançamento a partir de 26 de abril de 2026, 12:15 UTC, e que o desconto de 75% do deepseek-v4-pro foi estendido até 31 de maio de 2026, 15:59 UTC. Como preços podem mudar, revise a página oficial antes de produção.

Conceitos importantes:

• Tokens de entrada: texto enviado no prompt, mensagens, instruções e contexto.
• Tokens de saída: texto gerado pelo modelo.
• Cache hit: parte da entrada reutilizada pelo Context Caching.
• Cache miss: parte da entrada processada sem acerto de cache.
• Output tokens: tokens efetivamente gerados na resposta.

Exemplo simples de estimativa:

Custo aproximado =
(tokens de entrada sem cache / 1.000.000 × preço input cache miss)
+ (tokens de entrada com cache / 1.000.000 × preço input cache hit)
+ (tokens de saída / 1.000.000 × preço output)

Exemplo hipotético com deepseek-v4-flash:

Entrada sem cache: 100.000 tokens
Entrada com cache: 400.000 tokens
Saída: 50.000 tokens

Custo ≈
(100.000 / 1.000.000 × 0.14)
+ (400.000 / 1.000.000 × 0.0028)
+ (50.000 / 1.000.000 × 0.28)

Custo ≈ 0.014 + 0.00112 + 0.014 = US$ 0.02912

Este é apenas um exemplo de cálculo. O valor real depende do modelo, do cache, do volume de saída, de descontos vigentes e da tabela oficial no momento do uso.

Thinking Mode na DeepSeek API

O DeepSeek Thinking Mode permite que o modelo use raciocínio antes de gerar a resposta final. Segundo a documentação oficial, o Thinking Mode é controlado pelo parâmetro thinking e pelo reasoning_effort; no formato OpenAI, o toggle usa {"thinking": {"type": "enabled"}} ou {"thinking": {"type": "disabled"}}, e o esforço aceita high ou max. A documentação também informa que o Thinking Mode é habilitado por padrão.

Use Thinking Mode quando:

• a tarefa exige raciocínio matemático;
• o usuário pede análise técnica;
• o agente precisa tomar decisões em múltiplas etapas;
• a tarefa envolve código;
• a resposta precisa ser mais robusta que rápida.

Desative Thinking Mode quando:

• a tarefa é simples;
• o custo precisa ser mínimo;
• a latência é prioridade;
• você só precisa classificar, resumir ou extrair dados simples;
• o output precisa ser curto e previsível.

Exemplo Python com Thinking Mode:

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Analise este bug e proponha uma correção."}
    ],
    reasoning_effort="high",
    extra_body={
        "thinking": {
            "type": "enabled"
        }
    }
)

A documentação oficial alerta que, em Thinking Mode, parâmetros como temperature, top_p, presence_penalty e frequency_penalty não são suportados; por compatibilidade, eles podem não gerar erro, mas também não terão efeito.

JSON Output na DeepSeek API

O DeepSeek JSON Output é usado quando você precisa que o modelo retorne uma string JSON válida. Isso é importante para extração de dados, classificação, integração com bancos de dados, respostas estruturadas e automações.

A documentação oficial informa três cuidados principais: definir response_format como {"type": "json_object"}, incluir a palavra “json” no prompt, fornecer exemplo do formato desejado e configurar max_tokens de forma suficiente para evitar truncamento.

Exemplo:

import json
import os
from openai import OpenAI

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

messages = [
    {
        "role": "system",
        "content": """
Você extrai dados de textos comerciais.
Responda sempre em json válido no formato:
{
  "empresa": "string",
  "problema": "string",
  "prioridade": "baixa|media|alta"
}
"""
    },
    {
        "role": "user",
        "content": "A empresa Alfa precisa corrigir uma falha crítica no checkout."
    }
]

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    response_format={"type": "json_object"},
    max_tokens=300,
)

data = json.loads(response.choices[0].message.content)
print(data)

Mesmo usando JSON Output, valide o resultado no backend. Não confie cegamente em dados gerados por modelo. Use validação de schema, tratamento de exceções e fallback.

Tool Calls / Function Calling

Tool Calls permitem que o modelo solicite a chamada de uma função externa. A função não é executada pelo modelo. O modelo apenas retorna o nome da função e argumentos; sua aplicação valida esses argumentos, executa a função real e envia o resultado de volta ao modelo. A documentação oficial deixa claro que a funcionalidade da função precisa ser fornecida pelo usuário; o modelo não executa funções específicas sozinho.

Exemplo simplificado:

tools = [
    {
        "type": "function",
        "function": {
            "name": "buscar_pedido",
            "description": "Busca o status de um pedido pelo ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "pedido_id": {
                        "type": "string",
                        "description": "ID do pedido"
                    }
                },
                "required": ["pedido_id"]
            }
        }
    }
]

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

message = response.choices[0].message
print(message.tool_calls)

Boas práticas com Tool Calls:

• Valide os argumentos antes de executar qualquer função.
• Nunca execute comandos perigosos diretamente.
• Use allowlist de funções permitidas.
• Defina schemas claros.
• Trate erros de ferramentas.
• Registre chamadas de forma segura, sem dados sensíveis.
• Implemente timeout e retry.
• Retorne resultados objetivos para o modelo.

A API Reference informa que ferramentas são declaradas no parâmetro tools, que apenas funções são suportadas como tool nesse formato, e que os argumentos gerados pelo modelo devem ser validados porque podem não ser JSON válido ou podem incluir parâmetros não definidos no schema.

A DeepSeek também documenta um strict mode em beta para Tool Calls. Para usá-lo, a documentação orienta usar base_url="https://api.deepseek.com/beta" e definir strict: true em todas as funções. Como é beta, valide cuidadosamente antes de depender disso em produção.

Streaming responses

Streaming é útil quando você quer mostrar a resposta progressivamente, como em uma interface de chat. Em vez de aguardar a resposta completa, a aplicação recebe partes da resposta à medida que o modelo gera tokens.

A API Reference informa que, quando stream está habilitado, deltas parciais são enviados como Server-Sent Events, e o stream termina com data: [DONE].

Exemplo simples em Python:

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "user", "content": "Explique streaming em APIs de IA."}
    ],
    stream=True,
    extra_body={
        "thinking": {
            "type": "disabled"
        }
    }
)

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

Use streaming quando:

• a resposta pode ser longa;
• a interface é conversacional;
• a percepção de velocidade importa;
• você quer reduzir sensação de espera.

Evite streaming quando:

• você precisa validar JSON completo;
• a resposta será processada internamente;
• a tarefa é curta;
• o backend precisa fazer pós-processamento antes de exibir.

A FAQ oficial explica que a API usa stream=false por padrão e que streaming pode melhorar a interatividade porque exibe tokens incrementalmente.

Erros comuns da DeepSeek API e como resolver

A documentação oficial lista os principais códigos de erro da DeepSeek API e suas causas. Estes são os casos mais importantes para produção:

HTTP code	Causa provável	Solução prática
400	Formato inválido no corpo da requisição	Revise JSON, messages, model, tools, thinking e campos obrigatórios.
401	Falha de autenticação	Verifique a API key e o header Authorization: Bearer.
402	Saldo insuficiente	Verifique o billing e faça top-up se necessário.
422	Parâmetros inválidos	Confira nomes de parâmetros, tipos, modelo e compatibilidade.
429	Rate limit atingido	Reduza concorrência, implemente fila e retry com backoff.
500	Erro interno do servidor	Tente novamente após breve espera e registre o incidente.
503	Servidor sobrecarregado	Aguarde, faça retry com backoff e use fallback se necessário.

Para aplicações críticas, não trate todos os erros da mesma forma. Um 401 exige correção de credenciais. Um 402 exige saldo. Um 429 exige controle de concorrência. Um 500 ou 503 exige retry, fallback ou degradação temporária.

Rate limits, filas e retry com backoff

A documentação oficial informa que a DeepSeek API limita dinamicamente a concorrência do usuário conforme a carga do servidor. Quando o limite de concorrência é atingido, a API retorna HTTP 429.

Em produção, implemente:

• fila de requisições;
• limite de concorrência por usuário;
• limite de concorrência global;
• retry com exponential backoff;
• jitter para evitar picos sincronizados;
• timeout;
• fallback para outro provedor, se a tarefa for crítica;
• métricas de taxa de erro;
• alertas para 429, 500 e 503.

Exemplo conceitual de backoff:

Tentativa 1: aguardar 1s
Tentativa 2: aguardar 2s
Tentativa 3: aguardar 4s
Tentativa 4: aguardar 8s
Depois: falhar com mensagem segura ou usar fallback

A FAQ oficial também informa que o rate limit exposto por conta é ajustado dinamicamente conforme pressão de tráfego e uso histórico de curto prazo, e que a DeepSeek não oferece aumento individual desse limite dinâmico no momento documentado.

Migração de deepseek-chat e deepseek-reasoner para modelos atuais

Este é um ponto essencial para SEO e para implementação correta. Muitos tutoriais antigos ainda usam deepseek-chat e deepseek-reasoner. Isso acontece porque, em 2025, esses nomes eram usados com frequência para DeepSeek-V3 e DeepSeek-R1. Por exemplo, um tutorial em português da DataCamp atualizado em 11 de fevereiro de 2025 ainda ensinava model="deepseek-chat" e mencionava deepseek-reasoner.

Segundo a documentação oficial consultada em 10 de maio de 2026, os modelos atuais são deepseek-v4-flash e deepseek-v4-pro. A documentação informa que deepseek-chat e deepseek-reasoner serão aposentados em 24 de julho de 2026 e, por compatibilidade, correspondem aos modos non-thinking e thinking de deepseek-v4-flash.

Como atualizar código antigo:

Antes:

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=messages
)

Depois, para tarefa simples:

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

Antes:

response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=messages
)

Depois, para raciocínio:

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    reasoning_effort="high",
    extra_body={
        "thinking": {
            "type": "enabled"
        }
    }
)

Para novos projetos, evite começar com nomes legados. Use os modelos V4, teste os modos de raciocínio e monitore custo, latência e qualidade.

DeepSeek API vs APIs compatíveis com OpenAI

A DeepSeek API é compatível com o formato OpenAI em pontos importantes, mas isso não significa que tudo seja idêntico. A documentação oficial indica compatibilidade de formato, mas modelos, parâmetros, recursos e comportamento podem variar.

Critério	DeepSeek API	APIs compatíveis com OpenAI em geral
Base URL	https://api.deepseek.com	Varia por provedor
SDK	Pode usar OpenAI SDK com base_url alterado	Normalmente usa SDK do provedor ou OpenAI SDK
Nomes dos modelos	deepseek-v4-flash, deepseek-v4-pro	Varia conforme o provedor
Thinking Mode	Suporte com thinking e reasoning_effort	Nem sempre existe
JSON Output	Suportado via response_format	Frequentemente suportado, mas pode variar
Tool Calls	Suportado	Varia por provedor
Context Caching	Ativado por padrão na DeepSeek API	Depende do provedor
Custos	Por 1M tokens, com cache hit/miss	Depende do provedor
Cuidados	Nomes legados, parâmetros específicos, rate limit dinâmico	Compatibilidade não garante equivalência total

O melhor caminho é tratar a compatibilidade como facilidade de integração, não como garantia de comportamento idêntico.

Context Caching na DeepSeek API

O Context Caching ajuda a reduzir custo quando requisições reutilizam prefixos de contexto. Segundo a documentação oficial, a tecnologia de cache em disco da DeepSeek API fica habilitada por padrão para todos os usuários, sem necessidade de modificar o código.

A ideia é simples: se várias requisições reutilizam uma parte inicial do prompt, do system message ou de um documento longo, essa parte pode ter cache hit. A resposta da API inclui campos em usage para indicar prompt_cache_hit_tokens e prompt_cache_miss_tokens, permitindo analisar quanto da entrada usou cache.

Use Context Caching a seu favor:

• mantenha instruções estáveis no começo do prompt;
• coloque documentos longos antes das perguntas variáveis;
• evite mudar desnecessariamente o system prompt;
• monitore prompt_cache_hit_tokens;
• compare custo com e sem reutilização de contexto.

A documentação também informa que o cache funciona em regime de “best-effort”, sem garantia de 100% de hit rate, e que caches podem ser limpos automaticamente após algumas horas ou dias.

Anthropic API format com DeepSeek

Além do formato OpenAI-compatible, a DeepSeek documenta suporte ao formato Anthropic API. O base_url nesse caso é https://api.deepseek.com/anthropic.

Exemplo básico com Python:

pip install anthropic

import anthropic

client = anthropic.Anthropic(
    api_key="sua-chave-aqui",
    base_url="https://api.deepseek.com/anthropic"
)

message = client.messages.create(
    model="deepseek-v4-pro",
    max_tokens=1000,
    system="Você é um assistente técnico.",
    messages=[
        {
            "role": "user",
            "content": "Explique quando usar deepseek-v4-pro."
        }
    ]
)

print(message.content)

Use esse formato quando sua stack, ferramenta de agente ou workflow já segue o ecossistema Anthropic. Para a maioria das integrações comuns com OpenAI SDK, o formato OpenAI-compatible tende a ser o caminho mais direto.

Boas práticas para produção

Antes de colocar a DeepSeek API em produção, trate a integração como um serviço crítico. Modelos de IA podem gerar respostas incorretas, respostas incompletas, JSON truncado, argumentos inválidos de tools e custos inesperados.

Checklist de produção:

• Guarde a API key apenas no backend.
• Use variáveis de ambiente ou secret manager.
• Não registre prompts sensíveis em logs brutos.
• Remova dados pessoais quando possível.
• Defina max_tokens.
• Use timeout.
• Implemente retry com backoff.
• Trate 429, 500 e 503.
• Monitore custo por endpoint, usuário e tarefa.
• Valide JSON com schema.
• Valide argumentos de Tool Calls.
• Use fallback para fluxos críticos.
• Use cache quando fizer sentido.
• Teste com dados reais e casos extremos.
• Versione prompts.
• Separe prompts por ambiente.
• Registre modelo, latência, tokens e erro.
• Revise preços e modelos regularmente.
• Acompanhe o Change Log e News oficiais.

Também é recomendável criar limites internos por usuário. Mesmo que o provedor cobre por tokens, o seu produto deve ter políticas próprias de uso, cotas e proteção contra abuso.

Exemplo de arquitetura para usar DeepSeek API em um SaaS

Uma arquitetura segura para usar a DeepSeek API em um SaaS pode seguir este fluxo:

Frontend
  ↓
Backend da sua aplicação
  ↓
Validação de entrada e autenticação do usuário
  ↓
Construção do prompt
  ↓
DeepSeek API
  ↓
Validação da resposta
  ↓
Persistência, auditoria ou pós-processamento
  ↓
Resposta ao usuário

O frontend nunca deve chamar a DeepSeek API diretamente, porque isso exporia sua API key. O backend deve controlar autenticação, autorização, limites de uso, logs seguros, validação de entrada, validação de saída e tratamento de erros.

Em um SaaS, você pode criar camadas adicionais:

• Prompt service: monta prompts por caso de uso.
• LLM gateway: centraliza chamadas para DeepSeek e outros provedores.
• Cost monitor: mede custo por cliente.
• Moderation layer: aplica regras de segurança.
• Evaluation layer: mede qualidade das respostas.
• Fallback layer: troca de provedor se houver indisponibilidade.

Checklist final antes de publicar sua integração

Antes de publicar:

• A API key está fora do frontend?
• O endpoint usa autenticação do seu próprio sistema?
• Existe limite de uso por usuário?
• O modelo foi escolhido com base em testes reais?
• deepseek-chat e deepseek-reasoner foram substituídos?
• O custo foi estimado com tokens reais?
• max_tokens está configurado?
• JSON Output está sendo validado?
• Tool Calls têm validação de argumentos?
• Há retry com backoff?
• Há tratamento para 400, 401, 402, 422, 429, 500 e 503?
• O log remove dados sensíveis?
• Existe monitoramento de latência e custo?
• Existe fallback para fluxos críticos?
• A equipe sabe onde consultar o DeepSeek API Docs oficial?

FAQ sobre DeepSeek API Docs

Conclusão

A melhor forma de usar a DeepSeek API é começar pela documentação oficial, criar uma API key, testar uma chamada simples com cURL, implementar com Python ou Node.js, escolher entre deepseek-v4-flash e deepseek-v4-pro, validar JSON e Tool Calls, monitorar custos e tratar erros corretamente.

Para projetos novos, não comece com deepseek-chat ou deepseek-reasoner sem entender o status desses nomes. Segundo a documentação oficial consultada em 10 de maio de 2026, os modelos recomendados para novas integrações são deepseek-v4-flash e deepseek-v4-pro, enquanto os nomes legados têm aposentadoria programada para 24 de julho de 2026.

Use este guia como ponto de partida, mas revise sempre o DeepSeek API Docs oficial antes de publicar ou alterar uma integração em produção.