Blog

Como Usar a API DeepSeek V4? Guia Completo

Ashley Innocent

Ashley Innocent

24 abril 2026

Como Usar a API DeepSeek V4? Guia Completo

DeepSeek V4 foi lançado com a API ativa desde o primeiro dia. Os IDs dos modelos são deepseek-v4-pro e deepseek-v4-flash, o endpoint é compatível com OpenAI, e a URL base é https://api.deepseek.com. Isso significa que qualquer cliente que você já usa com GPT-5.5 ou outras APIs no formato OpenAI funciona com o V4 com uma simples troca da URL base.

Este guia aborda autenticação, todos os parâmetros importantes, exemplos em Python e Node, matemática no modo de raciocínio, chamada de ferramentas, streaming, e um fluxo de trabalho baseado no Apidog que mantém o custo visível enquanto você itera.

botão

Para uma visão geral do produto, veja o que é DeepSeek V4. Para o caminho sem custo, veja como usar o DeepSeek V4 gratuitamente.

TL;DR (Resumo)

Pré-requisitos

Antes da primeira requisição, prepare quatro coisas.

Exporte a chave uma vez:

export DEEPSEEK_API_KEY="sk-..."

Endpoint e autenticação

Duas URLs base cobrem dois formatos de requisição.

POST https://api.deepseek.com/v1/chat/completions    # Formato OpenAI
POST https://api.deepseek.com/anthropic/v1/messages  # Formato Anthropic

Escolha o formato compatível com OpenAI, a menos que você já tenha uma base de código no formato Anthropic. O restante deste guia usa o formato OpenAI.

A autenticação é um token Bearer no cabeçalho padrão Authorization. A requisição mínima viável:

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Explique o roteamento MoE em duas frases."}
    ]
  }'

Respostas bem-sucedidas retornam um corpo JSON com um array choices, um bloco usage detalhado em tokens de entrada e saída (e reasoning_tokens se o modo de raciocínio estiver ativado), e um id que você pode usar para rastreamento. Falhas retornam o envelope padrão OpenAI com error.code e error.message.

Parâmetros da requisição

Cada campo se correlaciona com custo ou comportamento. Aqui está o mapeamento para deepseek-v4-pro e deepseek-v4-flash.

Parâmetro Tipo Valores Notas
model string deepseek-v4-pro, deepseek-v4-flash Obrigatório.
messages array pares role/content Obrigatório. Mesmo esquema do OpenAI.
thinking_mode string non-thinking, thinking, thinking_max O padrão é non-thinking.
temperature float 0 a 2 DeepSeek recomenda 1.0.
top_p float 0 a 1 DeepSeek recomenda 1.0.
max_tokens int 1 a 131.072 Limita o comprimento da saída.
stream bool true ou false Habilita streaming SSE.
tools array Especificação de ferramenta OpenAI Para chamada de função.
tool_choice string ou objeto auto, required, none, ou ferramenta específica Controla o uso da ferramenta.
response_format objeto {"type": "json_object"} Saída em modo JSON.
seed int qualquer int Para reprodutibilidade.
presence_penalty float -2 a 2 Penaliza tópicos repetidos.
frequency_penalty float -2 a 2 Penaliza tokens repetidos.

thinking_mode é o maior fator de custo. non-thinking ignora completamente o rastreamento de raciocínio e retorna tokens aproximadamente na velocidade do V3.2. thinking habilita um bloco de raciocínio que custa tokens extras, mas melhora a precisão em código e matemática. thinking_max produz as pontuações da tabela principal da DeepSeek; ele também consome a maior quantidade de tokens e é o único modo que requer um orçamento de contexto de 384K+.

Cliente Python

O SDK oficial openai funciona com uma substituição da URL base. Todo wrapper existente compatível com OpenAI, incluindo LangChain, LlamaIndex e DSPy, também funciona.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Responda apenas em código."},
        {"role": "user", "content": "Escreva uma função Rust que faça 'debounce' de eventos."},
    ],
    extra_body={"thinking_mode": "thinking"},
    temperature=1.0,
    top_p=1.0,
    max_tokens=2048,
)

choice = response.choices[0]
print("Conteúdo:", choice.message.content)
print("Tokens de raciocínio:", response.usage.reasoning_tokens)
print("Total de tokens:", response.usage.total_tokens)

O truque do extra_body é como você passa parâmetros específicos do DeepSeek através do SDK OpenAI sem modificar a biblioteca.

Cliente Node

Mesma estrutura no Node:

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "Explique o otimizador Muon em linguagem simples." },
  ],
  thinking_mode: "thinking",
  temperature: 1.0,
  top_p: 1.0,
});

console.log(response.choices[0].message.content);
console.log("Uso:", response.usage);

O SDK Node aceita campos desconhecidos silenciosamente, então thinking_mode passa no nível superior sem extra_body.

