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

Última verificação documental: 24 de agosto 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. Também inclui uma medição autenticada realizada em 29 de julho de 2026 com 1.037 palavras em português brasileiro. Os exemplos textuais usam deepseek-v4-flash e deepseek-v4-pro; a seção de imagens cobre deepseek-v4-flash-vision-exp.

Atualizado em 24 de agosto de 2026. Os testes e custos medidos em 29 de julho permanecem como registro histórico e não foram recalculados. Hoje, a API hospedada lista deepseek-v4-flash, deepseek-v4-pro e deepseek-v4-flash-vision-exp; este último converte imagens em tokens de entrada. O Thinking Mode usa low, high e max; medium e xhigh são mapeados para high.

Leitura de usage em uma chamada real

Uma chamada autenticada ao V4 Flash, com Thinking desativado, respondeu HTTP 200. Os campos retornados permitem conferir entrada, cache, saída, total e custo.

Campo	Valor	Interpretação
prompt_tokens	31	Entrada total
prompt_cache_hit_tokens	0	Nada reaproveitado
prompt_cache_miss_tokens	31	Toda a entrada sem cache
completion_tokens	24	Saída gerada
total_tokens	55	31 + 24

prompt_tokens = cache_hit + cache_miss
31 = 0 + 31

total_tokens = prompt_tokens + completion_tokens
55 = 31 + 24

Custo V4 Flash = (31 ÷ 1.000.000 × 0,14) + (24 ÷ 1.000.000 × 0,28) = US$ 0,00001106

SHA-256 da requisição: cfe5fd5f35c1ed0ffb1e6b6844776ba9b15da6e84297c8af27201423c04a143a. SHA-256 da resposta: deb7c4e6450852c95b84fa035314754a39060d1cbaa770021b65d228234b953a. A latência de 306 ms é uma observação pontual, não benchmark.

Veja Preços, o teste de Context Caching e a referência oficial de Token Usage.

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.

---

Quantos tokens o português brasileiro usa?

Resposta curta: nas oito amostras deste estudo, 1.037 palavras em português brasileiro consumiram 1.657 tokens de texto: 159,8 tokens por 100 palavras, ou cerca de 1,60 token por palavra. A variação entre gêneros foi de 142,5 a 175,4 tokens por 100 palavras.

Use esse número para planejamento aproximado, não para faturamento. Em produção, leia usage.prompt_tokens na resposta da API, porque instruções de sistema, histórico, ferramentas e a estrutura da conversa também consomem tokens.

Resultado por tipo de texto

Amostra	Palavras	Tokens de texto	Tokens / 100 palavras
Notícia local	130	207	159,2
Conversa cotidiana	122	199	163,1
Texto administrativo	124	203	163,7
Documentação técnica	138	222	160,9
Financeiro e datas	126	221	175,4
Expressões brasileiras	134	191	142,5
Educação	135	207	153,3
Produto digital	128	207	161,7
Total / média ponderada	1.037	1.657	159,8

O corpus também soma 6.627 caracteres Unicode, incluindo espaços, e 6.827 bytes em UTF-8. A média ponderada foi de 250,0 tokens por 1.000 caracteres; por amostra, a faixa foi de 222,4 a 276,9. A diferença entre caracteres e bytes vem de letras acentuadas e outros caracteres que ocupam mais de um byte em UTF-8.

Como a medição foi feita

1. Criamos oito textos originais em pt-BR, com gêneros diferentes e sem copiar páginas externas.
2. Enviamos cada texto uma vez ao deepseek-v4-flash e uma vez ao deepseek-v4-pro: 16 chamadas autenticadas, todas em 29 de julho de 2026.
3. Usamos uma única mensagem de usuário, Thinking desativado e max_tokens: 1. A saída mínima serve apenas para obter o objeto usage; os tokens de conclusão não entram no estudo do texto.
4. Antes do corpus, medimos uma mensagem de usuário vazia. A API retornou quatro prompt_tokens nos dois modelos. Tratamos esses quatro tokens como o invólucro da conversa.
5. Para cada amostra, calculamos tokens_de_texto = prompt_tokens − 4. Assim, a métrica não confunde o texto do corpus com o custo estrutural da mensagem.
6. Contamos palavras como sequências de letras ou números Unicode; caracteres são pontos de código Unicode, incluindo espaços; bytes usam UTF-8.

Os dois modelos devolveram a mesma contagem de tokens em todas as oito amostras. Isso confirma a igualdade observada nesta coleta, mas não prova que toda versão futura usará o mesmo backend ou a mesma codificação. O finish_reason foi length porque limitamos deliberadamente a saída a um token; isso não invalida os campos de uso do prompt.

Texto puro não é o prompt completo

tokens de texto = prompt_tokens da chamada − 4 tokens do invólucro

Exemplo do corpus completo, somando oito chamadas por modelo:
1.657 tokens de texto + (8 × 4) = 1.689 prompt_tokens

Em uma aplicação real, o total pode ser muito maior. Mensagem de sistema, histórico, descrições de ferramentas, imagens, documentos recuperados e outros campos entram no prompt. O cache pode reduzir o preço de parte da entrada, mas não muda a quantidade de tokens informada. Veja o teste de Context Caching para separar contagem e cobrança.

Como usar a estimativa

Para um primeiro orçamento de texto semelhante ao corpus, multiplique a quantidade de palavras por 1,598. Um texto de 1.000 palavras daria cerca de 1.598 tokens; usando a faixa observada, aproximadamente 1.425 a 1.754. Depois, acrescente o restante do prompt e confirme com usage. Não use essa fórmula para limitar contexto ou cobrar cliente sem medição real.

