شمارش توکن
توکنهای یک متن یا یک درخواست کامل را پیش از ارسال بشمارید.
POST https://api.shannon-ai.com/v1/tokenize
POST https://api.shannon-ai.com/v1/messages/count_tokens
هر دو endpoint با توکنایزر مدلی که نام میبرید میشمارند و هیچ مدلی اجرا نمیشود. آنها مدلهای open-weight میزبانیشده را پوشش میدهند. /v1/tokenize یک متن ساده یا یک گفتگوی Chat Completions میگیرد. /v1/messages/count_tokens یک درخواست در قالب Anthropic Messages میگیرد، که همان فراخوانیای است که Anthropic SDK و Claude Code انجام میدهند.
شمارش رایگان است. فراخوانی به کلید API شما نیاز دارد، چیزی از موجودی شما کم نمیکند و در گزارش مصرف شما نمیآید.
شمارش یک متن
model و text را بفرستید. متن همانطور که هست شمرده میشود، بدون هیچ قالببندی چت در اطراف آن.
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
} عددهای موجود در پاسخهای این صفحه نمونه هستند. همان متن روی مدل دیگر شمارش متفاوتی میدهد.
شمارش یک درخواست چت
model و messages را بفرستید، و اگر درخواست ابزار دارد tools را هم، دقیقاً همانطور که به /v1/chat/completions میفرستید. پاسخ اندازه کل ورودی است.
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
} فیلدهای /v1/tokenize
| فیلد | نوع | توضیحات |
|---|---|---|
model | string | الزامی. id یک مدل open-weight میزبانیشده. حروف بزرگ و کوچک یکسان در نظر گرفته میشوند. |
text | string | متنی که همانطور که هست شمرده شود، بدون قالببندی چت. تا 4,000,000 بایت. text یا messages را بفرستید؛ اگر هر دو باشند، text شمرده میشود. |
messages | array | پیامهای چت در قالب Chat Completions. بهعنوان کل ورودی یک درخواست شمرده میشوند: هر پیام با قالببندیای که قالب چت مدل دور آن میگذارد. |
tools | array | تعریف ابزارهایی که باید در شمارش بیایند. همراه با messages استفاده میشود. |
پاسخ یک شیء JSON با این فیلدهاست:
| فیلد | نوع | توضیحات |
|---|---|---|
model | string | id مدلی که شمارش برای آن انجام شد، با املای منتشرشده آن. |
tokens | integer | با text: توکنهای متن. با messages: توکنهای کل ورودی، تصاویر هم شامل آن است. |
شمارش یک درخواست Messages
همان بدنهای را بفرستید که به /v1/messages میفرستید: model، messages، و در صورت استفاده system و tools. SDKهای رسمی Anthropic این endpoint را با 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
} فیلدهای endpoint شمارش /v1/messages/count_tokens
| فیلد | نوع | توضیحات |
|---|---|---|
model | string | الزامی. id یک مدل open-weight میزبانیشده. |
messages | array | الزامی. پیامها در قالب Anthropic Messages. بلوکهای text، image، tool_use و tool_result شمرده میشوند. |
system | string | array | پرامپت سیستم: یک رشته یا آرایهای از بلوکهای متن. |
tools | array | تعریف ابزارها با name، description و input_schema. |
برای سازگاری پذیرفته میشوند و روی شمارش اثری ندارند: tool_choice, max_tokens, temperature, top_p, stop_sequences, stream, thinking. میتوانید بدنه یک درخواست واقعی را بدون تغییر بفرستید.
پاسخ یک شیء JSON با این فیلدهاست:
| فیلد | نوع | توضیحات |
|---|---|---|
input_tokens | integer | توکنهای کل ورودی: پرامپت سیستم، پیامها، ابزارها و تصاویر. |
مدلهای پشتیبانیشده
هر دو endpoint برای مدلهای open-weight میزبانیشده میشمارند. GET /v1/models مقدارهای /v1/tokenize و /v1/messages/count_tokens را در endpoints هر مدلی که از آنها پشتیبانی میکند فهرست میکند. هر مقدار model دیگری، از جمله idهای Shannon، با 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
برای مدل Shannon، تعداد توکنها را از شیء usage پاسخ بخوانید.
شمارش چگونه انجام میشود
هر مدل با توکنایزر و قالب چت مخصوص خودش شمرده میشود. هیچ تخمینی از روی نویسهها یا کلمهها به کار نمیرود.
| چه چیزی شمرده میشود | قاعده |
|---|---|
| یک متن | توکنهای رشته به همان شکلی که فرستاده شده. رشته خالی 0 شمرده میشود. |
| پیامها | پیامها و ابزارها با قالب چت خود مدل چیده میشوند، تا نقطهای که پاسخ شروع میشود، و کل آن پرامپت شمرده میشود. |
| نقشها | پیامهای system، user، assistant و tool شمرده میشوند. developer مانند system شمرده میشود. پیامی که نه محتوا دارد و نه فراخوانی ابزار، چیزی اضافه نمیکند. |
| فراخوانیها و نتایج ابزار | فراخوانیهای ابزار در نوبتهای قبلی assistant و نتایج آنها در هر دو endpoint جزو شمارش هستند. |
| تصاویر | تصویری که داخل بدنه فرستاده شود (base64 یا URL از نوع data:) به ازای هر تکه 28 × 28 پیکسل یک توکن اضافه میکند: ceil(width / 28) × ceil(height / 28). تصویری که بهصورت URL از نوع http(s) داده شود توسط این endpointها دانلود نمیشود و 1,024 شمرده میشود. |
مثال: تصویری 1,024 × 768 پیکسل برابر ceil(1024 / 28) × ceil(768 / 28) = 37 × 28 = 1,036 توکن شمرده میشود.
شمارش و آنچه از یک درخواست محاسبه میشود
شمارش یک درخواست کامل به همان روشی انجام میشود که ورودی یک درخواست واقعی با همان مدل، پیامها و ابزارها شمرده میشود. پاسخ این عدد را در Chat Completions بهصورت usage.prompt_tokens، در Responses بهصورت usage.input_tokens، و در Messages بهصورت usage.input_tokens بهعلاوه usage.cache_read_input_tokens گزارش میکند.
- این شمارش ورودی پیش از تخفیف ورودی کششده است. یک درخواست واقعی ممکن است بخشی از آن ورودی را از کش بخواند و آن بخش را با نرخ کششده محاسبه کند. کش کردن پرامپت
- تصویری که بهصورت URL از نوع
http(s)داده شود اینجا 1,024 شمرده میشود. درخواست واقعی تصویر را دانلود میکند و از روی اندازه آن بر حسب پیکسل میشمارد، پس دو عدد ممکن است فرق کنند. تصویر را بهصورت base64 بفرستید تا همان عدد را بگیرید. - خروجی جزو شمارش نیست. پاسخ یک درخواست واقعی علاوه بر آن بهصورت توکن خروجی محاسبه میشود، استدلال هم شامل آن است.
- شمارش
textقالببندی چت ندارد. از آن برای اندازهگیری یک سند یا بخشی از پرامپت استفاده کنید، و از شکلmessagesبرای اندازهگیری یک درخواست.
برای تبدیل یک شمارش به هزینه، آن را در قیمت ورودی مدل به ازای هر 1M توکن ضرب کنید. مدلها و قیمتها
محدودیتها
| حد | مقدار | بالاتر از آن |
|---|---|---|
طول text | 4,000,000 بایت (UTF-8) | 413 با پیام text too long |
| بدنه درخواست | 32 MiB | 413 |
| در هر درخواست | یک متن یا یک گفتگو | برای شمارش چند متن، برای هر متن یک درخواست بفرستید. |
فراخوانیهای شمارش در حد 120 درخواست در دقیقه حساب نمیشوند. محدودیتها و موجودی
خطاها
| وضعیت | نوع | پیام | چه زمانی |
|---|---|---|---|
400 | invalid_request_error | tokenize is available for the hosted open models; unknown model: <model> | /v1/tokenize با یک model که id مدل open-weight میزبانیشده نیست. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <model> | /v1/messages/count_tokens با یک model که id مدل open-weight میزبانیشده نیست، یا بدون model. |
400 | invalid_request_error | send `text` or `messages` | /v1/tokenize بدون text و بدون messages. |
401 | authentication_error | Missing authentication / Invalid API key | کلیدی فرستاده نشده، یا کلید معتبر نیست. |
413 | invalid_request_error | text too long | text از 4,000,000 بایت بلندتر است. بدنه بزرگتر از 32 MiB هم با 413 پاسخ داده میشود. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | درخواست content type از نوع JSON ندارد. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | یک فیلد الزامی نیست (model در /v1/tokenize، messages در /v1/messages/count_tokens) یا نوع یک فیلد اشتباه است. |
503 | api_error | token counting is temporarily unavailable for this model | شمارش برای این مدل در حال حاضر ممکن نیست. بعداً دوباره امتحان کنید. |
/v1/tokenize خطاها را در شکل OpenAI برمیگرداند. در /v1/messages/count_tokens خطاهای خود endpoint (400 برای مدل، 503) در شکل Anthropic میآیند، و 401، 413، 415 و 422 در شکل OpenAI. ابتدا کد وضعیت را بخوانید، سپس error.type و error.message را که در هر دو شکل هستند.
{
"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"
}
}