Como usar a API DeepSeek-V3.1 — um tutorial prático para desenvolvedores

O DeepSeek-V3.1 é o mais recente modelo de raciocínio híbrido da DeepSeek, que suporta tanto um modo de bate-papo rápido "sem pensar" quanto um modo mais deliberado "pensando/raciocinando", oferece contexto longo (até 128K), saídas estruturadas e chamadas de função, e pode ser acessado diretamente pela API compatível com OpenAI da DeepSeek, por meio de um endpoint compatível com Anthropic ou pela CometAPI. Abaixo, explico o que é o modelo, os destaques de benchmark e custo, os recursos avançados (chamadas de função, saídas JSON, modo de raciocínio) e, em seguida, apresento exemplos concretos de código de ponta a ponta: chamadas REST diretas do DeepSeek (curl / Node / Python), uso do cliente Anthropic e chamadas via CometAPI.

O que é o DeepSeek-V3.1 e o que há de novo nesta versão?

DeepSeek-V3.1 é o lançamento mais recente da família DeepSeek V3: uma linha de modelos de linguagem de grande porte, de alta capacidade e com uma mistura de especialistas, que inclui uma design de inferência híbrida com dois “modos” operacionais — um rápido bate-papo sem pensar modo e um pensando / raciocinando Modo que pode expor rastros de estilo de cadeia de pensamento para tarefas de raciocínio mais complexas e uso de agentes/ferramentas. A versão enfatiza latência de "pensamento" mais rápida, recursos aprimorados de ferramentas/agentes e processamento de contexto mais longo para fluxos de trabalho em escala de documentos.

Principais conclusões práticas:

• Dois modos de operação: deepseek-chat para rendimento e custo, deepseek-reasoner (um modelo de raciocínio) quando você quer traços de cadeia de pensamento ou maior fidelidade de raciocínio.
• Melhorias no agente/ferramenta de tratamento e no tokenizador/contexto para documentos longos.
• Comprimento do contexto: até ~128 mil tokens (permite documentos longos, bases de código, logs).

Avanço de referência

O DeepSeek-V3.1 demonstrou melhorias significativas em desafios de codificação do mundo real. Na avaliação SWE-bench Verified, que mede a frequência com que o modelo corrige problemas do GitHub para garantir a aprovação em testes unitários, a V3.1 alcançou uma taxa de sucesso de 66%, em comparação com 45% para a V3-0324 e a R1. Na versão multilíngue, a V3.1 resolveu 54.5% dos problemas, quase o dobro da taxa de sucesso de aproximadamente 30% das outras versões. Na avaliação Terminal-Bench, que testa se o modelo consegue concluir tarefas com sucesso em um ambiente Linux ativo, o DeepSeek-V3.1 obteve sucesso em 31% das tarefas, em comparação com 13% e 6% para as outras versões, respectivamente. Essas melhorias demonstram que o DeepSeek-V3.1 é mais confiável na execução de código e na operação em ambientes de ferramentas do mundo real.

Os benchmarks de recuperação de informações também favorecem o DeepSeek-V3.1 em navegação, busca e resposta a perguntas. Na avaliação do BrowseComp, que requer navegação e extração de respostas de uma página da web, o V3.1 respondeu corretamente a 30% das perguntas, em comparação com 9% do R1. Na versão em chinês, o DeepSeek-V3.1 atingiu 49% de precisão, em comparação com 36% do R1. No Hard Language Exam (HLE), o V3.1 superou ligeiramente o R1, alcançando 30% a 25% de precisão, respectivamente. Em tarefas de busca profunda, como o xbench-DeepSearch, que requer a síntese de informações entre fontes, o V3.1 obteve 71% contra 1% do R55. O DeepSeek-V3.1 também demonstrou uma pequena, mas consistente vantagem em benchmarks como (raciocínio estruturado), SimpleQA (resposta a perguntas factuais) e Seal0 (resposta a perguntas específicas de domínio). No geral, a V3.1 superou significativamente a R1 em recuperação de informações e resposta a perguntas simples.

