Como usar o OpenAI SDK com DeepSeek: migração em Node.js e Python

Documentação reconferida em 23 de agosto de 2026. O SDK OpenAI pode acessar Chat Completions e a Responses API da DeepSeek em https://api.deepseek.com. As duas interfaces documentam deepseek-v4-flash, deepseek-v4-pro e deepseek-v4-flash-vision-exp, mas usam schemas, eventos e limites diferentes. O Vision Exp recebe imagens; os baselines autenticados desta página continuam datados de 29/07 e 05/08 e não foram repetidos após os lançamentos posteriores.

Baseline autenticado da interface compatível com OpenAI

Em 29 de julho de 2026, a interface Chat Completions compatível com OpenAI respondeu HTTP 200 ao usar a base https://api.deepseek.com, o modelo deepseek-v4-flash e Thinking desativado. O retorno incluiu choices, finish_reason, model e usage nos campos esperados.

Limite honesto: esta auditoria validou o contrato HTTP compatível, mas não instalou nem executou versões específicas dos pacotes openai para Node.js ou Python. Portanto, os exemplos de SDK permanecem baseados na documentação e devem ser testados no seu lockfile antes do deploy.

O resultado do baseline foi: modelo retornado V4 Flash, finish_reason=stop, 31 tokens de entrada, 24 de saída e 55 no total. Consulte a evidência autenticada e a documentação oficial.

Guia independente: este site não é a DeepSeek e não é endossado por ela. Os exemplos chamam https://api.deepseek.com diretamente. Crie e administre sua chave na plataforma oficial da DeepSeek.

O que muda na migração

Configuração	Origem	DeepSeek
Chave	OPENAI_API_KEY	DEEPSEEK_API_KEY
Base URL	Padrão do cliente original	https://api.deepseek.com
Chat Completions	client.chat.completions.create()	Flash, Pro e Vision Exp
Responses API	client.responses.create()	Flash, Pro e Vision Exp
Modelo econômico para texto	Depende do provedor original	deepseek-v4-flash
Modelo para tarefas complexas	Depende do provedor original	deepseek-v4-pro
Modelo com imagem	Depende do provedor original	deepseek-v4-flash-vision-exp — experimental
Raciocínio	Varia por API e modelo	Thinking ativado por padrão; controle conforme a interface

As versões atuais são DeepSeek-V4-Flash-0731, DeepSeek-V4-Pro-0813 e DeepSeek-V4-Flash-Vision-Exp. Os IDs enviados no campo model são os três nomes em minúsculas da tabela acima. Todos publicam contexto de 1 milhão de tokens e saída máxima de 384 mil tokens dentro da mesma janela.

Aliases antigos: o prazo anunciado para deepseek-chat e deepseek-reasoner já passou. Não use esses nomes em código novo. A observação autenticada deste site sobre seu comportamento em 29/07/2026 continua sendo uma fotografia datada, não suporte garantido.

Antes de trocar a URL: identifique a operação usada

Se o aplicativo usa client.chat.completions.create(), mantenha o formato messages e escolha Flash ou Pro para texto, ou Vision Exp para texto com imagem. Se usa client.responses.create(), a DeepSeek oferece compatibilidade direta com os mesmos três modelos. A troca não é automática: compare cada campo, tipo de conteúdo e ferramenta com a matriz oficial.

A implementação Responses da DeepSeek é stateless: previous_response_id, conversation e store não oferecem estado hospedado. Imagens são suportadas com Vision Exp por input_image, usando image_url ou file_id; arquivos genéricos não são suportados. A Files API atual armazena imagens, não PDFs, áudio, embeddings ou bases vetoriais.

Papéis de mensagem: em Chat Completions, use system, user, assistant e tool; não envie developer. Na Responses API, developer é aceito, mas tratado como user, não como system. Para instrução de sistema em Responses, prefira instructions ou uma mensagem system.

Parâmetros não suportados podem ser ignorados silenciosamente. Em Thinking Mode, temperature, top_p, presence_penalty e frequency_penalty não produzem efeito. Ferramentas solicitadas pelo modelo não autorizam nem executam automaticamente ações no backend.

Fonte primária: compatibilidade oficial da DeepSeek Responses API.

Migração mínima em Node.js

