ספירת טוקנים
ספרו את הטוקנים של טקסט או של בקשה שלמה לפני ששולחים אותם.
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"]) 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 | חובה. מזהה של מודל 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) 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
} השדות של הבקשה ל-/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-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 של תשובה.
איך הספירה נעשית
כל מודל נספר עם ה-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, הקיימים בשתי הצורות.
{
"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"
}
}