Atualizado em: 14 de maio de 2026.
DeepSeek Token Usage é o conjunto de métricas que mostra quantos tokens uma chamada à API da DeepSeek consumiu no prompt, na resposta, no cache e, quando aplicável, no raciocínio do modelo. Essas métricas são importantes porque tokens são a base de cobrança, limite de contexto, observabilidade, controle de custo e otimização de performance em produtos que usam a API.
A documentação oficial da DeepSeek define tokens como unidades básicas usadas pelos modelos para representar texto em linguagem natural e também como unidades de cobrança. A própria DeepSeek informa que proporções por caractere ou palavra são apenas aproximações; a contagem confiável deve vir do campo usage retornado pela API.
Esta página é um guia independente em português do Brasil. Para cobrança, limites, modelos e parâmetros, consulte sempre a documentação oficial da DeepSeek antes de usar em produção.
Table of Contents
Resumo executivo
Para monitorar DeepSeek API Token Usage corretamente, não conte apenas palavras, caracteres ou tamanho bruto do prompt. O ponto mais confiável é o objeto usage retornado pela API.
Os campos mais importantes são:
prompt_tokens: tokens de entrada.completion_tokens: tokens gerados na resposta.total_tokens: soma de tokens de entrada e saída.prompt_cache_hit_tokens: tokens de entrada que bateram no context cache.prompt_cache_miss_tokens: tokens de entrada que não bateram no context cache.completion_tokens_details.reasoning_tokens: tokens gerados pelo modelo para raciocínio, quando esse detalhe estiver presente.
A fórmula operacional mais importante é:
prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokensPara calcular custo, trate cache hit, cache miss e output separadamente, porque a página oficial de preços da DeepSeek usa valores diferentes para cada categoria.
O que é DeepSeek Token Usage?
DeepSeek Token Usage é a leitura das estatísticas de consumo de tokens retornadas pela API após uma requisição. Essas estatísticas mostram quanto texto foi processado como entrada, quanto foi gerado como saída, quanto foi reaproveitado via cache e, quando aplicável, quanto foi usado no raciocínio do modelo.
Na prática, token usage ajuda a responder perguntas como:
- Quanto esta request custou?
- Qual usuário, cliente ou feature consome mais tokens?
- O prompt está grande demais?
- O histórico da conversa está ficando caro?
- O context caching está funcionando?
- O Thinking Mode está aumentando o consumo?
- A chamada está se aproximando do limite de contexto?
Para protótipos pequenos, olhar apenas a resposta do modelo pode ser suficiente. Para produtos reais, como SaaS, chatbots, agentes, copilotos de código e pipelines RAG, o campo usage deve entrar em logs, métricas, dashboards e alertas.
O que é um token na DeepSeek API?
Um token é uma unidade de texto usada pelo modelo. Ele pode representar uma palavra, parte de uma palavra, um número, um símbolo ou pontuação. A documentação oficial da DeepSeek dá aproximações para inglês e chinês, mas reforça que a tokenização pode variar conforme o modelo e que a contagem real deve ser lida em usage.
Por isso, evite regras fixas como “1 token = 1 palavra”. Elas podem servir para estimativas rápidas, mas não para cobrança interna, auditoria, rate limiting, quotas de usuários ou cálculo financeiro em produção.
Fonte oficial: Token & Token Usage — DeepSeek API Docs.
Token, palavra, caractere, context length e max_tokens
Um erro comum é misturar conceitos diferentes. Eles se relacionam, mas não são iguais.
| Conceito | O que significa | Como usar na prática |
|---|---|---|
| Token | Unidade processada pelo modelo | Base para custo, uso e limites |
| Palavra | Unidade linguística humana | Útil para estimativa editorial, não para billing |
| Caractere | Letra, número, espaço ou símbolo | Estimativa grosseira de tamanho |
| Context length | Janela máxima de tokens que o modelo consegue considerar | Limite combinado de entrada, histórico, ferramentas e saída |
max_tokens | Número máximo de tokens que a resposta pode gerar | Controle de tamanho da saída e custo |
total_tokens | Soma de tokens de entrada e saída | Métrica geral de consumo da request |
A documentação oficial atual informa que deepseek-v4-flash e deepseek-v4-pro usam contexto de até 1 milhão de tokens e saída máxima de até 384 mil tokens. Esses números podem mudar com versões futuras, então valide sempre na página oficial de modelos e preços.
Context length não é a mesma coisa que max_tokens. A janela de contexto é o limite total da conversa, incluindo prompt, histórico, documentos, mensagens de ferramentas e resposta. Já max_tokens limita apenas a geração da resposta. Se a soma de entrada e saída exceder o contexto do modelo, a chamada pode falhar, ser truncada ou terminar com finish_reason="length".
Como ler o objeto usage da resposta da API
Depois de chamar /chat/completions, a API retorna um objeto com a resposta do modelo. Em chamadas não streaming, o corpo final normalmente inclui usage.
Um exemplo conceitual:
{
"model": "deepseek-v4-pro",
"usage": {
"prompt_tokens": 12000,
"completion_tokens": 850,
"total_tokens": 12850,
"prompt_cache_hit_tokens": 9000,
"prompt_cache_miss_tokens": 3000,
"completion_tokens_details": {
"reasoning_tokens": 420
}
}
}Interpretação:
- O prompt completo consumiu
12000tokens. 9000tokens de entrada foram cache hit.3000tokens de entrada foram cache miss.- A resposta gerada consumiu
850tokens. - O total da request foi
12850tokens. - Dentro da geração,
420tokens foram classificados como reasoning tokens.
A referência oficial informa que prompt_tokens é igual a prompt_cache_hit_tokens + prompt_cache_miss_tokens. Em integrações reais, ainda assim é recomendável tratar campos ausentes com segurança, porque exemplos, SDKs e respostas podem variar.
Tabela dos principais campos de token usage
| Campo | Significado | Por que importa |
|---|---|---|
prompt_tokens | Número de tokens no prompt | Mede a entrada total enviada ao modelo |
completion_tokens | Número de tokens gerados na resposta | Afeta custo de output e tamanho da resposta |
total_tokens | Total de tokens usados na request | Visão geral do consumo |
prompt_cache_hit_tokens | Tokens do prompt que bateram no context cache | Podem reduzir o custo da entrada |
prompt_cache_miss_tokens | Tokens do prompt que não bateram no cache | Entrada processada sem reaproveitamento |
completion_tokens_details.reasoning_tokens | Tokens gerados pelo modelo para raciocínio | Ajuda a monitorar Thinking Mode e esforço interno |
stream_options.include_usage | Opção para receber usage em streaming | Permite medir consumo em respostas SSE |
reasoning_content | Conteúdo de raciocínio retornado em Thinking Mode | Importante em fluxos multi-turn e tool calls |
Fonte oficial: Create Chat Completion — DeepSeek API Docs.
Como calcular token usage offline
Além de ler usage nas respostas reais da API, a DeepSeek também fornece um pacote oficial de tokenizer para estimar token usage offline. Esse recurso é útil para testar prompts, comparar versões de system prompt, estimar custo antes de enviar documentos longos e criar validações internas de tamanho.
Mesmo assim, para faturamento e auditoria, prefira sempre o número real retornado pela API em usage, porque a documentação oficial informa que a contagem efetiva depende da tokenização do modelo.
Link oficial: deepseek_tokenizer.zip.
Exemplo em Python para extrair usage metrics
O exemplo abaixo usa o SDK compatível com OpenAI apontando para a base URL oficial da DeepSeek. A documentação oficial informa que a API usa formato compatível com OpenAI e Anthropic, com base_url="https://api.deepseek.com" para o formato OpenAI.
import os
from typing import Any, Dict
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com",
)
def read_field(obj: Any, key: str, default: Any = 0) -> Any:
"""Lê campo de objeto ou dict sem quebrar quando a estrutura muda."""
if obj is None:
return default
if isinstance(obj, dict):
return obj.get(key, default)
return getattr(obj, key, default)
def extract_deepseek_usage(response: Any) -> Dict[str, int]:
usage = read_field(response, "usage", {}) or {}
details = read_field(usage, "completion_tokens_details", {}) or {}
prompt_tokens = int(read_field(usage, "prompt_tokens", 0) or 0)
completion_tokens = int(read_field(usage, "completion_tokens", 0) or 0)
total_tokens = int(read_field(usage, "total_tokens", 0) or 0)
cache_hit = int(read_field(usage, "prompt_cache_hit_tokens", 0) or 0)
cache_miss = int(read_field(usage, "prompt_cache_miss_tokens", 0) or 0)
reasoning_tokens = int(read_field(details, "reasoning_tokens", 0) or 0)
cache_sum = cache_hit + cache_miss
cache_fields_available = cache_sum > 0
return {
"prompt_tokens": prompt_tokens,
"completion_tokens": completion_tokens,
"total_tokens": total_tokens,
"prompt_cache_hit_tokens": cache_hit,
"prompt_cache_miss_tokens": cache_miss,
"reasoning_tokens": reasoning_tokens,
"cache_fields_available": int(cache_fields_available),
"cache_sum_matches_prompt": int(
not cache_fields_available or cache_sum == prompt_tokens
),
}
response = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[
{"role": "system", "content": "Você é um assistente técnico objetivo."},
{"role": "user", "content": "Explique como monitorar token usage na API."},
],
stream=False,
extra_body={"thinking": {"type": "disabled"}},
)
metrics = extract_deepseek_usage(response)
print(metrics)Em produção, salve essas métricas com request_id, user_id, customer_id, model, endpoint, feature, timestamp, latência, status HTTP e custo estimado. Não inclua dados pessoais sensíveis em identificadores como user_id.
Exemplo em Node.js/TypeScript para monitorar token usage
import OpenAI from "openai";
type DeepSeekUsage = {
prompt_tokens?: number;
completion_tokens?: number;
total_tokens?: number;
prompt_cache_hit_tokens?: number;
prompt_cache_miss_tokens?: number;
completion_tokens_details?: {
reasoning_tokens?: number;
};
};
const client = new OpenAI({
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: "https://api.deepseek.com",
});
function extractUsage(completion: any) {
const usage: DeepSeekUsage = completion.usage ?? {};
const details = usage.completion_tokens_details ?? {};
const promptTokens = usage.prompt_tokens ?? 0;
const completionTokens = usage.completion_tokens ?? 0;
const totalTokens = usage.total_tokens ?? 0;
const cacheHit = usage.prompt_cache_hit_tokens ?? 0;
const cacheMiss = usage.prompt_cache_miss_tokens ?? 0;
const reasoningTokens = details.reasoning_tokens ?? 0;
return {
prompt_tokens: promptTokens,
completion_tokens: completionTokens,
total_tokens: totalTokens,
prompt_cache_hit_tokens: cacheHit,
prompt_cache_miss_tokens: cacheMiss,
reasoning_tokens: reasoningTokens,
cache_sum_matches_prompt:
cacheHit + cacheMiss === 0 || cacheHit + cacheMiss === promptTokens,
};
}
async function main() {
const completion = await client.chat.completions.create({
model: "deepseek-v4-flash",
messages: [
{
role: "system",
content: "Você é um assistente técnico para documentação de APIs.",
},
{
role: "user",
content: "Liste boas práticas para reduzir uso de tokens em um chatbot.",
},
],
stream: false,
thinking: { type: "disabled" },
} as any);
const usage = extractUsage(completion);
console.log("Resposta:", completion.choices[0]?.message?.content);
console.log("Usage:", usage);
}
main().catch(console.error);Em TypeScript, as any pode ser necessário quando o SDK ainda não tipa parâmetros específicos da DeepSeek, como thinking. Em aplicações maiores, crie um wrapper próprio para padronizar modelo, modo, custo, logs e tratamento de erros.
Como medir token usage em streaming
Quando stream: true, a resposta chega em chunks via Server-Sent Events. Para receber o token usage final, use:
{
"stream": true,
"stream_options": {
"include_usage": true
}
}A referência oficial informa que, com stream_options.include_usage, um chunk adicional é enviado antes de data: [DONE]. Esse chunk contém usage para a request inteira, e o campo choices vem como array vazio. Os demais chunks também podem conter usage, mas com valor nulo.
Exemplo em Node.js/TypeScript:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: "https://api.deepseek.com",
});
async function streamWithUsage() {
const stream = await client.chat.completions.create({
model: "deepseek-v4-flash",
messages: [
{ role: "user", content: "Crie um resumo técnico sobre context caching." },
],
stream: true,
stream_options: { include_usage: true },
thinking: { type: "disabled" },
} as any);
let finalText = "";
let finalUsage: any = null;
for await (const chunk of stream) {
const delta = chunk.choices?.[0]?.delta?.content;
if (delta) {
finalText += delta;
}
if ((chunk as any).usage) {
finalUsage = (chunk as any).usage;
}
}
console.log("Texto final:", finalText);
console.log("Usage final:", finalUsage);
}
streamWithUsage().catch(console.error);Sem esse chunk final de usage, sua interface pode exibir a resposta normalmente, mas o sistema perde a medição correta de consumo e custo.
Como calcular o custo da DeepSeek API por request
A forma mais robusta de calcular custo é separar três componentes:
- Entrada com cache hit.
- Entrada com cache miss.
- Saída gerada pelo modelo.
Use a fórmula:
custo =
(prompt_cache_hit_tokens / 1_000_000) * preço_input_cache_hit
+
(prompt_cache_miss_tokens / 1_000_000) * preço_input_cache_miss
+
(completion_tokens / 1_000_000) * preço_outputEssa separação é necessária porque a página oficial de preços lista valores diferentes para input com cache hit, input com cache miss e output. Até a data desta revisão, os preços oficiais por 1 milhão de tokens são:
| Modelo | Input cache hit | Input cache miss | Output |
|---|---|---|---|
deepseek-v4-flash | US$ 0.0028 | US$ 0.14 | US$ 0.28 |
deepseek-v4-pro com desconto de 75% | US$ 0.003625 | US$ 0.435 | US$ 0.87 |
deepseek-v4-pro preço normal | US$ 0.0145 | US$ 1.74 | US$ 3.48 |
A DeepSeek informa que o desconto de 75% do deepseek-v4-pro está estendido até 31 de maio de 2026, às 15:59 UTC. Como preços, descontos e modelos podem mudar, sempre valide na página oficial antes de usar em produção.
Fonte oficial: Models & Pricing — DeepSeek API Docs.
Exemplo numérico
Suponha uma chamada com deepseek-v4-flash:
prompt_cache_hit_tokens = 90_000
prompt_cache_miss_tokens = 10_000
completion_tokens = 4_000Usando os preços oficiais atuais do deepseek-v4-flash:
preço_input_cache_hit = 0.0028
preço_input_cache_miss = 0.14
preço_output = 0.28O cálculo fica:
custo =
(90_000 / 1_000_000) * 0.0028
+
(10_000 / 1_000_000) * 0.14
+
(4_000 / 1_000_000) * 0.28
custo =
0.000252
+
0.0014
+
0.00112
custo = 0.002772Nesse exemplo, a request custaria aproximadamente US$ 0.002772, sem considerar impostos, câmbio, taxas bancárias ou custos externos ao preço oficial da DeepSeek.
Função de custo em Python
def calculate_deepseek_cost(
usage: dict,
price_input_cache_hit: float,
price_input_cache_miss: float,
price_output: float,
) -> float:
cache_hit = usage.get("prompt_cache_hit_tokens", 0) or 0
cache_miss = usage.get("prompt_cache_miss_tokens", 0) or 0
completion = usage.get("completion_tokens", 0) or 0
return (
(cache_hit / 1_000_000) * price_input_cache_hit
+ (cache_miss / 1_000_000) * price_input_cache_miss
+ (completion / 1_000_000) * price_output
)Evite calcular custo usando apenas total_tokens, porque isso ignora a diferença de preço entre cache hit, cache miss e output.
Cache hit vs cache miss no context caching
O Context Caching da DeepSeek é habilitado por padrão para todos os usuários da API e não exige alteração no código. Quando uma request posterior tem prefixos sobrepostos com uma request anterior, a parte sobreposta pode ser buscada no cache e contada como cache hit.
O que é cache hit?
Cache hit acontece quando uma parte inicial do prompt corresponde a um prefixo já persistido no cache da DeepSeek. Isso pode ocorrer em cenários como:
- Prompts de sistema repetidos.
- Conversas multi-turn.
- Análise do mesmo documento longo com perguntas diferentes.
- RAG que envia o mesmo bloco de contexto em múltiplas chamadas.
- Agentes que mantêm instruções fixas, ferramentas e contexto recorrente.
O que é cache miss?
Cache miss ocorre quando os tokens de entrada não são encontrados no cache ou não correspondem a uma unidade de prefixo persistida. Isso pode acontecer porque:
- A request é a primeira daquele contexto.
- O prefixo mudou.
- O conteúdo comum ainda não foi persistido.
- O cache foi limpo automaticamente.
- A estrutura do prompt foi reorganizada.
- O trecho repetido não aparece como prefixo compatível.
Por que prefixos importam?
A documentação oficial explica que cache hit exige correspondência com uma unidade de prefixo já persistida. Na prática, coloque conteúdo estável no começo do prompt:
- System prompt fixo.
- Regras permanentes.
- Contexto reutilizável.
- Documentos longos recorrentes.
- Histórico ou resumo estável.
- Pergunta atual por último.
Em vez de montar o prompt assim:
Pergunta nova do usuário
Regras fixas
Documento longoPrefira:
Regras fixas
Documento longo
Pergunta nova do usuárioEssa organização aumenta a chance de reaproveitamento de prefixos, embora não garanta cache hit.
O cache não garante 100% de hit rate
A DeepSeek informa que o cache funciona em regime de best effort e não garante taxa de hit de 100%. A construção do cache pode levar alguns segundos e caches sem uso podem ser limpos automaticamente depois de algumas horas ou dias.
Portanto, trate cache hit como otimização, não como garantia contratual de custo. Seu billing interno deve continuar correto mesmo quando todo o prompt for cache miss.
Fonte oficial: Context Caching — DeepSeek API Docs.
Thinking Mode, reasoning_content e reasoning_tokens
Os modelos atuais da DeepSeek podem operar em Thinking Mode ou em Non-Thinking Mode. Pela documentação oficial, o parâmetro é:
{
"thinking": {
"type": "enabled"
}
}ou:
{
"thinking": {
"type": "disabled"
}
}O Thinking Mode é habilitado por padrão. A DeepSeek também documenta reasoning_effort com valores como high e max. Em Thinking Mode, parâmetros como temperature, top_p, presence_penalty e frequency_penalty não têm efeito, ainda que possam ser aceitos por compatibilidade.
Em respostas com Thinking Mode, a API pode retornar:
reasoning_content: conteúdo de raciocínio retornado antes da resposta final.content: resposta final para o usuário.completion_tokens_details.reasoning_tokens: contagem de tokens de raciocínio dentro do usage, quando disponível.
Ao usar tool calls em Thinking Mode, a documentação oficial informa que reasoning_content deve ser passado de volta em requests subsequentes quando houver chamadas de ferramenta. Se esse encadeamento não for feito corretamente, a API pode retornar erro 400.
Para reduzir custo e tornar respostas mais previsíveis, use thinking: {"type": "disabled"} em rotas simples, como classificação, extração de campos, resumos curtos e respostas padronizadas. Ative Thinking Mode quando a tarefa exigir raciocínio, programação complexa, análise técnica ou agentes.
Fonte oficial: Thinking Mode — DeepSeek API Docs.
Como reduzir token usage sem perder qualidade
Reduzir uso de tokens não significa apenas encurtar tudo. Significa enviar ao modelo o contexto certo, na ordem certa e com o nível certo de detalhe.
1. Encurte o system prompt
System prompts crescem com o tempo. Times adicionam regras, exceções, estilo, políticas internas e exemplos até o prompt virar um documento inchado.
Revise periodicamente:
- Quais instruções são realmente usadas?
- Há regras duplicadas?
- O mesmo conceito aparece várias vezes?
- Exemplos antigos ainda ajudam?
- O prompt precisa ser igual para todas as features?
Um system prompt menor reduz prompt_tokens em todas as chamadas e pode melhorar latência.
2. Resuma o histórico da conversa
Em chatbots multi-turn, reenviar toda a conversa pode ficar caro. Depois de certo ponto, use resumo de estado:
Resumo da conversa até agora:
- O usuário quer integrar DeepSeek em um SaaS.
- Já escolheu deepseek-v4-flash para respostas rápidas.
- Precisa monitorar custo por customer_id.Mantenha as últimas mensagens brutas e substitua mensagens antigas por um resumo fiel.
3. Otimize RAG e envie apenas trechos necessários
Em RAG, o erro clássico é enviar documentos demais. Em vez de mandar muitos chunks por padrão, envie os trechos mais relevantes, com metadados mínimos e instrução clara.
Também vale deduplicar trechos parecidos e limitar tamanho por fonte. Se o usuário pergunta sobre política de reembolso, não envie todo o contrato se apenas um trecho responde à pergunta.
4. Use max_tokens com inteligência
max_tokens é uma trava de saída. Se a feature precisa apenas de uma classificação, não deixe a resposta gerar milhares de tokens.
- Classificação:
max_tokensbaixo. - Resumo curto: limite moderado.
- Relatório detalhado: limite maior.
- Agente de código: limite ajustado ao fluxo.
A referência oficial descreve max_tokens como o número máximo de tokens que podem ser gerados na chat completion, lembrando que entrada e geração continuam limitadas pelo context length do modelo.
5. Fixe prefixos recorrentes para melhorar cache
Como o context caching depende de prefixos compatíveis, não reordene blocos fixos sem necessidade. Use uma estrutura estável:
[system prompt fixo][política fixa]
[documento recorrente]
[histórico resumido]
[pergunta atual]
Pequenas mudanças no começo do prompt podem reduzir cache hit.
6. Separe custo por feature, usuário e cliente
Não basta saber o custo total da API. Registre:
modelfeatureuser_idcustomer_idprompt_tokenscompletion_tokensprompt_cache_hit_tokensprompt_cache_miss_tokensreasoning_tokens- custo estimado
- latência
- status HTTP
- erro retornado, quando houver
Assim, você consegue identificar clientes caros, features mal otimizadas e prompts que precisam ser revistos.
7. Monitore p95 e p99 de tokens
Médias escondem problemas. Uma feature pode ter média de 2.000 tokens, mas p99 de 120.000 tokens. Isso significa que uma pequena parcela das chamadas pode gerar custo desproporcional.
Acompanhe:
- p50, p95 e p99 de
prompt_tokens. - p50, p95 e p99 de
completion_tokens. - p95 de
reasoning_tokens. - cache hit ratio por feature.
- custo por 1.000 requests.
- custo por cliente.
- erros 400, 402, 429, 500 e 503.
Erros comuns ao interpretar DeepSeek Token Usage
1. Achar que token é igual a palavra
Token pode ser palavra, parte de palavra, número, símbolo ou pontuação. Use estimativas apenas para planejamento, não para faturamento.
2. Ignorar output tokens
Muitos times otimizam o prompt e esquecem que respostas longas também custam. completion_tokens deve ser monitorado com o mesmo cuidado que prompt_tokens.
3. Calcular custo usando apenas total_tokens
total_tokens é útil, mas não captura preços diferentes para cache hit, cache miss e output. Para custo realista, separe os componentes.
4. Ignorar reasoning_tokens
Em Thinking Mode, raciocínio pode aumentar consumo. Se você não registra reasoning_tokens, pode não entender por que algumas chamadas ficam mais caras.
5. Usar preços antigos
Preços, descontos e modelos podem mudar. A página oficial de pricing informa que os preços podem variar e recomenda verificar a página regularmente.
6. Confundir context length com max_tokens
Context length é a janela total. max_tokens é o limite de geração. Uma chamada pode falhar ou ser truncada se a soma de entrada e saída exceder o limite aplicável.
7. Não registrar usage nos logs
Sem usage, você não consegue auditar custo, criar alertas, comparar modelos ou provar consumo por cliente.
8. Colocar API key no frontend
Nunca exponha DEEPSEEK_API_KEY no navegador. Faça chamadas pelo backend, aplique autenticação, controle por usuário, rate limiting e monitoramento.
9. Ignorar restrições do Thinking Mode
Em Thinking Mode, parâmetros como temperature e top_p não têm efeito segundo a documentação oficial. Se você precisa controlar estilo ou aleatoriedade, teste o comportamento com Thinking Mode desativado.
Checklist prático para produção
Antes de lançar DeepSeek em produção, valide esta lista:
- O backend registra
usageem todas as chamadas. - Chamadas streaming usam
stream_options.include_usage. - O custo é calculado separando cache hit, cache miss e output.
- O sistema registra
model,feature,user_idecustomer_id. - Identificadores como
user_idnão contêm dados pessoais sensíveis. - Há alertas para p95/p99 de tokens.
- Há limites por usuário, cliente, plano ou feature.
- O histórico de conversa é resumido quando fica grande.
- RAG envia apenas chunks relevantes.
max_tokensé definido por feature.- System prompts são revisados periodicamente.
- API keys ficam apenas no backend.
- Preços são atualizados a partir da documentação oficial.
- Thinking Mode é usado apenas onde melhora o resultado.
- Dashboards mostram cache hit ratio.
- Erros 400, 401, 402, 422, 429, 500 e 503 são monitorados.
- Requests com 429 usam backoff, filas ou controle de concorrência.
- Requests com 503 são tratados como possível sobrecarga temporária.
A DeepSeek informa que a API aplica limites dinâmicos de concorrência conforme carga do servidor. Ao atingir o limite, a API pode retornar HTTP 429. Portanto, não assuma um limite público simples como “X requisições por minuto” válido para todas as contas.
Fontes oficiais: Rate Limit e Error Codes.
FAQ sobre DeepSeek Token Usage
O que é DeepSeek Token Usage?
É o conjunto de métricas de consumo de tokens retornadas pela API da DeepSeek. Ele mostra tokens de entrada, tokens de saída, total de tokens, tokens com cache hit, tokens com cache miss e, quando aplicável, tokens de raciocínio.
Onde encontro o token usage na resposta?
Em chamadas não streaming, procure o campo usage no objeto final da resposta. Em streaming, use stream_options.include_usage para receber o usage no chunk final antes de data: [DONE].
prompt_tokens é igual a palavras do prompt?
Não. Tokens não são palavras. Um token pode ser uma palavra, parte de palavra, número, símbolo ou pontuação. A contagem confiável vem do campo usage.
Qual é a diferença entre prompt_tokens e completion_tokens?
prompt_tokens mede a entrada enviada ao modelo. completion_tokens mede a saída gerada pelo modelo. Ambos contribuem para custo e consumo total.
O que significa total_tokens?
total_tokens é o total de tokens usados na request: prompt mais completion. Ele é útil para visão geral, mas não deve ser a única métrica de custo quando há preços diferentes para cache hit, cache miss e output.
O que são prompt_cache_hit_tokens?
São tokens do prompt que bateram no context cache da DeepSeek. Isso significa que parte do prefixo de entrada foi reaproveitada a partir de uma unidade de cache já persistida.
O que são prompt_cache_miss_tokens?
São tokens do prompt que não bateram no cache e precisaram ser processados sem reaproveitamento.
O cache hit é garantido?
Não. A DeepSeek informa que o context caching funciona em regime de best effort e não garante 100% de hit rate. Use o cache como otimização, não como garantia de custo.
Como calcular custo da DeepSeek API?
Use a fórmula separando input cache hit, input cache miss e output. Multiplique cada quantidade de tokens pelo respectivo preço por 1 milhão de tokens e some os resultados. Sempre confirme os preços atuais na página oficial.
reasoning_tokens aparecem sempre?
Não necessariamente. Eles aparecem dentro de completion_tokens_details quando a resposta inclui esse detalhamento. Monitore esse campo principalmente ao usar Thinking Mode.
Posso calcular tokens antes de chamar a API?
Sim. A DeepSeek fornece um pacote oficial de tokenizer para estimar token usage offline. Ainda assim, para billing e auditoria, use a contagem real retornada pela API em usage.
Conclusão
O objeto usage é a fonte mais importante para medir consumo real na DeepSeek API. Ele permite acompanhar entrada, saída, cache hit, cache miss e tokens de raciocínio, quando aplicáveis. Para produção, registre essas métricas em todas as chamadas, calcule custo separando os componentes de preço e valide regularmente os valores na documentação oficial.
O ponto central é simples: não faça billing interno com base em palavras ou caracteres. Use usage, monitore cache, trate streaming corretamente com stream_options.include_usage e mantenha prompts estáveis para aumentar a chance de cache hit sem depender dele como garantia.
Aviso: esta página foi revisada contra a documentação oficial da DeepSeek em 14 de maio de 2026. Modelos, preços, limites, parâmetros e políticas podem mudar. Sempre confirme as informações em api-docs.deepseek.com e platform.deepseek.com antes de usar em produção ou estimar custos comerciais.
