# 统计 Messages 请求 token 数

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volces.com/api/compatible/v1/messages/count_tokens`

统计 Messages 请求的输入 token 数，可用于请求预估、配额控制和成本测算。实际用量以真实请求结果为准。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**messages** `object[]` `必选` | 消息列表

**content** `string / object[]` `必选` | 消息内容

`messages.content`

纯文本消息内容 `string`

结构化消息内容 `object[]`

文本内容块 `object`

**text** `string` `必选` | 文本内容

`messages.content.text`

**type** `string` `必选` | 内容块类型

`messages.content.type`

取值固定为 `text`。

思考内容块 `object`

**type** `string` `必选` | 内容块类型

`messages.content.type`

取值固定为 `thinking`。

**signature** `string` | 用于回放思考内容的不透明签名

`messages.content.signature`

当 `type=thinking` 时必填，用于标识并校验该思考内容块。需将该字段与 `thinking` 字段一起完整回传，并保持字段值及内容块顺序不变。

**thinking** `string` | 模型的思考内容

`messages.content.thinking`

图片内容块 `object`

**source** `object` `必选` | 图片来源

`messages.content.source`

**type** `string` `必选` | 图片传入方式

`messages.content.source.type`

* `type=url`：`url` 为必填。
* `type=base64`：`data` 和 `media_type` 为必填。

**data** `string` | 图片数据

`messages.content.source.data`

当 `type=base64` 时传入。

**media_type** `string` | 媒体类型

`messages.content.source.media_type`

当 `type=base64` 时，与 `data` 一起传入。

**url** `string` | 图片 URL

`messages.content.source.url`

当 `type=url` 时传入。

**type** `string` `必选` | 内容块类型

`messages.content.type`

取值固定为 `image`。

文档内容块 `object`

**source** `object` `必选` | 文档来源

`messages.content.source`

**type** `string` `必选` | 文档传入方式

`messages.content.source.type`

支持通过 `url`、`base64`、`text` 或 `content` 四种方式传入文档。

* `type=url`：`url` 为必填。
* `type=base64` 或 `type=text`：`data` 为必填。
* `type=content`：`content` 为必填。

**content** `string / object[]` | 文档内容

`messages.content.source.content`

当 `type=content` 时传入。

该字段支持递归嵌套。为避免重复展示，此处不再继续展开。

**data** `string` | 文档数据

`messages.content.source.data`

当 `type` 为 `base64` 或 `text` 时传入。

**url** `string` | 文档 URL

`messages.content.source.url`

当 `type=url` 时传入。

**type** `string` `必选` | 内容块类型

`messages.content.type`

取值固定为 `document`。

工具调用内容块 `object`

**id** `string` `必选` | 工具调用的 ID

`messages.content.id`

**input** `object` `必选` | 模型为该工具生成的输入参数

`messages.content.input`

**name** `string` `必选` | 被调用的工具名称

`messages.content.name`

**type** `string` `必选` | 内容块类型

`messages.content.type`

取值固定为 `tool_use`。

工具结果内容块 `object`

**content** `string / object[]` `必选` | 工具返回的内容

`messages.content.content`

纯文本工具结果 `string`

结构化工具结果 `object[]`

文本内容块 `object`

**text** `string` `必选` | 文本内容

`messages.content.content.text`

**type** `string` `必选` | 内容块类型

`messages.content.content.type`

取值固定为 `text`。

图片内容块 `object`

**source** `object` `必选` | 图片来源

`messages.content.content.source`

**type** `string` `必选` | 图片传入方式

`messages.content.content.source.type`

* `type=url`：`url` 为必填。
* `type=base64`：`data` 和 `media_type` 为必填。

**data** `string` | 图片数据

`messages.content.content.source.data`

当 `type=base64` 时传入。

**media_type** `string` | 媒体类型

`messages.content.content.source.media_type`

当 `type=base64` 时，与 `data` 一起传入。

**url** `string` | 图片 URL

`messages.content.content.source.url`

当 `type=url` 时传入。

**type** `string` `必选` | 内容块类型

`messages.content.content.type`

取值固定为 `image`。

工具引用内容块 `object`

**tool_name** `string` `必选` | 引用的工具名称

`messages.content.content.tool_name`

**type** `string` `必选` | 内容块类型

`messages.content.content.type`

取值固定为 `tool_reference`。

**tool_use_id** `string` `必选` | 该结果所对应的工具调用 ID

`messages.content.tool_use_id`

**type** `string` `必选` | 内容块类型

`messages.content.type`

取值固定为 `tool_result`。

服务端工具调用内容块 `object`

**id** `string` `必选` | 服务端托管工具调用的公开 ID

`messages.content.id`

**input** `object` `必选` | 模型为该工具生成的输入参数

`messages.content.input`

**name** `string` `必选` | 被调用的服务端托管工具名称

`messages.content.name`

**type** `string` `必选` | 内容块类型

`messages.content.type`

取值固定为 `server_tool_use`。

联网搜索结果内容块 `object`

**content** `object[] / object` `必选` | 联网搜索结果内容

`messages.content.content`

联网搜索结果列表 `object[]`

**encrypted_content** `string` `必选` | 加密内容

`messages.content.content.encrypted_content`

**title** `string` `必选` | 结果标题

`messages.content.content.title`

**type** `string` `必选` | 结果类型

`messages.content.content.type`

取值固定为 `web_search_result`。

**url** `string` `必选` | 结果 URL

`messages.content.content.url`

**page_age** `string` | 页面时效

`messages.content.content.page_age`

联网搜索错误结果 `object`

**error_code** `string` `必选` | 错误码

`messages.content.content.error_code`

**type** `string` `必选` | 结果类型

`messages.content.content.type`

取值固定为 `web_search_tool_result_error`。

**tool_use_id** `string` `必选` | 该结果所对应的服务端工具调用 ID

`messages.content.tool_use_id`

**type** `string` `必选` | 内容块类型

`messages.content.type`

取值固定为 `web_search_tool_result`。

**caller** `object` | 服务端调用方

`messages.content.caller`

**type** `string` `必选` | 标识生成该结果的服务端调用方

`messages.content.caller.type`

**role** `string` `必选` | 角色

`messages.role`

输入消息的角色，决定指令的优先级层级。可选值：`user`、`system`、`assistant`、`developer`。

**model** `string` `必选` | 模型 ID

本次请求调用的模型 ID（Model ID），用于指定处理输入内容的模型。

> **说明**
>
> - 开通模型服务并查询 Model ID，请参见 [模型列表](/docs/model-list)。
> - 若需要多个应用分别调用模型服务或做更细粒度的权限管理，可改传 Endpoint ID（在线推理接入点的 ID），详细请参考 [获取 Endpoint ID](/docs/online-inference-standard)。

**max_tokens** `integer` | 最大输出 token 数

**output_config** `object` | 输出配置

**effort** `string` | 思考深度

`output_config.effort`

限制思考的工作量。减少思考深度可提升速度，思考花费的 token 更少。

* `none`：关闭思考。
* `minimal`：关闭思考，直接回答。
* `low`：轻量思考，侧重快速响应。
* `medium`：均衡模式，兼顾速度与深度。
* `high`：深度分析，处理复杂问题。
* `xhigh`：更高程度思考。
* `max`：最高程度思考，适配高难度推理任务。

> **注意：说明**
>
> 支持该字段的模型、默认取值、参数兼容映射规则，以及与 `thinking.type` 字段的关系，详见 [文档](/docs/deep-thinking)。

**output_format** `object` | 输出格式

**type** `string` `必选` | 输出格式类型

`output_format.type`

支持 `text`、`json_object` 和 `json_schema` 三种输出格式。

* `text`：返回文本格式结果。
* `json_object`：返回 JSON 对象格式结果。
* `json_schema`：按 JSON Schema 约束返回结果，此时 `schema` 为必填。

**schema** `object` | JSON Schema

`output_format.schema`

当 `type=json_schema` 时传入。

**service_tier** `string` `默认值 default` | 推理模式

控制使用的在线推理模式。

- `default`：使用 [在线推理（常规）](/docs/online-inference-standard)。
- `flex`：使用 [在线推理（低优）](/docs/online-inference-flex)。

**stop_sequences** `string / string[]` | 停止序列

支持传入单个字符串，或最多 `4` 个停止序列。

**stream** `boolean` | 响应内容是否流式返回

* `true`：按 SSE 协议逐块返回模型生成内容。
* `false`：模型生成完成后一次性返回结果。

**system** `string / object[]` | 系统提示词

支持直接传字符串，或传由 `text` 内容块组成的数组。

纯文本系统提示词 `string`

结构化系统提示词 `object[]`

**text** `string` `必选` | 文本内容

`system.text`

**type** `string` `必选` | 内容块类型

`system.type`

取值固定为 `text`。

**temperature** `number` | 采样温度

**取值范围**：`[0, 2]`

**thinking** `object` | 深度思考配置

**type** `string` `必选` | 思考模式

`thinking.type`

* `disabled`：关闭深度思考。
* `enabled`：开启深度思考。
* `adaptive`：由模型自动决定是否开启深度思考。

**tool_choice** `object` | 工具调用策略

配置 `tools` 后再设置该参数。

自动选择是否调用工具 `object`

**type** `string` `必选` | 策略类型

`tool_choice.type`

取值固定为 `auto`。

**disable_parallel_tool_use** `boolean` | 是否禁用并行工具调用

`tool_choice.disable_parallel_tool_use`

* `true`：模型在同一轮中不会并行调用多个工具。
* `false`：模型可在同一轮中并行调用多个工具。

当前不保证一定会调用工具，不同模型的保障效果不同 `object`

**type** `string` `必选` | 策略类型

`tool_choice.type`

取值固定为 `any`。

**disable_parallel_tool_use** `boolean` | 是否禁用并行工具调用

`tool_choice.disable_parallel_tool_use`

* `true`：模型在同一轮中不会并行调用多个工具。
* `false`：模型可在同一轮中并行调用多个工具。

不调用工具 `object`

**type** `string` `必选` | 策略类型

`tool_choice.type`

取值固定为 `none`。

强制调用指定工具 `object`

**name** `string` `必选` | 模型必须调用的工具名称

`tool_choice.name`

**type** `string` `必选` | 策略类型

`tool_choice.type`

取值固定为 `tool`。

**disable_parallel_tool_use** `boolean` | 是否禁用并行工具调用

`tool_choice.disable_parallel_tool_use`

* `true`：模型在同一轮中不会并行调用多个工具。
* `false`：模型可在同一轮中并行调用多个工具。

**tools** `object[]` | 工具列表

用户自定义工具 `object`

**name** `string` `必选` | 工具名称

`tools.name`

**description** `string` | 工具说明

`tools.description`

描述工具的用途以及模型应在何时调用。

**input_schema** `object` | 工具输入 Schema

`tools.input_schema`

服务端工具 `object`

当前仅支持原生联网搜索 `web_search`。

**type** `string` `必选` | 工具类型

`tools.type`

兼容 Anthropic 原生 Web Search 工具的版本化类型值。例如：`web_search_20250305`。

具体可用版本请参见 [Anthropic Web Search 工具文档](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)。

**name** `string` | 工具名称

`tools.name`

当前服务端工具可填写 `web_search`。

**max_uses** `integer` | 最大调用次数

`tools.max_uses`

**allowed_domains** `string[]` | 允许访问的域名列表

`tools.allowed_domains`

**blocked_domains** `string[]` | 禁止访问的域名列表

`tools.blocked_domains`

**user_location** `object` | 用户位置信息

`tools.user_location`

当前传入该参数会被忽略，不生效。

**top_p** `number` | 核采样概率

**取值范围**：`[0, 1]`

## 响应参数

**input_tokens** `integer` | 输入消息对应的 token 数


## 代码示例

## 默认

### cURL


#### Request

```bash
curl https://ark.cn-beijing.volces.com/api/compatible/v1/messages/count_tokens \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ARK_API_KEY" \
  -d '{
    "model": "doubao-seed-2-1-pro-260915",
    "system": "You are a scientist.",
    "messages": [
      {
        "role": "user",
        "content": "Hello, Ark"
      }
    ]
  }'
```

#### Response

```
{
  "input_tokens": 23
}
```