Đếm token
Đếm token của một văn bản hoặc của cả một yêu cầu trước khi bạn gửi nó.
POST https://api.shannon-ai.com/v1/tokenize
POST https://api.shannon-ai.com/v1/messages/count_tokens
Cả hai endpoint đều đếm bằng tokenizer của model bạn nêu tên, và không có model nào chạy. Chúng áp dụng cho các model open-weight hosted. /v1/tokenize nhận một văn bản thuần hoặc một cuộc hội thoại Chat Completions. /v1/messages/count_tokens nhận một yêu cầu theo định dạng Anthropic Messages, là lệnh gọi mà SDK Anthropic và Claude Code thực hiện.
Việc đếm là miễn phí. Một lượt gọi cần API key của bạn, không trừ gì khỏi số dư và không xuất hiện trong nhật ký sử dụng của bạn.
Đếm một văn bản
Hãy gửi model và text. Văn bản được đếm nguyên trạng, không có định dạng chat bao quanh.
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"
}' {
"model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
"tokens": 3
} Các con số trong phản hồi trên trang này là ví dụ. Cùng một văn bản cho số đếm khác nhau trên model khác.
Đếm một yêu cầu chat
Hãy gửi model và messages, kèm tools khi yêu cầu có, đúng như bạn sẽ gửi tới /v1/chat/completions. Phản hồi là kích thước của toàn bộ đầu vào.
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"]
}
}
}
]
}' {
"model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
"tokens": 164
} Các trường của /v1/tokenize
| Trường | Loại | Mô tả |
|---|---|---|
model | string | Bắt buộc. Một id model open-weight hosted. Chữ hoa và chữ thường được xử lý như nhau. |
text | string | Một văn bản được đếm nguyên trạng, không có định dạng chat. Tối đa 4,000,000 byte. Hãy gửi text hoặc messages; khi có cả hai, text được đếm. |
messages | array | Tin nhắn chat theo định dạng Chat Completions. Chúng được đếm như toàn bộ đầu vào của một yêu cầu: mỗi tin nhắn cùng phần định dạng mà chat template của model đặt quanh nó. |
tools | array | Các định nghĩa tool để đưa vào số đếm. Dùng cùng với messages. |
Phản hồi là một đối tượng JSON với các trường sau:
| Trường | Loại | Mô tả |
|---|---|---|
model | string | Id model mà số đếm được tạo cho, theo cách viết đã công bố. |
tokens | integer | Với text: các token của văn bản. Với messages: các token của toàn bộ đầu vào, bao gồm hình ảnh. |
Đếm một yêu cầu Messages
Hãy gửi nội dung bạn sẽ gửi tới /v1/messages: model, messages, và system cùng tools khi bạn dùng chúng. Các SDK chính thức của Anthropic gọi endpoint này qua 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."}
]
}' {
"input_tokens": 21
} Các trường của /v1/messages/count_tokens
| Trường | Loại | Mô tả |
|---|---|---|
model | string | Bắt buộc. Một id model open-weight hosted. |
messages | array | Bắt buộc. Tin nhắn theo định dạng Anthropic Messages. Các khối text, image, tool_use và tool_result được đếm. |
system | string | array | System prompt: một chuỗi hoặc một mảng các khối văn bản. |
tools | array | Các định nghĩa tool với name, description và input_schema. |
Được chấp nhận để tương thích, không ảnh hưởng đến số đếm: tool_choice, max_tokens, temperature, top_p, stop_sequences, stream, thinking. Bạn có thể truyền nội dung của một yêu cầu thật mà không cần thay đổi.
Phản hồi là một đối tượng JSON với các trường sau:
| Trường | Loại | Mô tả |
|---|---|---|
input_tokens | integer | Các token của toàn bộ đầu vào: system prompt, tin nhắn, tool và hình ảnh. |
Các model được hỗ trợ
Cả hai endpoint đếm cho các model open-weight hosted. GET /v1/models liệt kê /v1/tokenize và /v1/messages/count_tokens trong endpoints của mỗi model hỗ trợ chúng. Mọi giá trị model khác, kể cả các id Shannon, được trả lời bằng 400.
DeepSeek-V4-Pro-0813-3BIT-REAPGLM-5.2-3BIT-REAPKimi-K3-3BIT-REAPNemotron3Ultra-3BIT-REAPMiniMax-M3-3BIT-REAPDeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAPKimi-K2.6-W4A16-AUTOROUND-REAPLaguna-S-2.1-W4A16-AUTOROUND-REAPinkling-W4A16-AUTOROUND-REAPMiMo-V2.5-Pro-W8A16MiMo-V2.5-W8A16Hy3-W8A16
Với model Shannon, hãy đọc số token từ đối tượng usage của một phản hồi.
Cách số đếm được tạo
Mỗi model được đếm bằng tokenizer riêng và chat template riêng của nó. Không dùng ước tính từ số ký tự hay số từ.
| Cái được đếm | Quy tắc |
|---|---|
| Một văn bản | Các token của chuỗi như được gửi. Chuỗi rỗng được tính 0. |
| Tin nhắn | Tin nhắn và tool được sắp xếp bằng chat template riêng của model, đến điểm phản hồi bắt đầu, và toàn bộ prompt đó được đếm. |
| Vai trò | Các tin nhắn system, user, assistant và tool được đếm. developer được đếm như system. Tin nhắn không có nội dung và không có lần gọi tool thì không thêm gì. |
| Lần gọi tool và kết quả | Các lần gọi tool của những lượt assistant trước và kết quả của chúng là một phần của số đếm, trên cả hai endpoint. |
| Hình ảnh | Hình ảnh gửi bên trong nội dung (base64 hoặc URL data:) thêm một token cho mỗi ô 28 × 28 pixel: ceil(width / 28) × ceil(height / 28). Hình ảnh được cung cấp dưới dạng URL http(s) không được các endpoint này tải về và được tính 1,024. |
Ví dụ: một hình ảnh 1,024 × 768 pixel được tính ceil(1024 / 28) × ceil(768 / 28) = 37 × 28 = 1,036 token.
Số đếm và mức phí của một yêu cầu
Số đếm của cả một yêu cầu được tạo theo cùng cách như số đếm đầu vào của một yêu cầu thật với cùng model, tin nhắn và tool. Phản hồi báo cáo con số đó là usage.prompt_tokens trên Chat Completions, là usage.input_tokens trên Responses, và là usage.input_tokens cộng usage.cache_read_input_tokens trên Messages.
- Số đếm là đầu vào trước khi giảm giá đầu vào được cache. Một yêu cầu thật có thể đọc một phần đầu vào đó từ cache và tính phí phần đó theo giá cached. Caching prompt
- Hình ảnh được cung cấp dưới dạng URL
http(s)được tính 1,024 ở đây. Một yêu cầu thật tải hình ảnh về và đếm theo kích thước pixel của nó, nên hai con số có thể khác nhau. Hãy gửi hình ảnh dưới dạng base64 để có cùng một con số. - Đầu ra không nằm trong số đếm. Phản hồi của một yêu cầu thật được tính phí thêm dưới dạng token đầu ra, bao gồm cả suy luận.
- Số đếm
textkhông có định dạng chat. Hãy dùng nó để đo một tài liệu hoặc một phần của prompt, và dạngmessagesđể đo một yêu cầu.
Để đổi số đếm thành chi phí, hãy nhân nó với giá đầu vào của model cho mỗi 1M token. Model và giá
Giới hạn
| Giới hạn | Giá trị | Vượt quá giới hạn |
|---|---|---|
Độ dài của text | 4,000,000 byte (UTF-8) | 413 với thông báo text too long |
| Nội dung yêu cầu | 32 MiB | 413 |
| Mỗi yêu cầu | Một văn bản hoặc một cuộc hội thoại | Để đếm nhiều văn bản, hãy gửi một yêu cầu cho mỗi văn bản. |
Các lượt gọi đếm không được tính vào giới hạn 120 yêu cầu mỗi phút. Giới hạn và số dư
Lỗi
| Trạng thái | Loại | Thông báo | Khi nào |
|---|---|---|---|
400 | invalid_request_error | tokenize is available for the hosted open models; unknown model: <model> | /v1/tokenize với model không phải là id model open-weight hosted. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <model> | /v1/messages/count_tokens với model không phải là id model open-weight hosted, hoặc không có model. |
400 | invalid_request_error | send `text` or `messages` | /v1/tokenize không có cả text lẫn messages. |
401 | authentication_error | Missing authentication / Invalid API key | Không có key nào được gửi, hoặc key không hợp lệ. |
413 | invalid_request_error | text too long | text dài hơn 4,000,000 byte. Nội dung trên 32 MiB cũng được trả lời bằng 413. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Yêu cầu không có content type JSON. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Thiếu một trường bắt buộc (model trên /v1/tokenize, messages trên /v1/messages/count_tokens) hoặc một trường có kiểu sai. |
503 | api_error | token counting is temporarily unavailable for this model | Hiện tại không thể đếm cho model này. Hãy thử lại sau. |
/v1/tokenize trả lỗi theo dạng OpenAI. Trên /v1/messages/count_tokens, các lỗi của chính endpoint (400 cho model, 503) đến theo dạng Anthropic, còn 401, 413, 415 và 422 đến theo dạng OpenAI. Hãy đọc mã trạng thái trước, rồi error.type và error.message, vốn có trong cả hai dạng.
{
"error": {
"type": "invalid_request_error",
"message": "tokenize is available for the hosted open models; unknown model: shannon-3"
}
} {
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "count_tokens is available for the hosted open models; unknown model: shannon-3"
}
}