Conteggio dei token

Conta i token di un testo o di un'intera richiesta prima di inviarla.

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

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

Entrambi gli endpoint contano con il tokenizer del modello che indichi, e nessun modello viene eseguito. Coprono i modelli open-weight ospitati. /v1/tokenize accetta un testo semplice o una conversazione Chat Completions. /v1/messages/count_tokens accetta una richiesta nel formato Anthropic Messages, che è la chiamata fatta dall'SDK Anthropic e da Claude Code.

Il conteggio è gratuito. Una chiamata richiede la tua chiave API, non preleva nulla dal tuo saldo e non compare nel tuo registro di utilizzo.

Contare un testo

Invia model e text. Il testo viene contato così com'è, senza formattazione di chat attorno.

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 Risposta

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

I numeri nelle risposte di questa pagina sono esempi. Lo stesso testo dà un conteggio diverso su un modello diverso.

Contare una richiesta di chat

Invia model e messages, con tools quando la richiesta li ha, esattamente come li invieresti a /v1/chat/completions. La risposta è la dimensione dell'intero input.

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 Risposta

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

Campi di /v1/tokenize

Campo	Tipo	Descrizione
`model`	`string`	Obbligatorio. Un id di modello open-weight ospitato. Maiuscole e minuscole sono trattate allo stesso modo.
`text`	`string`	Un testo da contare così com'è, senza formattazione di chat. Fino a 4,000,000 byte. Invia `text` oppure `messages`; quando sono presenti entrambi, viene contato `text`.
`messages`	`array`	Messaggi di chat nel formato Chat Completions. Vengono contati come input completo di una richiesta: ogni messaggio con la formattazione che il template di chat del modello gli mette attorno.
`tools`	`array`	Definizioni di tool da includere nel conteggio. Usate insieme a `messages`.

La risposta è un oggetto JSON con questi campi:

Campo	Tipo	Descrizione
`model`	`string`	L'id del modello per cui è stato fatto il conteggio, nella sua grafia pubblicata.
`tokens`	`integer`	Con `text`: i token del testo. Con `messages`: i token dell'intero input, immagini incluse.

Contare una richiesta Messages

Invia il corpo che invieresti a /v1/messages: model, messages, e system e tools se li usi. Gli SDK Anthropic ufficiali chiamano questo endpoint tramite 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 Risposta

{
  "input_tokens": 21
}

Campi di /v1/messages/count_tokens

Campo	Tipo	Descrizione
`model`	`string`	Obbligatorio. Un id di modello open-weight ospitato.
`messages`	`array`	Obbligatorio. Messaggi nel formato Anthropic Messages. Vengono contati i blocchi `text`, `image`, `tool_use` e `tool_result`.
`system`	`string \| array`	Il system prompt: una stringa o un array di blocchi di testo.
`tools`	`array`	Definizioni di tool con `name`, `description` e `input_schema`.

Accettati per compatibilità, senza effetto sul conteggio: tool_choice, max_tokens, temperature, top_p, stop_sequences, stream, thinking. Puoi passare invariato il corpo di una richiesta reale.

La risposta è un oggetto JSON con questi campi:

Campo	Tipo	Descrizione
`input_tokens`	`integer`	I token dell'intero input: system prompt, messaggi, tool e immagini.

Modelli supportati

Entrambi gli endpoint contano per i modelli open-weight ospitati. GET /v1/models elenca /v1/tokenize e /v1/messages/count_tokens negli endpoints di ogni modello che li supporta. Qualsiasi altro valore di model, inclusi gli id Shannon, riceve risposta 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

Per un modello Shannon, leggi i conteggi dei token dall'oggetto usage di una risposta.

Come si fa il conteggio

Ogni modello viene contato con il proprio tokenizer e il proprio template di chat. Non si usa alcuna stima da caratteri o parole.