Em termos de eficiência de raciocínio, os resultados do uso de tokens demonstram sua eficácia. No AIME 2025 (um exame de matemática difícil), o V3.1-Think obteve precisão comparável ou ligeiramente superior ao R1 (88.4% contra 87.5%), mas utilizou aproximadamente 30% menos tokens. No GPQA Diamond (um exame de pós-graduação multidomínio), os dois modelos foram quase iguais (80.1% contra 81.0%), mas o V3.1 utilizou quase metade dos tokens do R1. No benchmark LiveCodeBench, que avalia o raciocínio de código, o V3.1 não foi apenas mais preciso (74.8% contra 73.3%), mas também mais conciso. Isso demonstra que o V3.1-Think é capaz de fornecer raciocínio detalhado, evitando verbosidade.

No geral, a V3.1 representa um salto geracional significativo em comparação com a V3-0324. Comparada à R1, a V3.1 obteve maior precisão em quase todos os benchmarks e foi mais eficaz em tarefas de raciocínio complexas. O único benchmark em que a R1 se equiparou foi o GPQA, mas com quase o dobro do custo.

Como obtenho uma chave de API e configuro uma conta de desenvolvimento?

Passo 1: Cadastre-se e crie uma conta

1. Acesse o portal do desenvolvedor do DeepSeek (documentação/console do DeepSeek). Crie uma conta com seu e-mail ou provedor de SSO.
2. Conclua todas as verificações de identidade ou configurações de cobrança exigidas pelo portal.

Etapa 2: crie uma chave de API

1. No painel, vá para chaves de API → Criar chave. Dê um nome à sua chave (por exemplo, dev-local-01).
2. Copie a chave e armazene-a em um gerenciador de segredos seguro (veja as práticas recomendadas de produção abaixo).

Dica: Alguns gateways e roteadores de terceiros (por exemplo, CometAPI) permitem que você use uma única chave de gateway para acessar modelos DeepSeek por meio deles — isso é útil para redundância de vários provedores (consulte o API DeepSeek V3.1 seção).

Como configuro meu ambiente de desenvolvimento (Linux/macOS/Windows)?

Esta é uma configuração simples e reproduzível para Python e Node.js que funciona para DeepSeek (endpoints compatíveis com OpenAI), CometAPI e Anthropic.

Pré-requisitos

• Python 3.10+ (recomendado), pip, virtualenv.
• Node.js 18+ e npm/yarn.
• curl (para testes rápidos).

Ambiente Python (passo a passo)

1. Crie um diretório de projeto:

mkdir deepseek-demo && cd deepseek-demo
python -m venv .venv
source .venv/bin/activate   # macOS / Linux

# .venv\Scripts\activate    # Windows PowerShell

2. Instalar pacotes mínimos:

pip install --upgrade pip
pip install requests
# Optional: install an OpenAI-compatible client if you prefer one:

pip install openai

3. Salve sua chave de API em variáveis ​​de ambiente (nunca faça commit):

export DEEPSEEK_KEY="sk_live_xxx"
export CometAPI_KEY="or_xxx"
export ANTHROPIC_KEY="anthropic_xxx"

(Uso do Windows PowerShell $env:DEEPSEEK_KEY = "…")

Ambiente de nó (passo a passo)

1. Inicializar:

mkdir deepseek-node && cd deepseek-node
npm init -y
npm install node-fetch dotenv

2. Crie uma .env arquivo:

DEEPSEEK_KEY=sk_live_xxx
CometAPI_KEY=or_xxx
ANTHROPIC_KEY=anthropic_xxx

Como chamar o DeepSeek-V3.1 diretamente — exemplos de código passo a passo?

A API do DeepSeek é compatível com OpenAI. Abaixo estão copy-paste exemplos: curl, Python (estilo de solicitações e SDK openai) e Node.

