Lucas

Posted on Apr 24 • Originally published at apidog.com

Como Usar a API DeepSeek V4? Guia Completo

DeepSeek V4 foi lançado com suporte imediato à API. Os IDs dos modelos são deepseek-v4-pro e deepseek-v4-flash. O endpoint segue o padrão OpenAI, com URL base https://api.deepseek.com. Basta trocar a URL base para começar a usar o V4 com qualquer cliente compatível com GPT-5.5 ou OpenAI.

Experimente o Apidog hoje

Neste guia, você vai implementar autenticação, configurar parâmetros essenciais, rodar exemplos em Python e Node, ativar matemática com raciocínio, chamar ferramentas, usar streaming e montar um fluxo no Apidog para acompanhar custos enquanto testa.

Veja a visão geral em o que é DeepSeek V4 e para experimentar sem custo, confira como usar o DeepSeek V4 gratuitamente.

TL;DR (Resumo)

Endpoint OpenAI: https://api.deepseek.com/v1/chat/completions. Endpoint Anthropic: https://api.deepseek.com/anthropic.
Modelos: deepseek-v4-pro (1.6T total, 49B ativos) e deepseek-v4-flash (284B total, 13B ativos).
Contexto de 1 milhão de tokens e três modos de raciocínio: non-thinking, thinking, thinking_max.
Use temperature=1.0, top_p=1.0 como padrão (não use padrões do GPT-5.5/Claude).
IDs deepseek-chat e deepseek-reasoner expiram em 24/07/2026; migre antes disso.
Baixe o Apidog para reproduzir requisições, comparar modos de raciocínio e manter a chave protegida.

Pré-requisitos

Antes de começar, prepare:

Conta DeepSeek em platform.deepseek.com com saldo de pelo menos $2.
Chave de API com escopo de projeto.
SDK compatível com OpenAI: Python openai>=1.30.0 ou Node openai@4.x.
Cliente de API para testar requisições. Use Apidog para repetir e comparar chamadas.

Defina sua chave no ambiente:

export DEEPSEEK_API_KEY="sk-..."

Endpoint e autenticação

Dois formatos:

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

Prefira OpenAI se não tiver legado Anthropic. O padrão deste guia é OpenAI.

Envie o token Bearer no cabeçalho Authorization. Exemplo de chamada mínima:

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 incluem choices, usage detalhado e id para rastreamento. Erros seguem o padrão OpenAI.

Parâmetros da requisição

Configure cada campo para ajustar custo e comportamento:

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 principal driver de custo. Use non-thinking para performance, thinking para precisão em código/matemática, e thinking_max para máxima qualidade (usa mais tokens, requer contexto grande).

Cliente Python

O SDK openai funciona direto, só alterando a base URL:

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)

Passe parâmetros DeepSeek extras via extra_body.

Cliente Node

No Node, basta ajustar baseURL:

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);

No Node, thinking_mode pode ir direto.

Respostas em Streaming

Para streaming, use stream=True e consuma os chunks:

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)

Se usar raciocínio, monitore delta.reasoning_content.

Chamada de Ferramentas

Implemente funções conforme esquema OpenAI:

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)

Chame a função, retorne o resultado como role: "tool", e continue o ciclo.

Modo JSON

Peça saída JSON válida assim:

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"},
)

Combine com validação usando Pydantic ou Zod no cliente.

Construa a coleção no Apidog

Para controle e repetição:

Baixe o Apidog e crie um projeto.
Adicione ambiente com {{DEEPSEEK_API_KEY}} como variável secreta.
Salve requisição POST para {{BASE_URL}}/chat/completions e cabeçalho Authorization: Bearer {{DEEPSEEK_API_KEY}}.
Parametrize model e thinking_mode para testes A/B.
Use o visualizador para inspecionar usage.reasoning_tokens e evitar custos desnecessários.

Se já usa a coleção GPT-5.5 do Apidog, basta duplicar, trocar base URL/modelo e rodar comparações.

Tratamento de Erros

Principais códigos e ações:

Código	Significado	Solução
400	Requisição inválida	Verifique JSON, `messages` e `tools`.
401	Chave inválida	Regenere em platform.deepseek.com.
402	Saldo insuficiente	Recarregue a conta.
403	Modelo não permitido	Verifique escopo da chave e nome do modelo.
422	Parâmetro fora do intervalo	Confira `max_tokens` e `thinking_mode`.
429	Limite de taxa	Espere e tente novamente com jitter exponencial.
500	Erro do servidor	Tente novamente; se persistir, veja a página de status.
503	Sobrecarga	Tente V4-Flash ou aguarde 30 segundos.

Implemente retentativa para erros 429/5xx com recuo exponencial. Erros 4xx são bugs de lógica, ajuste antes de tentar novamente.

Padrões de Controle de Custo

Use V4-Flash como padrão. Só mude para V4-Pro quando comprovar aumento de qualidade.
Controle thinking_max via flag. Só ative quando precisão máxima for necessária.
Limite max_tokens. 2.000 tokens de saída bastam para a maioria dos casos.
Registre usage toda chamada. Monitore picos de tokens de raciocínio para detectar desvios de prompt.

Migrando de modelos DeepSeek mais antigos

Mude apenas o ID do modelo:

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

Compare respostas no Apidog antes de aplicar em produção.

FAQ (Perguntas Frequentes)

A API DeepSeek V4 está pronta para produção? Sim. Desde 23/04/2026, baseada na mesma infraestrutura robusta dos modelos anteriores.
O V4 suporta formato Anthropic? Sim. Use https://api.deepseek.com/anthropic/v1/messages com payload Anthropic.
Qual o contexto máximo? 1 milhão de tokens nos dois modelos; thinking_max requer pelo menos 384K.
Como contar tokens antes de enviar? Use o tokenizador OpenAI para estimar, mas confie na contagem usage da resposta para produção.
Fine-tuning via API? Não disponível via API no lançamento. Faça fine-tuning apenas via checkpoints no Hugging Face.
Existe trial/gratuito? Não há tier gratuito fixo, mas novos registros podem receber crédito de teste.

DEV Community