火山方舟
火山方舟
API参考
请输入
- 文档首页
火山方舟管控面 API管理模型用量查询推理用量
复制全文
下载 pdf查询推理用量
文档反馈
问问助手POST https://ark.cn-beijing.volcengineapi.com/?Action=GetInferenceUsage&Version=2024-01-01
查询推理用量，支持按时间范围、接入点、模型等多维度过滤，返回 token 消耗及请求数等用量数据。
鉴权
- Access Key 鉴权，请在 Access Key 管理 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。
请求参数
Body 参数
EndTime string 必选 | 结束日期
查询结束日期，格式为 yyyy-MM-dd，时区为北京时间（UTC+8）。需大于等于 StartTime。
QueryInterval string 必选 | 查询粒度
查询粒度。可取值：
- Day：按天统计
- Hour：按小时统计
StartTime string 必选 | 起始日期
查询起始日期，格式为 yyyy-MM-dd，时区为北京时间（UTC+8）。
Filters object[] | 过滤条件
过滤条件数组，支持按鉴权 token、模型名称、接入点 ID、批量任务 ID 等字段过滤。多个过滤项之间为「与」关系。
Key string 必选 | 过滤字段
Filters.Key
过滤字段。目前支持：
注意
由于安全升级，用量查询能力将调整为基于 ApiKeyID 的查询方式。
- 2026-08-12 及之后创建的 API Key，仅支持通过 ApiKeyID 查询用量，不再支持 AuthToken 查询方式。
- 2026-08-12 之前创建的存量 API Key，当前同时兼容 AuthToken 与 ApiKeyID 两种用量查询方式；其中 AuthToken 查询方式即将下线。为避免业务受影响，请您尽快将业务逻辑切换至 ApiKeyID 进行用量查询。
- AuthToken：鉴权 token。
- 若为 jwt token 鉴权，则默认为 ****
- 若为 apikey 鉴权：
- 传统格式 API Key：取前 8 位 + **** + 后 12 位字符，示例：37efcc63****92c8fe4c880e
- 新版方舟 API Key：取前 3 位 + **** + 后 5 位字符，示例：ark****d5b88
- ApikeyID：API Key 对应的资源 ID
说明
在按 API Key 维度统计用量的场景中，会出现不同命名，实际指向同一个 API Key 唯一标识，仅命名存在差异，对应关系如下：
- 资源 ID（Resource ID）：火山方舟控制台 API Key 管理 页面展示的列名。
- ApikeyID / apikey_id：分账账单系统中的分账维度名称，以及查账单 API 过滤条件 Filters 的键名。
您可以前往方舟控制台的 API Key 管理 页面，在对应 API Key 的详情中查看并复制“资源 ID”。请注意，资源 ID 并非 API Key 密钥本身，请勿将 API Key 密钥作为 ApiKeyID 传入。
- ModelUnitID：模型单元 ID
- BillingStatus：计费方式。可取值：no_need_billing（无需付费，一般为客户未开通前体验的用量）、free_for_model_unit（模型单元用量）、free_for_free_quota / free_for_limit_boundary（超过安心体验边界的用量）、normal（正常后付费按量计费）、free_for_viptier（TPM 保障包用量）
- ModelName：模型名称
- ModelVersion：模型版本
- ModelEndpoint：接入点 ID
- BatchJobID：批量任务 ID
- BatchType：批量推理类型
ValueLike string 必选 | 相似匹配值
Filters.ValueLike
相似匹配值，按前缀/包含等近似规则过滤。Values 与 ValueLike 不能同时传递。
Values string[] 必选 | 过滤值列表
Filters.Values
过滤值列表。若 Values 长度为 0，则表示不按 Key 过滤，但返回结果列中仍包含该 Key。
ProjectName string 默认值 default | 项目名称
资源所属的项目名称。若资源不在默认项目中，需填写正确的项目名称。
ShowWindowDetail boolean 默认值 false | 展示窗口详情
是否在返回结果中展示计费窗口详情（如窗口序列、窗口描述、窗口 token 上限等）。
响应参数
Data string[] | 用量数据
用量数据，二维数组。每行对应一条记录，列顺序与 Fields 一致。
DataCount integer | 数据行数
返回的数据行数，即 Data 数组的长度。
Fields object[] | 列定义
返回数据的列定义，描述 Data 数组中每一列的类型与名称。
Name string | 列名称
Fields.Name
列名称。包括请求参数 Filters 内的所有字段。默认包括：
- AccountID：账户 ID
- Day：日期
- Hour：小时
- InputTokens：输入 token 数
- OutputTokens：输出 token 数
- TotalTokens：总 token 数
- ReqCnt：请求数
若返回按窗口划分的数据，则额外包含：
- BillingStatus：计费类型
- WindowMatchOrder：窗口序列
- WindowDescription：窗口描述
- WindowMaxInputTokens：窗口输入 token 上限
- WindowMaxOutputTokens：窗口输出 token 上限
Type string | 列类型
Fields.Type
列数据类型，如 string、integer 等。
默认
Request
cURL
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=GetInferenceUsage&Version=2024-01-01' \
-H 'Content-Type: application/json' \
-H 'X-Date: <X-Date>' \
-H 'X-Content-Sha256: <X-Content-Sha256>' \
-H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
-d '{
"QueryInterval": "Hour",
"StartTime": "2025-09-17",
"EndTime": "2025-09-19",
"Filters": [
{
"Key": "ModelEndpoint",
"Values": [
"ep-20xxxx-xxx"
]
}
]
}
'Response
{
"ResponseMetadata": {
"RequestId": "202509231425196F1F971FFFC20F544E6A",
"Action": "GetInferenceUsage",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Fields": [
{
"Name": "AccountID",
"Type": "BIGINT"
},
{
"Name": "ModelEndpoint",
"Type": "STRING"
},
{
"Name": "Day",
"Type": "DATE"
},
{
"Name": "Hour",
"Type": "STRING"
},
{
"Name": "InputTokens",
"Type": "BIGINT"
},
{
"Name": "OutputTokens",
"Type": "BIGINT"
},
{
"Name": "ImageCount",
"Type": "BIGINT"
},
{
"Name": "TotalTokens",
"Type": "BIGINT"
},
{
"Name": "ReqCnt",
"Type": "BIGINT"
}
],
"Data": [
[
"2100339946",
"ep-20xxxx-xxx",
"2025-09-18",
"16",
"3062",
"914",
"0",
"3976",
"1"
],
[
"2100339946",
"ep-20xxxx-xxx",
"2025-09-17",
"14",
"6955",
"1921",
"0",
"8876",
"4"
]
],
"DataCount": 2
}
}最近更新时间：2026.09.04 20:18:47
这个页面对您有帮助吗？
有用
有用
无用
无用