DeepSeek Token Usage: como medir tokens, cache e custos da API

Verificado em 19 de julho de 2026. Este guia explica como interpretar o objeto usage retornado pela API da DeepSeek, transformar tokens em custo e monitorar cache, streaming, Thinking Mode e ferramentas. Os exemplos usam os IDs documentados deepseek-v4-flash e deepseek-v4-pro.

Aviso de independência: este é um guia independente em português e não representa nem é endossado pela DeepSeek. Preços, modelos e limites podem ser alterados pelo fornecedor; confirme a tabela oficial de preços antes de definir orçamento ou cobrar clientes.

Um token não equivale de forma fixa a uma palavra. Pode representar uma palavra, parte dela, um número, pontuação ou outro símbolo. Estimativas por caracteres ajudam no planejamento, mas a medição para faturamento deve vir da resposta da API. A própria documentação ressalta que a tokenização varia; por isso, não use regras como “uma palavra é um token” em quotas financeiras.

Resumo: os campos que você precisa registrar

Campo	Significado	Uso prático
prompt_tokens	Total de tokens de entrada	Dimensionar contexto e custo do prompt
prompt_cache_hit_tokens	Entrada recuperada do cache	Aplicar o preço reduzido de cache hit
prompt_cache_miss_tokens	Entrada não recuperada do cache	Aplicar o preço de cache miss
completion_tokens	Tokens gerados na conclusão	Calcular o custo de saída
completion_tokens_details.reasoning_tokens	Parte da conclusão usada em raciocínio	Observar o impacto do Thinking Mode
total_tokens	Entrada mais conclusão	Métrica geral, não uma base única de custo

A relação documentada é prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens. Já reasoning_tokens é um detalhamento dos tokens de conclusão; não o some novamente a completion_tokens ao calcular o preço. Para cobrança, use os campos retornados, não a quantidade de caracteres visíveis na resposta.

Como ler token usage em Node.js

Instale o SDK e guarde a chave apenas no servidor:

npm install openai
export DEEPSEEK_API_KEY="sua_chave_aqui"

O exemplo desativa o Thinking Mode para deixar a demonstração curta. Em JavaScript, parâmetros adicionais compatíveis são enviados no corpo da requisição.

import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "system", content: "Responda em português, com objetividade." },
    { role: "user", content: "Explique context caching em três tópicos." },
  ],
  thinking: { type: "disabled" },
  max_tokens: 300,
});

const usage = completion.usage ?? {};
const metrics = {
  prompt_tokens: usage.prompt_tokens ?? 0,
  cache_hit: usage.prompt_cache_hit_tokens ?? 0,
  cache_miss: usage.prompt_cache_miss_tokens ?? 0,
  completion_tokens: usage.completion_tokens ?? 0,
  reasoning_tokens:
    usage.completion_tokens_details?.reasoning_tokens ?? 0,
  total_tokens: usage.total_tokens ?? 0,
};

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

Em produção, associe essas métricas ao modelo, funcionalidade, status HTTP, latência, horário e um identificador interno não pessoal. A DeepSeek aceita user_id para isolamento de segurança, cache e agendamento, mas orienta que ele não contenha informação privada.

Leitura de usage em Python

O SDK Python expõe os mesmos campos como atributos. Use valores padrão para que a coleta não quebre caso um detalhamento opcional não esteja presente:

import os
from openai import OpenAI

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": "user", "content": "Defina token em uma frase."}],
    extra_body={"thinking": {"type": "disabled"}},
)

usage = response.usage
details = getattr(usage, "completion_tokens_details", None)
metrics = {
    "prompt_tokens": usage.prompt_tokens,
    "cache_hit": getattr(usage, "prompt_cache_hit_tokens", 0) or 0,
    "cache_miss": getattr(usage, "prompt_cache_miss_tokens", 0) or 0,
    "completion_tokens": usage.completion_tokens,
    "reasoning_tokens": getattr(details, "reasoning_tokens", 0) or 0,
    "total_tokens": usage.total_tokens,
}
print(metrics)

Se o seu sistema transforma respostas em dicionários, mantenha o mesmo contrato de métricas entre Node.js e Python. Isso facilita dashboards, alertas e reconciliação financeira entre serviços.