Cosa viene contato	Regola
Un testo	I token della stringa così come inviata. Una stringa vuota conta 0.
Messaggi	I messaggi e i tool vengono disposti con il template di chat del modello, fino al punto in cui inizia la risposta, e l'intero prompt viene contato.
Ruoli	I messaggi `system`, `user`, `assistant` e `tool` vengono contati. `developer` viene contato come `system`. Un messaggio senza contenuto e senza chiamata di tool non aggiunge nulla.
Chiamate di tool e risultati	Le chiamate di tool dei turni precedenti dell'assistente e i loro risultati fanno parte del conteggio, su entrambi gli endpoint.
Immagini	Un'immagine inviata nel corpo (base64 o un URL `data:`) aggiunge un token per ogni patch di 28 × 28 pixel: `ceil(width / 28) × ceil(height / 28)`. Un'immagine fornita come URL `http(s)` non viene scaricata da questi endpoint e conta 1,024.

Esempio: un'immagine di 1,024 × 768 pixel conta ceil(1024 / 28) × ceil(768 / 28) = 37 × 28 = 1,036 token.

Il conteggio e ciò che viene addebitato a una richiesta

Il conteggio di un'intera richiesta viene fatto nello stesso modo del conteggio dell'input di una richiesta reale con lo stesso modello, gli stessi messaggi e gli stessi tool. Una risposta riporta quel numero come usage.prompt_tokens su Chat Completions, come usage.input_tokens su Responses e come usage.input_tokens più usage.cache_read_input_tokens su Messages.

Il conteggio è l'input prima dello sconto sull'input cached. Una richiesta reale può leggere parte di quell'input dalla cache e fatturare quella parte alla tariffa cached. Prompt caching
Un'immagine fornita come URL http(s) qui conta 1,024. Una richiesta reale scarica l'immagine e la conta in base alle sue dimensioni in pixel, quindi i due numeri possono differire. Invia l'immagine in base64 per ottenere lo stesso numero.
L'output non fa parte del conteggio. La risposta di una richiesta reale viene fatturata in aggiunta come token di output, ragionamento compreso.
Un conteggio text non ha formattazione di chat. Usalo per misurare un documento o una parte di prompt, e la forma messages per misurare una richiesta.

Per trasformare un conteggio in un costo, moltiplicalo per il prezzo di input del modello per 1M token. Modelli e prezzi

Limiti

Limite	Valore	Oltre il limite
Lunghezza di `text`	4,000,000 byte (UTF-8)	`413` con il messaggio `text too long`
Corpo della richiesta	32 MiB	`413`
Per richiesta	Un testo o una conversazione	Per contare più testi, invia una richiesta per ciascun testo.

Le chiamate di conteggio non rientrano nel limite di 120 richieste al minuto. Limiti e saldo

Errori

Stato	Tipo	Messaggio	Quando
`400`	`invalid_request_error`	`tokenize is available for the hosted open models; unknown model: <model>`	`/v1/tokenize` con un `model` che non è un id di modello open-weight ospitato.
`400`	`invalid_request_error`	`count_tokens is available for the hosted open models; unknown model: <model>`	`/v1/messages/count_tokens` con un `model` che non è un id di modello open-weight ospitato, oppure senza `model`.
`400`	`invalid_request_error`	send `text` or `messages`	`/v1/tokenize` né con `text` né con `messages`.
`401`	`authentication_error`	`Missing authentication / Invalid API key`	Non è stata inviata alcuna chiave, oppure la chiave non è valida.
`413`	`invalid_request_error`	`text too long`	`text` è più lungo di 4,000,000 byte. Anche un corpo oltre 32 MiB riceve risposta `413`.
`415`	`invalid_request_error`	Expected request with `Content-Type: application/json`	La richiesta non ha un content type JSON.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type: …`	Manca un campo obbligatorio (`model` su `/v1/tokenize`, `messages` su `/v1/messages/count_tokens`) oppure un campo ha il tipo sbagliato.
`503`	`api_error`	`token counting is temporarily unavailable for this model`	Al momento il conteggio non può essere eseguito per questo modello. Riprova più tardi.

/v1/tokenize restituisce gli errori nella forma OpenAI. Su /v1/messages/count_tokens gli errori dell'endpoint stesso (400 per il modello, 503) arrivano nella forma Anthropic, mentre 401, 413, 415 e 422 arrivano nella forma OpenAI. Leggi prima il codice di stato, poi error.type e error.message, presenti in entrambe le forme.

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"
  }
}