Use Node.js 20 LTS ou superior no servidor; não exponha a chave em JavaScript do navegador. O SDK OpenAI bloqueia uso em browsers por padrão justamente para reduzir o risco de credenciais públicas.

mkdir deepseek-sdk-demo
cd deepseek-sdk-demo
npm init -y
npm install openai
export DEEPSEEK_API_KEY="sua_chave_aqui"
export DEEPSEEK_MODEL="deepseek-v4-flash"

Salve como app.mjs:

import OpenAI from "openai";

if (!process.env.DEEPSEEK_API_KEY) {
  throw new Error("Defina DEEPSEEK_API_KEY no ambiente do servidor.");
}

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

const completion = await client.chat.completions.create({
  model: process.env.DEEPSEEK_MODEL ?? "deepseek-v4-flash",
  messages: [
    { role: "system", content: "Responda em português do Brasil." },
    { role: "user", content: "Explique a diferença entre cache hit e miss." },
  ],
  thinking: { type: "disabled" },
  max_tokens: 500,
});

console.log(completion.choices[0]?.message?.content);
console.log("Usage:", completion.usage);

Execute com node app.mjs. A separação entre DEEPSEEK_API_KEY e OPENAI_API_KEY evita enviar uma chave ao fornecedor errado. Também é recomendável guardar modelo e URL em configuração de servidor, mas aceitar somente valores previamente autorizados.

E se o TypeScript não reconhecer thinking?

O SDK é tipado conforme a API da OpenAI, enquanto thinking é uma extensão do corpo da DeepSeek. Uma versão do pacote pode enviá-lo em runtime sem incluí-lo nos tipos. Restrinja a exceção à linha do parâmetro, em vez de converter toda a resposta para any:

const completion = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "Responda em uma frase." }],
  // @ts-expect-error Campo específico documentado pela DeepSeek.
  thinking: { type: "disabled" },
});

A documentação do SDK explica que campos adicionais são encaminhados ao corpo, embora o compilador possa exigir uma anotação. Fixe uma versão testada do pacote, execute um teste de integração após upgrades e valide a resposta real; compatibilidade de transporte não substitui testes de comportamento.

Escolher e controlar Thinking Mode

Thinking vem habilitado por padrão. Para respostas rápidas, classificação, extração ou transformação simples, desative-o explicitamente depois de validar a qualidade:

thinking: { type: "disabled" }

Para raciocínio complexo, habilite o modo e defina o esforço documentado:

const completion = await client.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [{ role: "user", content: "Analise este problema passo a passo." }],
  thinking: { type: "enabled" },
  reasoning_effort: "high",
});

const message = completion.choices[0].message;
console.log("Resposta final:", message.content);
// reasoning_content é separado de content.

Os valores de esforço publicados são low, high e max; high é o padrão. Por compatibilidade, medium e xhigh são mapeados para high. Use o menor esforço que atenda ao critério de qualidade da tarefa. Mostre content ao usuário e preserve reasoning_content quando o mesmo fluxo inclui chamadas de ferramenta.

Exemplo secundário em Python

python -m pip install openai
export DEEPSEEK_API_KEY="sua_chave_aqui"

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Responda em português."},
        {"role": "user", "content": "Crie um checklist de teste de API."},
    ],
    max_tokens=500,
    extra_body={"thinking": {"type": "disabled"}},
)

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

No SDK Python, a documentação da DeepSeek coloca o parâmetro específico thinking em extra_body. Isso preserva a compatibilidade do cliente tipado e envia o campo no JSON final.

Responses API com imagem

Use deepseek-v4-flash-vision-exp e um bloco input_image com image_url ou file_id. Não envie os dois campos no mesmo bloco. O upload da Files API aceita imagens; sem prazo de expiração, o arquivo permanece armazenado até ser excluído.

Veja o exemplo Python oficial e valide o comportamento com a versão do pacote fixada no seu projeto.

Streaming com o SDK

const stream = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "Escreva um resumo curto." }],
  thinking: { type: "disabled" },
  stream: true,
  stream_options: { include_usage: true },
});

let usage = null;
for await (const chunk of stream) {
  const text = chunk.choices?.[0]?.delta?.content;
  if (text) process.stdout.write(text);
  if (chunk.usage) usage = chunk.usage;
}
console.log("\nUsage:", usage);

