OpenAI SDK with DeepSeek: guia prático em Python e Node.js

Última verificação: 10 de maio de 2026

Sim, você pode usar OpenAI SDK with DeepSeek em Python e Node.js/TypeScript. Na prática, o OpenAI SDK funciona como uma biblioteca cliente, enquanto a DeepSeek atua como provedora do modelo. As mudanças principais são: usar uma chave da DeepSeek, configurar base_url ou baseURL para https://api.deepseek.com, escolher um modelo DeepSeek atual e enviar a requisição pelo endpoint de Chat Completions. A documentação oficial da DeepSeek afirma que a API usa um formato compatível com OpenAI/Anthropic e mostra exemplos com OpenAI SDK em Python e Node.js.

Isso não significa que a DeepSeek seja da OpenAI, nem que todos os endpoints, parâmetros ou recursos específicos da OpenAI funcionem automaticamente com DeepSeek. O ponto correto é: a DeepSeek oferece uma API compatível o suficiente para você reutilizar o pacote openai em vários cenários, principalmente com client.chat.completions.create.

---

Resposta rápida

Item	Configuração recomendada
Python	base_url="https://api.deepseek.com"
Node.js/TypeScript	baseURL: "https://api.deepseek.com"
Variável de ambiente	DEEPSEEK_API_KEY
Endpoint	Chat Completions
Método comum	client.chat.completions.create(...)
Modelos atuais	deepseek-v4-flash e deepseek-v4-pro
Segurança	Nunca exponha a chave no frontend
Streaming	Use stream=True em Python ou stream: true em Node.js
JSON Output	Use response_format={"type": "json_object"}
Tool Calls	Suportado com funções, validação e execução no backend

Na documentação atual, a DeepSeek lista deepseek-v4-flash e deepseek-v4-pro como modelos principais e informa que deepseek-chat e deepseek-reasoner serão descontinuados em 24 de julho de 2026.

---

O que significa usar OpenAI SDK com DeepSeek?

Usar OpenAI SDK com DeepSeek significa reaproveitar o pacote openai como cliente HTTP para conversar com a API da DeepSeek. Em vez de apontar para a API da OpenAI, você troca a URL base para https://api.deepseek.com e usa uma chave criada na plataforma da DeepSeek.

A ideia é simples:

OpenAI SDK  →  cliente
DeepSeek API →  provedor do modelo
DeepSeek model → deepseek-v4-flash ou deepseek-v4-pro

Essa distinção é importante porque muita gente confunde “usar OpenAI SDK” com “usar modelos da OpenAI”. Não é isso. O SDK é só a biblioteca. O modelo chamado na requisição será o modelo DeepSeek informado no campo model.

Também é importante não misturar credenciais. Não use OPENAI_API_KEY no endpoint da DeepSeek, nem use DEEPSEEK_API_KEY no endpoint da OpenAI. Mantenha variáveis separadas para evitar requisições enviadas ao provedor errado.

---

O que muda ao migrar de OpenAI para DeepSeek?

Área	OpenAI padrão	DeepSeek via OpenAI SDK
Pacote Python	openai	openai
Pacote Node.js	openai	openai
API key	OPENAI_API_KEY	DEEPSEEK_API_KEY
Base URL	Padrão do SDK	https://api.deepseek.com
Modelo	Ex.: modelos OpenAI	deepseek-v4-flash ou deepseek-v4-pro
Endpoint recomendado	Depende do caso	Chat Completions
Python	api_key, base_url	api_key, base_url
Node.js/TypeScript	apiKey, baseURL	apiKey, baseURL
Streaming	Suportado	Suportado via Chat Completions
JSON Output	Depende do modelo/API	Suportado com json_object
Tool Calls	Suportado	Suportado com validação no backend
Custos	Tabela OpenAI	Tabela DeepSeek
Rate limits	Política OpenAI	Limite dinâmico de concorrência na DeepSeek
Segurança	Server-side	Server-side obrigatório

A DeepSeek documenta /chat/completions como endpoint de criação de resposta para conversa e lista parâmetros como messages, model, thinking, reasoning_effort, response_format, stream, tools e tool_choice.

---

Pré-requisitos

Antes de implementar OpenAI SDK with DeepSeek, você precisa de:

