عدّ الـ tokens
عدّ tokens نص أو طلب كامل قبل أن ترسله.
POST https://api.shannon-ai.com/v1/tokenize
POST https://api.shannon-ai.com/v1/messages/count_tokens
تعدّ كلتا نقطتي النهاية بمُجزّئ النموذج الذي تسميه، ولا يعمل أي نموذج. وهما تغطيان النماذج المفتوحة الأوزان المستضافة. يقبل /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 | مطلوب. معرّف نموذج مفتوح الأوزان مستضاف. لا فرق بين الأحرف الكبيرة والصغيرة. |
text | string | نص يُعدّ كما هو، دون تنسيق دردشة. حتى 4,000,000 بايت. أرسل text أو messages؛ وعند وجودهما معاً يُعدّ text. |
messages | array | رسائل دردشة بصيغة Chat Completions. تُعدّ بوصفها المدخلات الكاملة للطلب: كل رسالة مع التنسيق الذي يضعه قالب الدردشة الخاص بالنموذج حولها. |
tools | array | تعريفات أدوات تُضمَّن في العدّ. تُستخدم مع messages. |
الرد كائن JSON بهذه الحقول:
| الحقل | النوع | الوصف |
|---|---|---|
model | string | معرّف النموذج الذي أُجري العدّ له، بصيغته المنشورة. |
tokens | integer | مع text: tokens النص. ومع messages: tokens المدخلات كلها، بما فيها الصور. |
عدّ طلب Messages
أرسل النص الذي سترسله إلى /v1/messages: model وmessages، وsystem وtools عند استخدامهما. وتستدعي Anthropic SDKs الرسمية نقطة النهاية هذه عبر 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 | مطلوب. معرّف نموذج مفتوح الأوزان مستضاف. |
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 | tokens المدخلات كلها: توجيهات النظام والرسائل والأدوات والصور. |
النماذج المدعومة
كلتا نقطتي النهاية تعدّان للنماذج المفتوحة الأوزان المستضافة. ويسرد 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، اقرأ أعداد الـ tokens من الكائن usage في الرد.
كيف يُجرى العدّ
يُعدّ كل نموذج بمُجزّئه الخاص (tokenizer) وبقالب الدردشة الخاص به. ولا يُستخدم أي تقدير من الأحرف أو الكلمات.
| ما يُعدّ | القاعدة |
|---|---|
| نص | tokens السلسلة النصية كما أُرسلت. والسلسلة الفارغة تُحسب 0. |
| الرسائل | تُرتَّب الرسائل والأدوات بقالب الدردشة الخاص بالنموذج، حتى النقطة التي يبدأ عندها الرد، ثم تُعدّ المطالبة كلها. |
| الأدوار | تُعدّ رسائل system وuser وassistant وtool. وتُعدّ developer كأنها system. والرسالة التي بلا محتوى وبلا استدعاء أداة لا تضيف شيئاً. |
| استدعاءات الأدوات ونتائجها | استدعاءات الأدوات في أدوار المساعد السابقة ونتائجها جزء من العدد، في نقطتي النهاية كلتيهما. |
| الصور | الصورة المرسلة داخل النص (base64 أو data: URL) تضيف token واحداً لكل رقعة 28 × 28 بكسل: ceil(width / 28) × ceil(height / 28). أما الصورة المعطاة كعنوان http(s) URL فلا تنزّلها نقطتا النهاية هاتان وتُحسب 1,024. |
مثال: صورة بحجم 1,024 × 768 بكسل تُحسب ceil(1024 / 28) × ceil(768 / 28) = 37 × 28 = 1,036 token.
العدد وما يُحاسَب عليه الطلب
يُجرى عدّ الطلب كاملاً بالطريقة نفسها التي يُحسب بها عدد المدخلات في طلب حقيقي بالنموذج والرسائل والأدوات نفسها. ويبلّغ الرد عن هذا الرقم بوصفه usage.prompt_tokens في Chat Completions، وusage.input_tokens في Responses، وusage.input_tokens زائد usage.cache_read_input_tokens في Messages.
- العدد هو المدخلات قبل خصم المدخلات المخبأة. وقد يقرأ الطلب الحقيقي جزءاً من تلك المدخلات من الذاكرة المؤقتة ويحاسب ذلك الجزء بسعر المخبأ. التخزين المؤقت للمطالبات
- الصورة المعطاة كعنوان
http(s)URL تُحسب هنا 1,024. أما الطلب الحقيقي فينزّل الصورة ويحسبها من حجمها بالبكسل، ولذلك قد يختلف الرقمان. أرسل الصورة بصيغة base64 لتحصل على الرقم نفسه. - المخرجات ليست جزءاً من العدد. ويُحاسَب رد الطلب الحقيقي بوصفه tokens مخرجات فوق ذلك، بما فيها الاستدلال.
- عدّ
textلا يتضمن تنسيق الدردشة. استخدمه لقياس مستند أو جزء من مطالبة، واستخدم صيغةmessagesلقياس طلب.
لتحويل العدد إلى تكلفة، اضربه في سعر المدخلات للنموذج لكل 1M token. النماذج والأسعار
الحدود
| الحد | القيمة | فوقه |
|---|---|---|
طول 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 ليس معرّف نموذج مفتوح الأوزان مستضاف. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <model> | /v1/messages/count_tokens مع model ليس معرّف نموذج مفتوح الأوزان مستضاف، أو بدون 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` | ليس للطلب نوع محتوى 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 تأتي أخطاء نقطة النهاية نفسها (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"
}
}