Contagem de tokens

Conte os tokens de um texto ou de uma requisição inteira antes de enviá-la.

POST https://api.shannon-ai.com/v1/tokenize

POST https://api.shannon-ai.com/v1/messages/count_tokens

Os dois endpoints contam com o tokenizador do modelo que você nomeia, e nenhum modelo é executado. Eles cobrem os modelos open-weight hospedados. /v1/tokenize aceita um texto simples ou uma conversa do Chat Completions. /v1/messages/count_tokens aceita uma requisição no formato Anthropic Messages, que é a chamada feita pelo SDK da Anthropic e pelo Claude Code.

A contagem é gratuita. Uma chamada precisa da sua chave de API, não tira nada do seu saldo e não aparece no seu registro de uso.

Contar um texto

Envie model e text. O texto é contado como está, sem formatação de chat em volta.

import requests

response = requests.post(
    "https://api.shannon-ai.com/v1/tokenize",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
        "text": "Hello, world",
    },
)
print(response.json()["tokens"])

const response = await fetch("https://api.shannon-ai.com/v1/tokenize", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    text: "Hello, world",
  }),
});

const { tokens } = await response.json();
console.log(tokens);

curl https://api.shannon-ai.com/v1/tokenize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    "text": "Hello, world"
  }'

200 Resposta

{
  "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
  "tokens": 3
}

Os números nas respostas desta página são exemplos. O mesmo texto dá uma contagem diferente em outro modelo.

Contar uma requisição de chat

Envie model e messages, com tools quando a requisição os tiver, exatamente como você os enviaria para /v1/chat/completions. A resposta é o tamanho de toda a entrada.

import requests

request = {
    "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "What is the weather in Paris?"},
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Current weather for a city",
                "parameters": {
                    "type": "object",
                    "properties": {"city": {"type": "string"}},
                    "required": ["city"],
                },
            },
        }
    ],
}

response = requests.post(
    "https://api.shannon-ai.com/v1/tokenize",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json=request,
)
print(response.json()["tokens"])

const request = {
  model: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "What is the weather in Paris?" },
  ],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Current weather for a city",
        parameters: {
          type: "object",
          properties: { city: { type: "string" } },
          required: ["city"],
        },
      },
    },
  ],
};

const response = await fetch("https://api.shannon-ai.com/v1/tokenize", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(request),
});

const { tokens } = await response.json();
console.log(tokens);

curl https://api.shannon-ai.com/v1/tokenize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "What is the weather in Paris?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Current weather for a city",
          "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      }
    ]
  }'

200 Resposta

{
  "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
  "tokens": 164
}

Campos de /v1/tokenize

Campo	Tipo	Descrição
`model`	`string`	Obrigatório. Um id de modelo open-weight hospedado. Maiúsculas e minúsculas são tratadas da mesma forma.
`text`	`string`	Um texto a contar como está, sem formatação de chat. Até 4,000,000 bytes. Envie `text` ou `messages`; quando ambos estão presentes, `text` é contado.
`messages`	`array`	Mensagens de chat no formato Chat Completions. Elas são contadas como a entrada completa de uma requisição: cada mensagem com a formatação que o template de chat do modelo coloca em volta dela.
`tools`	`array`	Definições de ferramenta a incluir na contagem. Usadas junto com `messages`.

A resposta é um objeto JSON com estes campos:

Campo	Tipo	Descrição
`model`	`string`	O id do modelo para o qual a contagem foi feita, na grafia publicada.
`tokens`	`integer`	Com `text`: os tokens do texto. Com `messages`: os tokens de toda a entrada, imagens incluídas.

Contar uma requisição Messages

Envie o corpo que você enviaria para /v1/messages: model, messages, e system e tools quando os usar. Os SDKs oficiais da Anthropic chamam este endpoint por meio de messages.count_tokens.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

count = client.messages.count_tokens(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    system="You are a concise assistant.",
    messages=[
        {"role": "user", "content": "Summarise the attached report."}
    ],
)
print(count.input_tokens)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.shannon-ai.com",
});

const count = await client.messages.countTokens({
  model: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
  system: "You are a concise assistant.",
  messages: [
    { role: "user", content: "Summarise the attached report." },
  ],
});
console.log(count.input_tokens);

curl https://api.shannon-ai.com/v1/messages/count_tokens \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    "system": "You are a concise assistant.",
    "messages": [
      {"role": "user", "content": "Summarise the attached report."}
    ]
  }'

200 Resposta

{
  "input_tokens": 21
}

Campos de /v1/messages/count_tokens

Campo	Tipo	Descrição
`model`	`string`	Obrigatório. Um id de modelo open-weight hospedado.
`messages`	`array`	Obrigatório. Mensagens no formato Anthropic Messages. Os blocos `text`, `image`, `tool_use` e `tool_result` são contados.
`system`	`string \| array`	O system prompt: uma string ou um array de blocos de texto.
`tools`	`array`	Definições de ferramenta com `name`, `description` e `input_schema`.

Aceitos por compatibilidade, sem efeito na contagem: tool_choice, max_tokens, temperature, top_p, stop_sequences, stream, thinking. Você pode passar o corpo de uma requisição real sem alterações.

A resposta é um objeto JSON com estes campos:

Campo	Tipo	Descrição
`input_tokens`	`integer`	Os tokens de toda a entrada: system prompt, mensagens, ferramentas e imagens.

Modelos aceitos

Os dois endpoints contam para os modelos open-weight hospedados. GET /v1/models lista /v1/tokenize e /v1/messages/count_tokens em endpoints de cada modelo que os suporta. Qualquer outro valor de model, inclusive os ids Shannon, é respondido com 400.