Etapa 1: Exemplo de curl simples

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat-v3.1",
    "messages": [
      {"role":"system","content":"You are a concise engineering assistant."},
      {"role":"user","content":"Give a 5-step secure deployment checklist for a Django app."}
    ],
    "max_tokens": 400,
    "temperature": 0.0,
    "reasoning_enabled": true
  }'

Observações: reasoning_enabled Alterna o modo de reflexão (sinalizador do fornecedor). O nome exato do sinalizador pode variar de acordo com o fornecedor — consulte a documentação do modelo.

Etapa 2: Python (solicitações) com telemetria simples

import os, requests, time, json

API_KEY = os.environ
URL = "https://api.deepseek.com/v1/chat/completions"

payload = {
  "model": "deepseek-chat-v3.1",
  "messages": [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Refactor this Flask function to be testable: ..."}
  ],
  "max_tokens": 600,
  "temperature": 0.1,
  "reasoning_enabled": True
}

start = time.time()
r = requests.post(URL, headers={
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}, json=payload, timeout=60)

elapsed = time.time() - start
print("Status:", r.status_code, "Elapsed:", elapsed)
data = r.json()
print(json.dumps(data, indent=2))

CometAPI: acesso totalmente gratuito ao DeepSeek V3.1

Para desenvolvedores que buscam acesso imediato sem registro, a CometAPI oferece uma alternativa atraente ao DeepSeek V3.1 (nome do modelo: deepseek-v3-1-250821; deepseek-v3.1). Este serviço de gateway agrega vários modelos de IA por meio de uma API unificada, fornecendo acesso ao DeepSeek e outros benefícios, incluindo failover automático, análise de uso e faturamento simplificado entre provedores.

Primeiro, crie uma conta CometAPI em https://www.cometapi.com/— todo o processo leva apenas dois minutos e requer apenas a verificação do endereço de e-mail. Após o login, gere uma nova chave na seção "Chave de API". https://www.cometapi.com/ oferece créditos gratuitos para novas contas e um desconto de 20% no preço oficial da API.

A implementação técnica requer alterações mínimas no código. Basta alterar o ponto de extremidade da sua API de uma URL direta do DeepSeek para o gateway CometAPI.

Nota: A API suporta streaming (stream: true), max_tokens, temperatura, sequências de parada e recursos de chamada de função semelhantes a outras APIs compatíveis com OpenAI.

Como posso chamar o DeepSeek usando SDKs Anthropic?

O DeepSeek fornece um ponto de extremidade compatível com o Anthropic para que você possa reutilizar os SDKs do Anthropic ou as ferramentas do Claude Code apontando o SDK para https://api.deepseek.com/anthropic e definindo o nome do modelo para deepseek-chat (ou deepseek-reasoner onde suportado).

Invocar o modelo DeepSeek via API Anthropic

Instale o SDK Anthropic: pip install anthropic. Configure seu ambiente:

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic  
export ANTHROPIC_API_KEY=YOUR_DEEPSEEK_KEY

Criar uma mensagem:

import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="deepseek-chat",
max_tokens=1000,
system="You are a helpful assistant.",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hi, how are you?"
}
]
}
]
)
print(message.content)

Use DeepSeek no Claude Code

Instalação: npm install -g @anthropic-ai/claude-code. Configure seu ambiente:

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${YOUR_API_KEY}
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat

Entre no diretório do projeto e execute o código Claude:

cd my-project  
claude

Use DeepSeek no Claude Code via CometAPI

O CometAPI suporta o Claude Code. Após a instalação, ao configurar o ambiente, basta substituir a URL base por https://www.cometapi.com/console/ e a chave pela Chave do CometAPI para usar o modelo DeepSeek do CometAPI no Claude Code.

# Navigate to your project folder cd your-project-folder 

# Set environment variables (replace sk-... with your actual token) 
export ANTHROPIC_AUTH_TOKEN=sk-... 
export ANTHROPIC_BASE_URL=https://www.cometapi.com/console/ 
# Start Claude Code 

claude

Observações:

• DeepSeek mapeia nomes de modelos antrópicos não suportados para deepseek-chat.
• A camada de compatibilidade antrópica suporta system, messages, temperature, streaming, sequências de parada e matrizes de pensamento.

