رفتن به محتوا
شمارش توکن

شمارش توکن

توکن‌های یک متن یا یک درخواست کامل را پیش از ارسال بشمارید.

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"])
200 پاسخ
{
  "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"])
200 پاسخ
{
  "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)
200 پاسخ
{
  "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-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

برای مدل 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 را که در هر دو شکل هستند.

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