• Conta na DeepSeek Platform.
• Uma DeepSeek API key.
• Python 3.9+ para o exemplo Python.
• Node.js moderno para JavaScript/TypeScript.
• Ambiente backend, não frontend.
• Editor de código e terminal.
• Pacote openai.
• dotenv em desenvolvimento local ou secret manager em produção.

A documentação da OpenAI informa que a biblioteca Python funciona a partir de aplicações Python 3.9+ e pode ser instalada com pip install openai. Para JavaScript server-side, a documentação orienta instalar o SDK com npm install openai.

---

Instalação

Python

pip install openai python-dotenv

Node.js / TypeScript

npm install openai dotenv

Arquivo .env

DEEPSEEK_API_KEY=sua_chave_aqui

Nunca faça commit do arquivo .env. Em produção, prefira um secret manager, variáveis de ambiente protegidas no provedor de deploy ou um cofre de segredos. A chave deve ser usada somente no backend.

---

Exemplo Python: OpenAI SDK with DeepSeek

Crie um arquivo chamado deepseek_python.py:

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(
    api_key=os.environ["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 objetivo."
        },
        {
            "role": "user",
            "content": "Explique em 3 bullets como usar OpenAI SDK com DeepSeek."
        },
    ],
    stream=False,
    extra_body={
        "thinking": {
            "type": "disabled"
        }
    },
)

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

Execute:

python deepseek_python.py

O que cada parte faz:

Trecho	Função
load_dotenv()	Carrega a variável DEEPSEEK_API_KEY do arquivo .env em desenvolvimento local
OpenAI(...)	Cria o cliente usando o pacote openai
api_key	Usa a chave da DeepSeek, não da OpenAI
base_url	Redireciona o SDK para a API da DeepSeek
model	Define o modelo DeepSeek
messages	Envia o histórico da conversa
stream=False	Retorna a resposta completa de uma vez
extra_body	Permite enviar parâmetros específicos aceitos pela DeepSeek, como thinking

A documentação oficial da DeepSeek mostra o uso do OpenAI SDK em Python com base_url="https://api.deepseek.com" e client.chat.completions.create(...).

---

Exemplo Node.js/TypeScript

Crie um arquivo deepseek-node.mjs:

import OpenAI from "openai";
import "dotenv/config";

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ê é um assistente técnico claro e objetivo.",
      },
      {
        role: "user",
        content: "Explique em 3 bullets como usar OpenAI SDK com DeepSeek.",
      },
    ],
    stream: false,
    thinking: {
      type: "disabled",
    },
  });

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

main().catch((error) => {
  console.error("Erro ao chamar DeepSeek:", error);
  process.exit(1);
});

Execute:

node deepseek-node.mjs

A diferença de nome dos parâmetros é importante:

Linguagem	API key	Base URL
Python	api_key	base_url
Node.js/TypeScript	apiKey	baseURL

No TypeScript, dependendo da versão do pacote openai, o campo thinking pode ainda não estar refletido nos tipos do SDK. Uma forma segura é restringir o cast ao objeto de requisição da DeepSeek, em vez de espalhar as any por todo o projeto:

import OpenAI from "openai";
import "dotenv/config";

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

type DeepSeekChatRequest =
  Parameters<typeof client.chat.completions.create>[0] & {
    thinking?: {
      type: "enabled" | "disabled";
    };
    reasoning_effort?: "high" | "max";
  };

const request: DeepSeekChatRequest = {
  model: "deepseek-v4-flash",
  messages: [
    {
      role: "user",
      content: "Gere um checklist curto para testar a integração DeepSeek.",
    },
  ],
  stream: false,
  thinking: {
    type: "disabled",
  },
};

const completion = await client.chat.completions.create(request as any);

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

A documentação da DeepSeek também mostra um exemplo Node.js com baseURL: "https://api.deepseek.com", apiKey: process.env.DEEPSEEK_API_KEY e chat.completions.create(...).

---

Qual modelo DeepSeek usar?

Modelo	Melhor para	Observação
deepseek-v4-flash	Chats rápidos, classificação, extração, resumo, MVPs, tarefas de menor latência	Boa escolha inicial para custo e velocidade
deepseek-v4-pro	Raciocínio, código complexo, agentes, análise, tarefas multi-etapas	Melhor quando qualidade e raciocínio importam mais
deepseek-chat	Alias legado	Não use como padrão em código novo
deepseek-reasoner	Alias legado	Não use como padrão em código novo