Com include_usage, um chunk extra antes de [DONE] traz o consumo total e um array choices vazio. Se você escreveu seu próprio parser SSE, aceite comentários : keep-alive. A DeepSeek também pode enviar linhas vazias em respostas não streaming enquanto a conexão permanece aberta.

Tool calls com Thinking: loop completo

O exemplo abaixo oferece uma função local. Ele valida os argumentos antes de executar e adiciona a mensagem de assistente completa ao histórico. Essa última etapa preserva reasoning_content no turno de ferramenta, como exige o guia oficial do Thinking Mode.

const tools = [{
  type: "function",
  function: {
    name: "consultar_estoque",
    description: "Consulta a quantidade disponível de um SKU.",
    parameters: {
      type: "object",
      properties: { sku: { type: "string" } },
      required: ["sku"],
      additionalProperties: false,
    },
  },
}];

async function consultarEstoque({ sku }) {
  if (!/^[A-Z0-9-]{1,30}$/.test(sku)) throw new Error("SKU inválido");
  return { sku, quantidade: 12 }; // Troque pela consulta real do backend.
}

const messages = [
  { role: "user", content: "Há unidades do SKU NOTE-14?" },
];

let answered = false;
for (let step = 0; step < 5; step++) {
  const completion = await client.chat.completions.create({
    model: "deepseek-v4-pro",
    messages,
    tools,
    thinking: { type: "enabled" },
    reasoning_effort: "high",
  });

  const message = completion.choices[0].message;
  messages.push(message); // Inclui reasoning_content e tool_calls.

  if (!message.tool_calls?.length) {
    console.log(message.content);
    answered = true;
    break;
  }

  for (const call of message.tool_calls) {
    if (call.function.name !== "consultar_estoque") {
      throw new Error("Ferramenta não autorizada");
    }
    const args = JSON.parse(call.function.arguments);
    const result = await consultarEstoque(args);
    messages.push({
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(result),
    });
  }
}

if (!answered) throw new Error("Limite de etapas da ferramenta atingido");

O modelo pode produzir JSON inválido ou argumentos fora do schema. Valide tipos, valores, autorização do usuário e impacto da ação. Para pagamentos, exclusões ou mensagens externas, exija confirmação e idempotência. A API admite somente ferramentas do tipo função, com até 128 funções por pedido; schemas e resultados também consomem contexto.

Erros, retries e limites de concorrência

A DeepSeek documenta 400 para formato inválido, 401 para chave incorreta, 402 para saldo insuficiente, 422 para parâmetros inválidos, 429 para limite, 500 para erro do servidor e 503 para sobrecarga. Não repita automaticamente 400, 401, 402 ou 422: corrija a causa. Para 429, 500, 503 e falhas de conexão, use backoff exponencial com jitter e um número máximo de tentativas.

const request = {
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "Teste de disponibilidade." }],
  thinking: { type: "disabled" },
};

try {
  const result = await client.chat.completions.create(request);
  console.log(result.choices[0].message.content);
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error({
      status: error.status,
      requestId: error.request_id,
      message: error.message,
    });
  }
  throw error;
}

O SDK JavaScript repete por padrão, duas vezes, falhas de conexão, 408, 409, 429 e erros 5xx; maxRetries altera esse comportamento. Ajuste o timeout à rota: Thinking e contexto longo podem demorar mais que uma resposta curta. Não faça retries ilimitados, pois uma fila congestionada pode multiplicar carga e custo.

Os limites de concorrência publicados são 2.500 conexões por conta para deepseek-v4-flash, 500 para deepseek-v4-pro e 2.500 para deepseek-v4-flash-vision-exp, independentemente da quantidade de chaves. Ao excedê-los, a API retorna 429. Controle picos com fila e semáforo no aplicativo.

Tokens, cache e custo depois da migração

Preços atuais: as tarifas de pico e fora de pico estão em vigor desde 16/08/2026, às 16:00 UTC. Desde 23/08/2026, sábado e domingo inteiros, definidos pelo horário de Pequim, são cobrados como fora de pico. Custos e testes explicitamente datados antes dessa vigência não foram recalculados.

Registro histórico de 19/07/2026

