Token 计数

POST /v1/messages/count_tokens  compatible  语义操作 generate  契约修订 1

状态语义：stateless; served natively against one direct Anthropic connection

查看原始契约偏差（英文）

这些是源码契约中的逐条证据。日常接入先看本页示例、字段表和 Profile 覆盖矩阵；排查兼容性边界时 再展开核对原文。

• only the direct Anthropic Messages provider profile serves this endpoint; Bedrock Mantle shares the Messages wire format but its count_tokens surface is not established
• the request body reaches the provider verbatim with only the upstream model identifier substituted, so there is no portable execution mode to select
• Anthropic does not bill count_tokens, and Halro settles it at zero cost — but it is a real provider call on the operator’s credential, so it takes a ledger attempt and appears in the audit trail like any other
• the reported count is Anthropic’s, for the upstream model behind the alias; it is not re-derived by Halro

在真正发出请求之前估算 token 数。这个端点不支持流式（stream 会被拒）， 也不接受 Halro-Route-Mode: portable。

固定每请求费用仍会结算

Count Tokens 没有 input/output token 计费跨度；普通按 Token 价格结算为 0，但 Price Version 若配置 fixed per-request fee，该固定费用仍会进入账本。

请求示例

curl

curl https://halro.example.com/v1/messages/count_tokens \
  -H "x-api-key: $HALRO_GATEWAY_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude",
        "messages": [{"role": "user", "content": "你好"}] }'

Python

import os
from anthropic import Anthropic

client = Anthropic(base_url="https://halro.example.com", api_key=os.environ["HALRO_GATEWAY_KEY"],
                   timeout=60.0, max_retries=0)
count = client.messages.count_tokens(
    model="claude",
    messages=[{"role": "user", "content": "你好"}],
)
print(count.input_tokens)

Node.js

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://halro.example.com", apiKey: process.env.HALRO_GATEWAY_KEY,
  timeout: 60_000, maxRetries: 0,
});
const count = await client.messages.countTokens({
  model: "claude",
  messages: [{ role: "user", content: "你好" }],
});
console.log(count.input_tokens);

SDK 默认会自动重试

官方 SDK 默认会重试 2 次。Halro 在发出上游请求之前就把预算预留落盘，因此客户端的 静默重试会产生多次独立的预留与结算。示例把它关掉，由你自己决定重试策略 —— 见重试、超时与幂等。

请求头

• x-api-key or Authorization
• anthropic-version
• anthropic-beta
• Content-Type

请求字段

怎么读这张表

第 2 列沉默不等于支持 —— 契约只记录已声明的限制，没列出的 Profile 是「未声明限制」， 不是「已验证支持」。第 3 列是组合级限制：某些拒绝规则在字段粒度上表达不出来 （例如某个 Profile 拒绝「带工具的流式请求」，而 tools 与 stream 单看都支持）。 字段的类型、是否必填与语义说明当前不在契约里，见页脚说明。

请求字段

字段	不支持该字段的 Provider Profile	组合级限制
model	—	—
messages	—	—
messages[].role	—	—
messages[].content	—	—
system	—	—
tools	—	—
tool_choice	—	—
thinking	—	—
output_config	—	—

门面层直接拒绝的字段

这些字段在到达任何 Provider 之前就会被拒。照搬 OpenAI 文档最容易撞上的就是它们：

• stream
• Halro-Route-Mode: portable
• unknown top-level fields

响应字段

input_tokens

Provider Profile 契约覆盖与本构建可用性

端点成熟度不提升单个 Profile

顶部的 compatible 徽章说的是端点，不是下面每一行。每行的成熟度取自该 Profile 自己的覆盖记录。

Provider Profile 契约覆盖与本构建可用性

Provider Profile	成熟度	本构建	不支持的请求字段
anthropic.messages.2023-06-01	compatible	可创建	未声明

已声明的变换

anthropic.messages.2023-06-01

• 操作结论：原生模式只替换模型标识，其余字段原样转发；调用方必须确保正文完全符合所选 Provider 的原生协议。 原始契约：only the model identifier is substituted; every other member is forwarded unchanged

证据

已验证的证据：gateway_contract、provider_transport_fixture、sdk_blackbox

SDK 黑盒协议桩矩阵

anthropic-go、anthropic-typescript、anthropic-python

警告

该矩阵只证明这些 SDK 版本能序列化请求、并消费 Halro 声明的响应与流形状。它跑的是协议桩， 不经过真实 Runtime 路由、Gateway Key 认证、路由选择、能力过滤、脱敏与预算核算， 不能被引为端到端网关或真实 Provider 的证据。

最佳实践

计数与实际治理准入的边界见案例十。

---

本页的字段表、覆盖矩阵与偏差列表由 Halro 08af8c8b0b10 的兼容性契约生成 （scripts/generate-api-pages.mjs，当前副本摘要 db249a88ce62e5b7…）。

字段的类型、是否必填与语义说明尚未进入契约，因此本页只列字段名。