A página de modelos e preços da DeepSeek lista deepseek-v4-flash e deepseek-v4-pro, com suporte a modos thinking e non-thinking, contexto de 1M, saída máxima de 384K, JSON Output e Tool Calls para ambos. A mesma página informa que deepseek-chat e deepseek-reasoner serão descontinuados no futuro e correspondem, por compatibilidade, a modos do deepseek-v4-flash.

Como nomes de modelos e preços podem mudar, valide sempre a documentação oficial antes de publicar, versionar ou colocar uma integração em produção.

---

Chat Completions vs Responses API

Ao usar modelos da OpenAI, a documentação atual da OpenAI mostra exemplos modernos com client.responses.create(...) no quickstart. Porém, para DeepSeek, a documentação oficial trabalha com Chat Completions, usando /chat/completions e client.chat.completions.create(...).

Portanto, para OpenAI SDK with DeepSeek, a recomendação prática é:

client.chat.completions.create(...)

e não:

client.responses.create(...)

Não copie exemplos da Responses API e assuma que funcionarão com DeepSeek. Use Chat Completions, a menos que a documentação oficial da DeepSeek confirme explicitamente outro endpoint ou fluxo.

---

Thinking Mode vs Non-Thinking Mode

A DeepSeek oferece dois modos principais:

Modo	Quando usar
Non-thinking	Chat simples, extração, classificação, respostas rápidas, JSON mais previsível
Thinking	Problemas complexos, análise, raciocínio, programação, agentes e tarefas multi-etapas

Na documentação atual, o Thinking Mode tem toggle {"thinking": {"type": "enabled/disabled"}}, o padrão é enabled, e o controle de esforço usa reasoning_effort com valores high ou max. Ao usar OpenAI SDK, a DeepSeek orienta passar thinking dentro de extra_body em Python. A documentação também informa que, em thinking mode, parâmetros como temperature, top_p, presence_penalty e frequency_penalty não têm efeito.

Python com thinking disabled

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {
            "role": "user",
            "content": "Resuma este texto em uma frase."
        }
    ],
    extra_body={
        "thinking": {
            "type": "disabled"
        }
    },
)

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

Python com thinking enabled e reasoning_effort

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

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

Para tarefas simples, comece com thinking: disabled. Para raciocínio mais pesado, use deepseek-v4-pro com thinking habilitado.

---

Streaming

Streaming é útil quando você quer mostrar a resposta token por token, como em uma interface de chat. Em vez de aguardar a resposta inteira, seu backend envia partes conforme elas chegam.

A referência de Chat Completion da DeepSeek informa que, quando stream está ativo, deltas parciais são enviados por Server-Sent Events até o marcador final data: [DONE].

Streaming em Python

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

for chunk in stream:
    if not chunk.choices:
        continue

    delta = chunk.choices[0].delta
    content = getattr(delta, "content", None)

    if content:
        print(content, end="", flush=True)

Streaming em Node.js

const stream = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    {
      role: "user",
      content: "Explique streaming em APIs de LLM em termos simples.",
    },
  ],
  stream: true,
  thinking: {
    type: "disabled",
  },
});

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

Boas práticas para streaming:

• Trate chunks vazios.
• Configure timeout.
• Use keep-alive quando apropriado.
• Tenha reconexão ou fallback na interface.
• Separe streaming do processamento final de dados sensíveis.
• Não assuma que cada chunk terá content.

---

JSON Output

Use DeepSeek JSON Output quando você precisa de uma resposta estruturada para parsing no backend, por exemplo: extração de dados, classificação, normalização de campos, criação de objetos para banco de dados ou integração com automações.

A documentação da DeepSeek orienta definir response_format como {"type": "json_object"}, incluir a palavra “json” no prompt, fornecer um exemplo do formato desejado e configurar max_tokens de forma razoável para evitar truncamento. A documentação também alerta que o conteúdo pode ocasionalmente vir vazio ao usar JSON Output.

Exemplo Python com JSON Output

import json
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

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

system_prompt = """
Você extrai dados de tickets de suporte.
Responda somente em json válido.

Formato esperado:
{
  "categoria": "billing | technical | account | other",
  "prioridade": "low | medium | high",
  "resumo": "string curta"
}
"""