Respostas em Streaming

Defina stream: true e itere os blocos SSE. O formato corresponde exatamente ao OpenAI.

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Transmita um ensaio de 300 palavras sobre MoE."}],
    stream=True,
    extra_body={"thinking_mode": "non-thinking"},
)

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

Os rastros de raciocínio são transmitidos separadamente quando o modo de raciocínio está ativado; o campo delta.reasoning_content os carrega e você pode exibi-los na interface ou descartá-los.

Chamada de Ferramentas

O V4 suporta o esquema padrão de chamada de ferramentas do OpenAI. Funções definidas no array tools tornam-se chamáveis, e o modelo decide quando invocá-las.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Retorna o clima atual de uma cidade.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Clima em Lagos em Celsius?"}],
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking_mode": "thinking"},
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

A partir daí, chame a função, anexe o resultado como uma mensagem role: "tool", e chame a API novamente para continuar o ciclo. O padrão é idêntico aos ciclos de uso de ferramentas do OpenAI e Anthropic.

Modo JSON

Para saída estruturada, peça JSON explicitamente e defina o formato de resposta.

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Responda com um único objeto JSON."},
        {"role": "user", "content": "Resuma esta nota de lançamento como {título, data, marcadores}: ..."},
    ],
    response_format={"type": "json_object"},
    extra_body={"thinking_mode": "non-thinking"},
)

O modo JSON força a saída de JSON válido, mas não impõe um esquema específico. Para validação de esquema, combine-o com Pydantic ou Zod no lado do cliente.

Construa a coleção no Apidog

Reproduzir requisições do terminal consome créditos e esconde a diferença entre as execuções. O fluxo de trabalho que sobrevive ao uso real:

  1. Baixe o Apidog e crie um projeto.
  2. Adicione um ambiente com {{DEEPSEEK_API_KEY}} armazenado como uma variável secreta.
  3. Salve uma requisição POST para {{BASE_URL}}/chat/completions com o cabeçalho Authorization: Bearer {{DEEPSEEK_API_KEY}}.
  4. Parametrize model e thinking_mode para que você possa fazer testes A/B entre variantes sem duplicar requisições.
  5. Use o visualizador de respostas para inspecionar usage.reasoning_tokens em cada execução. Esse é o sinal mais claro se você está pagando por um modo de raciocínio que não precisa.

Equipes que já estão usando a coleção de API GPT-5.5 correspondente no Apidog podem duplicá-la, trocar a URL base para https://api.deepseek.com/v1, trocar o ID do modelo e executar prompts de comparação entre ambos os provedores em minutos.

Tratamento de Erros

O formato segue exatamente o OpenAI. Os que você encontrará primeiro:

Código Significado Solução
400 Requisição inválida Verifique o esquema JSON, especialmente messages e tools.
401 Chave inválida Regenere em platform.deepseek.com.
402 Saldo insuficiente Recarregue a conta.
403 Modelo não permitido Verifique o escopo da chave e a ortografia do ID do modelo.
422 Parâmetro fora do intervalo max_tokens ou thinking_mode provavelmente estão incompatíveis.
429 Limite de taxa Aguarde, depois tente novamente com jitter exponencial.
500 Erro do servidor Tente novamente uma vez; se o erro persistir, verifique a página de status.
503 Sobrecarga Volte para V4-Flash ou tente novamente em 30 segundos.

Empacote as chamadas em um auxiliar de retentativa que lida com erros 429 e 5xx com recuo exponencial. Não tente novamente erros 4xx automaticamente; eles são bugs de lógica, não falhas transitórias.

Padrões de Controle de Custo

Quatro padrões mantêm os gastos previsíveis.

  1. Use V4-Flash como padrão. Mude para V4-Pro apenas para prompts onde você mediu um aumento de qualidade.
  2. Controle thinking_max com uma flag. É o modo mais caro por uma larga margem; use-o apenas quando a correção for mais importante que a latência.
  3. Limite max_tokens. A maioria das respostas se encaixa em 2.000 tokens de saída. O contexto de 1M é para entrada, não para saída.
  4. Registre usage em cada chamada. Envie as contagens de entrada, saída e raciocínio para sua pilha de observabilidade; um alerta sobre um pico repentino de tokens de raciocínio detecta prompts que se desviaram.

Migrando de modelos DeepSeek mais antigos

Os IDs mais antigos deepseek-chat e deepseek-reasoner serão descontinuados em 24 de julho de 2026. A migração requer uma linha de diferença por local de chamada; os formatos de requisição e resposta permanecem inalterados.

-  model="deepseek-chat"
+  model="deepseek-v4-pro"

Antes de ativar em produção, execute comparações A/B lado a lado no Apidog. O salto na qualidade da resposta geralmente recompensa a mudança; o prazo de descontinuação a impõe de qualquer maneira.

FAQ (Perguntas Frequentes)

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar