POST /v1/tokenizers/estimate-token-count 接口用于预估请求的 token 消耗，输入格式与 chat completions 完全一致，支持文本和图片/视频多模态内容。适合在批量任务前预算 token 费用，或避免超出模型上下文窗口。

Kimi Token 预估接口

接口信息

POST https://api.moonshot.cn/v1/tokenizers/estimate-token-count
Authorization: Bearer {MOONSHOT_API_KEY}
Content-Type: application/json

---

文本消息预估

curl https://api.moonshot.cn/v1/tokenizers/estimate-token-count \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "messages": [
      {"role": "system", "content": "你是一个助手。"},
      {"role": "user", "content": "帮我总结这段文字..."}
    ]
  }'

import os
import requests

response = requests.post(
    "https://api.moonshot.cn/v1/tokenizers/estimate-token-count",
    headers={
        "Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k2.6",
        "messages": [
            {"role": "system", "content": "你是一个助手。"},
            {"role": "user", "content": "帮我总结这段文字..."},
        ],
    },
)

data = response.json()
print(f"预估 token 数: {data['data']['total_tokens']}")

---

多模态（图片）预估

import base64

with open("image.png", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.moonshot.cn/v1/tokenizers/estimate-token-count",
    headers={
        "Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k2.6",
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "image_url",
                        "image_url": {"url": f"data:image/png;base64,{base64_image}"},
                    },
                    {"type": "text", "text": "描述这张图片"},
                ],
            }
        ],
    },
)

total_tokens = response.json()["data"]["total_tokens"]
print(f"图片预估 token 数: {total_tokens}")

---

TypeScript 封装示例

async function estimateTokens(
  messages: any[],
  model = "kimi-k2.6"
): Promise<number> {
  const response = await fetch(
    "https://api.moonshot.cn/v1/tokenizers/estimate-token-count",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ model, messages }),
    }
  );

  const data = await response.json();
  return data.data.total_tokens;
}

// 在发送请求前检查 token 限制
const tokens = await estimateTokens(messages);
if (tokens > 200000) {
  console.warn(`消息过长 (${tokens} tokens)，超出 200k 上下文限制`);
}

---

常见问题

Q: 预估结果与实际消耗完全一致吗？

A: 预估值通常与实际消耗非常接近，但可能存在小幅偏差（< 1%），主要来自模型内部的分词差异。用于预算估算和上下文限制检查完全可靠。

Q: 为什么要用预估接口而不是直接发请求试试？

A: 超出上下文窗口的请求会直接报错，浪费一次 API 调用。对于大文件（如上传的 PDF）注入上下文的场景，预估可以提前判断是否需要拆分文档。

Q: 预估接口是否免费？

A: 是的，token 预估接口不计费，可以频繁调用。但每次预估本身会消耗一定的服务器资源，建议只在需要时调用（如批处理前的批量预估），避免不必要的高频请求。