user_prompt = """
O cliente diz que foi cobrado duas vezes no mesmo mês e quer reembolso.
"""

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_prompt},
    ],
    response_format={
        "type": "json_object"
    },
    max_tokens=500,
    extra_body={
        "thinking": {
            "type": "disabled"
        }
    },
)

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

print(data)

Mesmo com JSON Output, valide o JSON no backend antes de usar. Para produção, combine json.loads, validação de schema, tratamento de erro e logs sem dados sensíveis.

---

Tool Calls / Function Calling

Tool Calls permitem que o modelo solicite a execução de uma função externa. O ponto essencial: o modelo não executa a função sozinho. Ele retorna uma intenção estruturada, e o seu backend decide se executa, valida argumentos, chama a função real e devolve o resultado ao modelo.

A documentação da DeepSeek mostra esse fluxo: o modelo retorna a chamada da função, o usuário/aplicação executa a função e depois envia o resultado de volta com role: "tool" e tool_call_id. A própria documentação reforça que a função precisa ser fornecida pelo usuário, pois o modelo não executa funções específicas por conta própria.

Exemplo Python simplificado

import json
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

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

tools = [
    {
        "type": "function",
        "function": {
            "name": "consultar_status_pedido",
            "description": "Consulta o status de um pedido pelo ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "ID do pedido, por exemplo PED-12345."
                    }
                },
                "required": ["order_id"],
                "additionalProperties": False
            },
        },
    }
]

def consultar_status_pedido(order_id: str) -> dict:
    if not isinstance(order_id, str):
        raise ValueError("order_id deve ser string")

    if not order_id.startswith("PED-"):
        raise ValueError("order_id inválido")

    return {
        "order_id": order_id,
        "status": "em_transito",
        "previsao_entrega": "2026-05-15"
    }

messages = [
    {
        "role": "user",
        "content": "Qual é o status do pedido PED-12345?"
    }
]

first_response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
    tool_choice="auto",
    extra_body={
        "thinking": {
            "type": "disabled"
        }
    },
)

assistant_message = first_response.choices[0].message
messages.append(assistant_message.model_dump(exclude_none=True))

if assistant_message.tool_calls:
    for tool_call in assistant_message.tool_calls:
        function_name = tool_call.function.name

        if function_name != "consultar_status_pedido":
            raise ValueError(f"Função não permitida: {function_name}")

        args = json.loads(tool_call.function.arguments)
        order_id = args.get("order_id")

        result = consultar_status_pedido(order_id)

        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })

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

    print(final_response.choices[0].message.content)
else:
    print(assistant_message.content)

Sobre strict mode beta

A DeepSeek documenta um strict mode em beta para Tool Calls. Para usá-lo, a documentação orienta trocar a base URL para https://api.deepseek.com/beta, definir strict: true nas funções e garantir que o JSON Schema seja compatível com as regras aceitas. Use esse modo somente depois de testar seu schema, pois ele não deve ser o padrão para iniciantes.

---

Custos, tokens, cache e limites

A DeepSeek cobra com base em tokens de entrada e saída. A página oficial de preços informa valores por 1 milhão de tokens e explica que o custo é calculado pela quantidade de tokens multiplicada pelo preço aplicável. A mesma página recomenda verificar regularmente os preços, pois eles podem variar.

Até a verificação de 10 de maio de 2026, a documentação listava:

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	US$ 0.435	US$ 0.87

A página também indicava desconto temporário de 75% para deepseek-v4-pro até 31 de maio de 2026, 15:59 UTC. Como isso é temporal, revise antes de publicar ou atualizar o artigo.

Context caching

A DeepSeek informa que o Context Caching em disco é ativado por padrão para todos os usuários. Quando requisições posteriores compartilham prefixos com requisições anteriores, partes sobrepostas podem ser lidas do cache. A resposta inclui campos como prompt_cache_hit_tokens e prompt_cache_miss_tokens na seção usage.

Na prática:

• Cache hit tende a reduzir custo de entrada.
• Cache miss usa o preço normal de entrada.
• Prompts longos e repetidos podem se beneficiar mais.
• O cache é best-effort, não uma garantia absoluta.
• Monitore tokens, latência e custo por usuário.

Rate limits