DeepSeek-V4-Pro-0813-3BIT-REAP
GLM-5.2-3BIT-REAP
Kimi-K3-3BIT-REAP
Nemotron3Ultra-3BIT-REAP
MiniMax-M3-3BIT-REAP
DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP
Kimi-K2.6-W4A16-AUTOROUND-REAP
Laguna-S-2.1-W4A16-AUTOROUND-REAP
inkling-W4A16-AUTOROUND-REAP
MiMo-V2.5-Pro-W8A16
MiMo-V2.5-W8A16
Hy3-W8A16

Para um modelo Shannon, leia as contagens de tokens do objeto usage de uma resposta.

Como a contagem é feita

Cada modelo é contado com o seu próprio tokenizador e o seu próprio template de chat. Nenhuma estimativa a partir de caracteres ou palavras é usada.

O que é contado	Regra
Um texto	Os tokens da string como enviada. Uma string vazia conta 0.
Mensagens	As mensagens e as ferramentas são organizadas com o template de chat do próprio modelo, até o ponto em que a resposta começa, e todo esse prompt é contado.
Papéis	As mensagens `system`, `user`, `assistant` e `tool` são contadas. `developer` é contado como `system`. Uma mensagem sem conteúdo e sem chamada de ferramenta não acrescenta nada.
Chamadas de ferramenta e resultados	As chamadas de ferramenta de turnos anteriores do assistente e os seus resultados fazem parte da contagem, nos dois endpoints.
Imagens	Uma imagem enviada dentro do corpo (base64 ou uma URL `data:`) acrescenta um token por bloco de 28 × 28 pixels: `ceil(width / 28) × ceil(height / 28)`. Uma imagem informada como URL `http(s)` não é baixada por estes endpoints e conta 1,024.

Exemplo: uma imagem de 1,024 × 768 pixels conta ceil(1024 / 28) × ceil(768 / 28) = 37 × 28 = 1,036 tokens.

A contagem e o que uma requisição é cobrada

A contagem de uma requisição inteira é feita do mesmo modo que a contagem de entrada de uma requisição real com o mesmo modelo, mensagens e ferramentas. Uma resposta informa esse número como usage.prompt_tokens no Chat Completions, como usage.input_tokens no Responses, e como usage.input_tokens mais usage.cache_read_input_tokens no Messages.

A contagem é a entrada antes do desconto de entrada em cache. Uma requisição real pode ler parte dessa entrada do cache e faturar essa parte à tarifa de cache. Caching de prompt
Uma imagem informada como URL http(s) conta 1,024 aqui. Uma requisição real baixa a imagem e a conta pelo tamanho em pixels, então os dois números podem diferir. Envie a imagem em base64 para obter o mesmo número.
A saída não faz parte da contagem. A resposta de uma requisição real é faturada como tokens de saída além disso, raciocínio incluído.
Uma contagem de text não tem formatação de chat. Use-a para medir um documento ou uma parte de prompt, e a forma messages para medir uma requisição.

Para transformar uma contagem em custo, multiplique-a pelo preço de entrada do modelo por 1M de tokens. Modelos e preços

Limites

Limite	Valor	Acima dele
Tamanho de `text`	4,000,000 bytes (UTF-8)	`413` com a mensagem `text too long`
Corpo da requisição	32 MiB	`413`
Por requisição	Um texto ou uma conversa	Envie uma requisição por texto para contar vários textos.

As chamadas de contagem não entram no limite de 120 requisições por minuto. Limites e saldo

Erros

Status	Tipo	Mensagem	Quando
`400`	`invalid_request_error`	`tokenize is available for the hosted open models; unknown model: <model>`	`/v1/tokenize` com um `model` que não é um id open-weight hospedado.
`400`	`invalid_request_error`	`count_tokens is available for the hosted open models; unknown model: <model>`	`/v1/messages/count_tokens` com um `model` que não é um id open-weight hospedado, ou sem `model`.
`400`	`invalid_request_error`	send `text` or `messages`	`/v1/tokenize` sem `text` nem `messages`.
`401`	`authentication_error`	`Missing authentication / Invalid API key`	Nenhuma chave foi enviada, ou a chave não é válida.
`413`	`invalid_request_error`	`text too long`	`text` tem mais de 4,000,000 bytes. Um corpo acima de 32 MiB também é respondido com `413`.
`415`	`invalid_request_error`	Expected request with `Content-Type: application/json`	A requisição não tem um tipo de conteúdo JSON.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type: …`	Falta um campo obrigatório (`model` em `/v1/tokenize`, `messages` em `/v1/messages/count_tokens`) ou um campo tem o tipo errado.
`503`	`api_error`	`token counting is temporarily unavailable for this model`	A contagem não pode ser feita para este modelo no momento. Tente novamente mais tarde.

/v1/tokenize retorna erros no formato da OpenAI. Em /v1/messages/count_tokens, os erros do próprio endpoint (400 para o modelo, 503) vêm no formato da Anthropic, e 401, 413, 415 e 422 vêm no formato da OpenAI. Leia primeiro o código de status e depois error.type e error.message, que estão presentes nos dois formatos.

400 /v1/tokenize

{
  "error": {
    "type": "invalid_request_error",
    "message": "tokenize is available for the hosted open models; unknown model: shannon-3"
  }
}

400 /v1/messages/count_tokens

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "count_tokens is available for the hosted open models; unknown model: shannon-3"
  }
}