דילוג לתוכן
ספירת טוקנים

ספירת טוקנים

ספרו את הטוקנים של טקסט או של בקשה שלמה לפני ששולחים אותם.

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

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

שני ה-endpoints סופרים עם ה-tokenizer של המודל שאתם נוקבים בו, ושום מודל אינו רץ. הם מכסים את מודלי ה-open-weight המתארחים. /v1/tokenize מקבל טקסט פשוט או שיחת Chat Completions. /v1/messages/count_tokens מקבל בקשה בפורמט Anthropic Messages, שהיא הקריאה ש-SDK של Anthropic ו-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 חובה. מזהה של מודל open-weight מתארח. אותיות גדולות וקטנות מטופלות באותו אופן.
text string טקסט לספירה כמות שהוא, בלי עיצוב צ'אט. עד 4,000,000 בייטים. שלחו text או messages; כששניהם קיימים, text נספר.
messages array הודעות צ'אט בפורמט Chat Completions. הן נספרות כקלט המלא של בקשה: כל הודעה עם העיצוב שתבנית הצ'אט של המודל שמה סביבה.
tools array הגדרות כלים שייכללו בספירה. משמשות יחד עם messages.

התשובה היא אובייקט JSON עם השדות האלה:

שדה סוג תיאור
model string מזהה המודל שהספירה נעשתה עבורו, באיות שפורסם.
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
}

השדות של הבקשה ל-/v1/messages/count_tokens

שדה סוג תיאור
model string חובה. מזהה של מודל open-weight מתארח.
messages array חובה. הודעות בפורמט Anthropic Messages. בלוקי text, image, tool_use ו-tool_result נספרים.
system string | array ה-system prompt: מחרוזת או מערך של בלוקי טקסט.
tools array הגדרות כלים עם name, description ו-input_schema.

מתקבלים לשם תאימות, בלי השפעה על הספירה: tool_choice, max_tokens, temperature, top_p, stop_sequences, stream, thinking. אפשר להעביר את הגוף של בקשה אמיתית ללא שינוי.

התשובה היא אובייקט JSON עם השדות האלה:

שדה סוג תיאור
input_tokens integer הטוקנים של כל הקלט: system prompt, הודעות, כלים ותמונות.

מודלים נתמכים

שני ה-endpoints סופרים עבור מודלי ה-open-weight המתארחים. GET /v1/models מפרט את /v1/tokenize ואת /v1/messages/count_tokens ב-endpoints של כל מודל שתומך בהם. כל ערך model אחר, כולל מזהי 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 של תשובה.

איך הספירה נעשית

כל מודל נספר עם ה-tokenizer שלו ועם תבנית הצ'אט שלו. לא נעשה שימוש בהערכה לפי תווים או מילים.

מה נספר כלל
טקסט הטוקנים של המחרוזת כפי שנשלחה. מחרוזת ריקה נספרת 0.
הודעות ההודעות והכלים מסודרים בתבנית הצ'אט של המודל עצמו, עד הנקודה שבה התשובה מתחילה, וכל הפרומפט הזה נספר.
תפקידים הודעות system, user, assistant ו-tool נספרות. developer נספר כ-system. הודעה בלי תוכן ובלי קריאה לכלי אינה מוסיפה דבר.
קריאות לכלים ותוצאות קריאות לכלים בתורי assistant קודמים ותוצאותיהן הן חלק מהספירה, בשני ה-endpoints.
תמונות תמונה שנשלחת בתוך הגוף (base64 או data: URL) מוסיפה טוקן אחד לכל טלאי של 28 × 28 פיקסלים: ceil(width / 28) × ceil(height / 28). תמונה שניתנה ככתובת http(s) אינה מורדת על ידי ה-endpoints האלה ונספרת 1,024.

דוגמה: תמונה של 1,024 × 768 פיקסלים נספרת ceil(1024 / 28) × ceil(768 / 28) = 37 × 28 = 1,036 טוקנים.

הספירה ומה בקשה מחויבת

ספירה של בקשה שלמה נעשית באותה דרך כמו ספירת הקלט של בקשה אמיתית עם אותם מודל, הודעות וכלים. תשובה מדווחת על המספר הזה כ-usage.prompt_tokens ב-Chat Completions, כ-usage.input_tokens ב-Responses, וכ-usage.input_tokens ועוד usage.cache_read_input_tokens ב-Messages.

  • הספירה היא הקלט לפני ההנחה על קלט במטמון. בקשה אמיתית יכולה לקרוא חלק מהקלט הזה מהמטמון ולחייב את החלק הזה בתעריף המטמון. מטמון פרומפטים (Prompt caching)
  • תמונה שניתנה ככתובת http(s) נספרת כאן 1,024. בקשה אמיתית מורידה את התמונה וסופרת אותה לפי גודלה בפיקסלים, ולכן שני המספרים יכולים להיות שונים. שלחו את התמונה כ-base64 כדי לקבל את אותו מספר.
  • הפלט אינו חלק מהספירה. התשובה של בקשה אמיתית מחויבת כטוקני פלט נוספים, כולל reasoning.
  • לספירת 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 שאינו מזהה של open-weight מתארח.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <model> /v1/messages/count_tokens עם model שאינו מזהה של 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"
  }
}