A DeepSeek informa que limita dinamicamente a concorrência com base na carga do servidor. Ao atingir o limite, a API retorna HTTP 429.

Boas práticas:

• Retry com exponential backoff.
• Jitter para evitar novas rajadas.
• Fila para cargas altas.
• Circuit breaker.
• Fallback provider quando o SLA exigir.
• Logs de latência, tokens e status code.

---

Erros comuns e como corrigir

Erro	Causa provável	Como corrigir
400 Invalid Format	Corpo da requisição inválido	Revise JSON, messages, model, tools e estrutura do payload
401 Authentication Fails	API key errada	Verifique DEEPSEEK_API_KEY e se a chave pertence à DeepSeek
402 Insufficient Balance	Saldo insuficiente	Adicione créditos na plataforma
422 Invalid Parameters	Parâmetro inválido	Confira campos como model, thinking, response_format e tools
429 Rate Limit Reached	Muitas requisições ou concorrência alta	Use backoff, fila, limite por usuário e fallback
500 Server Error	Erro no servidor	Tente novamente com backoff
503 Server Overloaded	Alta carga no serviço	Aguarde, tente novamente e use fallback se necessário
Requisição indo para OpenAI	Faltou base_url ou baseURL	Configure https://api.deepseek.com
Usar base_url em Node.js	Nome errado do parâmetro	Use baseURL
Usar baseURL em Python	Nome errado do parâmetro	Use base_url
Model ID errado	Modelo antigo ou inexistente	Use deepseek-v4-flash ou deepseek-v4-pro
JSON inválido	Prompt fraco ou sem response_format	Use JSON Output, exemplo de schema e validação
JSON truncado	max_tokens baixo	Aumente max_tokens e valide finish_reason
Chave exposta no browser	Chamada feita no frontend	Mova a chamada para backend
.env ausente no deploy	Variável não configurada	Configure secrets no provedor
Timeout	Resposta longa ou thinking mode	Ajuste timeout, streaming e limites
Tool call sem validação	Confiança excessiva nos argumentos	Valide função, schema e permissões antes de executar

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

---

Boas práticas de produção

Para colocar DeepSeek API com OpenAI SDK em produção:

• Faça chamadas apenas server-side.
• Proteja DEEPSEEK_API_KEY em secret manager.
• Nunca registre API keys em logs.
• Valide entrada do usuário.
• Defina max_tokens.
• Use rate limiting por usuário, IP ou tenant.
• Aplique retries com exponential backoff e jitter.
• Configure timeouts.
• Use circuit breaker para falhas repetidas.
• Monitore tokens de entrada e saída.
• Monitore cache hit/cache miss.
• Valide JSON antes de usar.
• Valide argumentos de Tool Calls.
• Não execute comandos sensíveis diretamente a partir de Tool Calls.
• Teste prompts reais, não apenas exemplos pequenos.
• Tenha fallback para cargas críticas.
• Revise compliance antes de enviar dados pessoais sensíveis.

---

Quando não usar DeepSeek via OpenAI SDK?

Evite ou revise com cuidado quando:

• Você trabalha com dados pessoais sensíveis sem revisão de compliance.
• Precisa de um endpoint específico da OpenAI que não está documentado pela DeepSeek.
• Seu SLA é rígido e você não tem fallback.
• A aplicação exige latência previsível em 100% dos casos.
• Você não tem observabilidade de custo, tokens e erros.
• A aplicação toma decisões financeiras, jurídicas, médicas ou de segurança sem supervisão humana.
• Você pretende chamar a API diretamente do navegador.

Nesses casos, a solução não é apenas trocar modelo. É desenhar arquitetura, fallback, segurança, auditoria e validação.

---

Checklist final

Antes de publicar ou subir para produção:

• API key da DeepSeek criada.
• DEEPSEEK_API_KEY configurada.
• base_url correto no Python.
• baseURL correto no Node.js/TypeScript.
• Modelo atual definido.
• Chat Completions usado corretamente.
• Secrets protegidos.
• Streaming testado, se necessário.
• JSON Output validado.
• Tool Calls validadas.
• Erros 400/401/402/422/429/500/503 tratados.
• Custo e tokens monitorados.
• Fallback definido para cenários críticos.
• Documentação oficial revisada antes do deploy.

---

FAQ