Quais são as melhores práticas concretas de produção (segurança, custo, confiabilidade)?

Abaixo estão os padrões de produção recomendados que se aplicam ao DeepSeek ou a qualquer uso de LLM de alto volume.

Segredos e identidade

• Armazene chaves de API em um gerenciador secreto (não use .env em produção). Gire as chaves regularmente e crie chaves por serviço com privilégios mínimos.
• Use projetos/contas separados para desenvolvimento/preparação/produção.

Limites de taxa e novas tentativas

• Executar recuo exponencial em HTTP 429/5xx com jitter. Limite de tentativas de repetição (ex.: 3 tentativas).
• Use chaves de idempotência para solicitações que podem ser repetidas.

Exemplo Python — nova tentativa com recuo

import time, random, requests

def post_with_retries(url, headers, payload, attempts=3):
    for i in range(attempts):
        r = requests.post(url, json=payload, headers=headers, timeout=60)
        if r.status_code == 200:
            return r.json()
        if r.status_code in (429, 502, 503, 504):
            backoff = (2 ** i) + random.random()
            time.sleep(backoff)
            continue
        r.raise_for_status()
    raise RuntimeError("Retries exhausted")

Gestão de custos

• Limitar max_tokens e evite solicitar acidentalmente saídas enormes.
• Respostas do modelo de cache quando apropriado (especialmente para prompts repetidos). O DeepSeek distingue explicitamente o acerto do erro de cache na precificação — o cache economiza dinheiro.
• Uso deepseek-chat para pequenas respostas de rotina; reserve deepseek-reasoner para casos que realmente precisam de CoT (é mais caro).

Observabilidade e registro

• Registre apenas metadados sobre solicitações em texto simples (hashes de prompt, contagens de tokens, latências). Evite registrar dados completos do usuário ou conteúdo confidencial. Armazene IDs de solicitação/resposta para suporte e reconciliação de faturamento.
• Rastreie o uso de tokens por solicitação e exponha orçamentos/alertas sobre custos.

Controles de segurança e alucinação

• Uso saídas de ferramentas e validadores determinísticos para qualquer coisa crítica à segurança (financeira, legal, médica).
• Para saídas estruturadas, use response_format+Esquema JSON e valide saídas antes de tomar ações irreversíveis.

Padrões de implantação

• Execute chamadas de modelo de um processo de trabalho dedicado para controlar a simultaneidade e o enfileiramento.
• Descarregue tarefas pesadas para trabalhadores assíncronos (tarefas do Celery, Fargate, tarefas do Cloud Run) e responda aos usuários com indicadores de progresso.
• Para necessidades extremas de latência/taxa de transferência, considere os SLAs do provedor e se você deve se hospedar por conta própria ou usar aceleradores do provedor.

Nota final

O DeepSeek-V3.1 é um modelo híbrido e pragmático, projetado tanto para bate-papo rápido quanto para tarefas complexas de agente. Seu formato de API compatível com OpenAI simplifica a migração para muitos projetos, enquanto as camadas de compatibilidade com Anthropic e CometAPI o tornam flexível para ecossistemas existentes. Benchmarks e relatórios da comunidade mostram compensações promissoras de custo/desempenho — mas, como acontece com qualquer novo modelo, valide-o em suas cargas de trabalho reais (prompts, chamadas de função, verificações de segurança, latência) antes da implementação completa em produção.

No CometAPI, você pode executá-lo com segurança e interagir com ele por meio de uma API compatível com OpenAI ou de uma interface amigável. recreio, sem limites de taxa.

👉 Implante o DeepSeek-V3.1 no CometAPI agora!

Por que usar o CometAPI?

• Multiplexação de provedores: trocar de provedor sem reescrever código.
• Faturamento/métricas unificadas: se você rotear vários modelos por meio do CometAPI, obterá uma única superfície de integração.
• Metadados do modelo: visualizar comprimento do contexto e parâmetros ativos por variante do modelo.