Como receber usage em streaming

Com stream: true, os deltas de texto chegam antes do resumo de consumo. Defina stream_options.include_usage como true. A API envia um chunk adicional antes de [DONE]; nele, choices é um array vazio e usage contém a medição da requisição inteira.

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

let text = "";
let finalUsage = null;

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

console.log("\nUsage:", finalUsage);

Não encerre a coleta quando o texto terminar: o chunk de usage pode chegar depois do último delta textual. Se a conexão for interrompida antes dele, marque o custo como desconhecido ou reconcilie-o com registros do fornecedor; não invente uma contagem a partir do texto parcial.

Preços verificados e fórmula de custo

Modelo	Input: cache hit	Input: cache miss	Output
deepseek-v4-flash	US$ 0,0028 / 1M	US$ 0,14 / 1M	US$ 0,28 / 1M
deepseek-v4-pro	US$ 0,003625 / 1M	US$ 0,435 / 1M	US$ 0,87 / 1M

Valores em dólares por 1 milhão de tokens, verificados em 19 de julho de 2026 conforme a tabela oficial consultada.

custo =
  (cache_hit_tokens  / 1_000_000) * preço_cache_hit
+ (cache_miss_tokens / 1_000_000) * preço_cache_miss
+ (completion_tokens / 1_000_000) * preço_output

Exemplo exato: 90 mil hits, 10 mil misses e 4 mil tokens de saída

Para deepseek-v4-flash: (90.000 ÷ 1M × 0,0028) + (10.000 ÷ 1M × 0,14) + (4.000 ÷ 1M × 0,28) = US$ 0,002772.

Para deepseek-v4-pro: (90.000 ÷ 1M × 0,003625) + (10.000 ÷ 1M × 0,435) + (4.000 ÷ 1M × 0,87) = US$ 0,00815625.

Esses totais cobrem somente os preços da API indicados na tabela. Acrescente, quando aplicável, impostos, câmbio, infraestrutura, banco de vetores, observabilidade e outras dependências do seu produto. Para uma visão comercial separada, consulte nosso guia de preços do DeepSeek.

Função de custo em Node.js

const PRICES = {
  "deepseek-v4-flash": { hit: 0.0028, miss: 0.14, output: 0.28 },
  "deepseek-v4-pro": { hit: 0.003625, miss: 0.435, output: 0.87 },
};

function requestCost(model, usage) {
  const price = PRICES[model];
  if (!price) throw new Error(`Modelo sem preço configurado: ${model}`);

  const hit = usage.prompt_cache_hit_tokens ?? 0;
  const miss = usage.prompt_cache_miss_tokens ?? 0;
  const output = usage.completion_tokens ?? 0;

  return (
    (hit / 1_000_000) * price.hit +
    (miss / 1_000_000) * price.miss +
    (output / 1_000_000) * price.output
  );
}

console.log(requestCost("deepseek-v4-flash", completion.usage));

Mantenha a tabela de preços em configuração versionada, com data de vigência, em vez de espalhar números pelo código. Assim, uma mudança futura não altera o histórico: você calcula cada requisição com a versão de preço válida no momento em que ela ocorreu.

Cache hit e cache miss

O context caching em disco é habilitado por padrão para usuários da API e não exige um endpoint diferente. Ele reutiliza prefixos sobrepostos já persistidos. Um prompt com instruções fixas e um documento estável no início, seguido pela pergunta variável, tem mais chance de reaproveitamento que um prompt cuja ordem muda em toda chamada.

• Mantenha o system prompt e as definições de ferramentas estáveis.
• Coloque o contexto reutilizável antes da pergunta variável.
• Não reorganize ou reformate documentos sem necessidade.
• Meça a taxa real: hit ÷ prompt_tokens.
• Orce o pior caso como cache miss, pois o cache opera em best effort.

A construção pode levar alguns segundos, e entradas sem uso são removidas normalmente depois de horas ou dias. Logo, um primeiro ou segundo pedido pode não produzir hit mesmo quando há texto comum. Veja exemplos de prefixos no nosso guia de context caching.

Thinking Mode e tokens de raciocínio