Não compare fornecedores usando apenas o tamanho do texto final. Registre prompt_cache_hit_tokens, prompt_cache_miss_tokens, completion_tokens e, quando presente, reasoning_tokens. Em 19 de julho de 2026, Flash custa US$ 0,0028 por 1M tokens de input com hit, US$ 0,14 com miss e US$ 0,28 de output; Pro custa US$ 0,003625, US$ 0,435 e US$ 0,87, respectivamente.

Tarifas atuais por 1 milhão de tokens

Modelo e período	Cache hit	Cache miss	Saída
Flash / Vision — fora de pico	US$ 0,007	US$ 0,22	US$ 0,66
Flash / Vision — pico	US$ 0,014	US$ 0,44	US$ 1,32
Pro — fora de pico	US$ 0,022	US$ 0,66	US$ 1,98
Pro — pico	US$ 0,044	US$ 1,32	US$ 3,96

Imagens são convertidas em tokens conforme suas dimensões e cobradas como entrada no Vision Exp. Use o objeto usage e a faixa horária da cobrança real; não aplique as tarifas de julho a chamadas novas.

O cache em disco é habilitado por padrão e reaproveita prefixos persistidos em regime best effort. Não conte com hit em todo pedido. Veja fórmulas e código de medição no guia de DeepSeek Token Usage.

Checklist de migração e teste

1. Crie uma chave DeepSeek e guarde-a no secret manager do servidor.
2. Troque baseURL, chave e modelo sem sobrescrever a configuração OpenAI existente.
3. Identifique se o fluxo usa Chat Completions ou Responses API e valide os campos suportados antes de migrar.
4. Use somente deepseek-v4-flash ou deepseek-v4-pro.
5. Defina Thinking explicitamente por rota e remova parâmetros sem efeito.
6. Teste system prompts, JSON, streaming e ferramentas com casos reais e adversariais.
7. Valide argumentos de ferramenta e preserve a mensagem completa do assistente no loop.
8. Registre request ID, modelo, latência, status e objeto usage.
9. Configure timeout, retries limitados, fila e controle de concorrência.
10. Faça rollout gradual, compare qualidade e custo e mantenha rollback para o provedor anterior.

Compatibilidade de formato não garante equivalência de resposta. Execute um conjunto fixo de avaliações para precisão, instruções, idioma, segurança, estrutura JSON, chamadas de ferramenta e custo. Para a referência geral do endpoint, consulte nossa página da API DeepSeek; para modelos, veja o guia do DeepSeek V4.

Perguntas frequentes

Preciso trocar o pacote openai?

Não para este fluxo. Instale o SDK OpenAI e configure a base URL e a chave da DeepSeek. Os exemplos desta página usam Chat Completions; a Responses API exige validação separada dos recursos suportados.

Posso usar client.responses.create() com a URL da DeepSeek?

Sim. A documentação atual inclui deepseek-v4-flash, deepseek-v4-pro e deepseek-v4-flash-vision-exp. Imagens funcionam com Vision Exp; arquivos genéricos e estado hospedado continuam fora da matriz. O HTTP 400 observado com Pro em 05/08 antecede o Pro-0813 e permanece como resultado histórico não repetido.

deepseek-reasoner é o ID do V4 Pro?

Não. A documentação verificada antes da retirada o associava temporariamente ao V4 Flash com Thinking. Para Pro, use deepseek-v4-pro.

Por que temperature não muda a resposta?

Se Thinking estiver habilitado, temperature e top_p não têm efeito. Desative Thinking apenas quando isso fizer sentido para a tarefa.

Posso colocar a chave no frontend?

Não. Faça a chamada no backend, autentique seus usuários, aplique quotas e mantenha a chave em segredo de ambiente ou secret manager.

Posso usar imagens com o OpenAI SDK e a DeepSeek?

Sim. Use deepseek-v4-flash-vision-exp. Em Chat Completions, envie blocos image_url ou file; na Responses API, use input_image com image_url ou file_id. A Files API armazena imagens, não PDFs ou outros documentos genéricos.

Fontes oficiais

• DeepSeek: primeira chamada de API
• DeepSeek: Create Chat Completion
• DeepSeek: modelos disponíveis
• DeepSeek: Thinking Mode
• DeepSeek: Tool Calls
• DeepSeek: Rate Limit & Isolation
• OpenAI: biblioteca TypeScript e JavaScript

Fontes desta atualização: Responses API, Vision e Files API.