Corpus e dados para download

Baixar o CSV do corpus e das 16 medições. O arquivo contém o texto integral de cada amostra, SHA-256 individual, palavras, caracteres, bytes e as contagens retornadas por Flash e Pro.

SHA-256 do CSV: cee95a911dc2fccb0a5a2b8165c1267556e9881bbddfb110ca6fb38a48bf585c
SHA-256 dos oito textos concatenados: d692b7880b0ec5cf30aa3191c513ecce9ad6b042e8021b740deb758a761efec3

O primeiro hash verifica o arquivo distribuído. O segundo identifica apenas o corpus textual combinado, na ordem C01–C08. Se qualquer caractere, espaço ou quebra de linha mudar, o hash correspondente também muda.

Limites da amostra

• São oito textos sintéticos e 1.037 palavras; não representam toda a escrita brasileira.
• A distribuição por gênero, tamanho, números, siglas, URLs, código, emojis e regionalismos altera a tokenização.
• Cada amostra foi medida uma vez por modelo; a contagem foi idêntica, mas o estudo não mede variação de saída.
• Subtraímos um baseline de quatro tokens observado naquele endpoint. Outros SDKs, formatos de mensagem ou backends podem adicionar estrutura diferente.
• O corpus mede entrada textual. Tokens de resposta e de raciocínio ficam fora das taxas por palavra.
• A codificação e o serviço podem mudar. Registre data, modelo e usage ao reproduzir.

Referências primárias: Token Usage oficial, Chat Completions e o repositório oficial de encoding do DeepSeek V4 Pro.

---

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 históricos do teste de 29 de julho

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 vigentes e verificados em 29 de julho de 2026. Esta tabela e os cálculos abaixo documentam aquele teste; não representam as tarifas atuais.

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 histórica de custo em Node.js — preços de 29/07/2026

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.

Preços atuais da API (24 de agosto de 2026)

Períodos de cobrança: o pico ocorre das 01:00 às 04:00 UTC e das 06:00 às 10:00 UTC, de segunda a sexta-feira; todos os demais horários são fora de pico. Confirme a tabela oficial antes de estimar produção.

Fora de pico

Modelo	Cache hit / 1M	Cache miss / 1M	Output / 1M
deepseek-v4-flash	US$ 0,007	US$ 0,22	US$ 0,66
deepseek-v4-pro	US$ 0,022	US$ 0,66	US$ 1,98
deepseek-v4-flash-vision-exp	US$ 0,007	US$ 0,22	US$ 0,66

Pico

Modelo	Cache hit / 1M	Cache miss / 1M	Output / 1M
deepseek-v4-flash	US$ 0,014	US$ 0,44	US$ 1,32
deepseek-v4-pro	US$ 0,044	US$ 1,32	US$ 3,96
deepseek-v4-flash-vision-exp	US$ 0,014	US$ 0,44	US$ 1,32

A fórmula permanece a mesma: multiplique os tokens de cache hit, cache miss e saída por suas tarifas e divida cada parcela por 1 milhão. Se você mantém histórico de custos, versione a tabela por data e faixa horária para não aplicar preços atuais a requisições antigas.

Como estimar tokens de imagem

Somente deepseek-v4-flash-vision-exp aceita imagens. Antes da inferência, cada imagem é redimensionada preservando a proporção: imagens abaixo de aproximadamente 384 × 384 pixels são ampliadas; imagens maiores são reduzidas para uma área próxima de 800 × 800 pixels. O limite resultante é de 384 tokens por imagem, e cada imagem de uma requisição é contada separadamente.

Para prever o consumo, informe largura e altura no calculador oficial de image tokens. Trate o resultado como estimativa: o objeto usage devolvido pela API é a fonte final de faturamento. Os tokens visuais entram no total de entrada junto com os tokens de texto.

Quando o detalhe fino não for necessário, detail: "low" reduz a imagem para 512 × 512 antes da inferência. Para imagens grandes, repetidas ou que ultrapassem o corpo inline, envie uma vez pela Files API e reutilize o file_id; isso evita novo upload, mas não transforma a Files API em armazenamento geral de PDFs nem elimina a cobrança dos tokens processados.

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.

Em um estudo separado de 8 de agosto de 2026, publicamos uma medição de contexto longo do DeepSeek V4 com usage, cache e custo observados em 16K, 128K e 512K.

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 low, 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. Se a requisição não incluir tools, o reasoning_content anterior pode ser omitido na próxima rodada e, se for enviado, será ignorado. Se a requisição incluir tools, preserve toda mensagem assistant com reasoning_content nas interações subsequentes, mesmo quando o modelo não realizar uma Tool Call naquela rodada. Quando houver chamadas, preserve também tool_calls e mantenha content como uma string não nula. 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

Em 29/07/2026, os aliases legados responderam e retornaram V4 Flash nesta conta, mas ficaram fora de GET /models. Não os use como base de código novo; veja a auditoria.

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?

Pelas tarifas atuais, V4 Flash e Vision Exp custam menos que V4 Pro nas três categorias. Vision Exp só é a escolha certa quando a entrada inclui imagens; considere também qualidade, latência e tarefa, não apenas o preço unitário.

Fontes oficiais e próximos passos

• Token & Token Usage, incluindo calculador de imagens
• Create Chat Completion
• Models & Pricing
• Context Caching
• Thinking Mode
• Vision e image tokens
• 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.