O Thinking Mode é habilitado por padrão. A resposta pode trazer reasoning_content além de content, e o usage pode detalhar reasoning_tokens. Para solicitações regulares, reasoning_effort usa high por padrão; os valores documentados são high e max. Em Thinking Mode, temperature, top_p, presence_penalty e frequency_penalty não produzem efeito.

Não exiba reasoning_content como se fosse a resposta final: apresente content ao usuário. Em conversas comuns sem ferramenta, o raciocínio anterior pode ser omitido na próxima rodada. Porém, quando o modelo fez uma tool call, preserve a mensagem de assistente completa, incluindo reasoning_content, ao devolver o resultado da ferramenta. Nosso guia do Thinking Mode detalha esse fluxo.

Onde os tokens crescem sem aparecer no texto final

1. Histórico: reenviar todas as mensagens aumenta a entrada a cada rodada. Resuma estados antigos quando for seguro.
2. Ferramentas: nomes, descrições e JSON Schema entram no pedido; chamadas e resultados também passam a integrar a conversa.
3. RAG: chunks duplicados, metadados extensos e documentos irrelevantes elevam cache miss.
4. Thinking: raciocínio pode consumir parte relevante da conclusão, ainda que a resposta final seja curta.
5. JSON: schemas e exemplos grandes aumentam o prompt; limite a estrutura ao necessário.

Defina max_tokens conforme a tarefa, mas lembre que ele limita a saída, não garante gasto nem qualidade. Os modelos documentados têm contexto de 1 milhão de tokens e saída máxima de 384 mil; isso é capacidade, não uma recomendação para preencher a janela. Pré-visualize o tamanho de documentos e imponha limites por funcionalidade.

Orçamento e alertas para produção

• Calcule custo por request e agregue por usuário, cliente, rota e modelo.
• Crie alertas para aumento de cache miss, output e reasoning tokens.
• Defina tetos diários e mensais no seu aplicativo, além do saldo da plataforma.
• Use deepseek-v4-flash em rotas rápidas e econômicas; escolha Pro quando a tarefa justificar maior custo.
• Desative Thinking explicitamente em classificação ou extração simples quando tiver validado a qualidade.
• Teste prompts com dados representativos antes de estimar o custo médio.
• Registre falhas e não presuma custo zero; reconcilie o valor com os dados do fornecedor.

Concorrência não é uma quota de tokens. Os limites padrão documentados são 2.500 conexões simultâneas por conta para Flash e 500 para Pro. Acima disso, a API retorna HTTP 429. A DeepSeek permite solicitar expansão de capacidade sem custo adicional, sujeita à análise da necessidade do negócio. Use fila e backoff; não interprete 429 como erro de cálculo de tokens.

Aviso de migração dos aliases antigos

A DeepSeek marcou deepseek-chat e deepseek-reasoner para retirada em 24 de julho de 2026, 15:59 UTC. Na documentação verificada em 19 de julho, eles ainda eram aliases de compatibilidade para V4 Flash sem Thinking e com Thinking, respectivamente. Use deepseek-v4-flash ou deepseek-v4-pro e controle Thinking explicitamente.

Perguntas frequentes

Posso calcular tokens contando palavras?

Não com precisão suficiente para faturamento. Use aproximações apenas antes do envio e confirme o consumo no objeto usage retornado pela API.

Reasoning tokens são cobrados duas vezes?

Não os some separadamente. completion_tokens_details.reasoning_tokens detalha a conclusão; o cálculo de output deve usar completion_tokens.

Streaming impede a medição de usage?

Não. Ative stream_options.include_usage e capture o chunk final enviado antes de [DONE].

Cache hit é garantido quando repito o prompt?

Não. O mecanismo é best effort, depende da persistência e da correspondência de prefixos. Meça os campos de hit e miss em cada resposta.

Qual modelo custa menos?

Pelos preços verificados, V4 Flash tem tarifas menores que V4 Pro nas três categorias. A escolha deve considerar também qualidade, latência e tarefa, não apenas o preço unitário.

Fontes oficiais e próximos passos

• Token & Token Usage
• Create Chat Completion
• Models & Pricing
• Context Caching
• Thinking Mode
• Rate Limit & Isolation

Para implementar a chamada completa, continue no guia de migração do SDK OpenAI para DeepSeek ou consulte a nossa visão geral da API DeepSeek.