面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/usage-and-diagnostics.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

用量与诊断

用量、账单与诊断：推理量、结算金额，以及健康检查与错误码归因。

  • usage 出推理量（近实时，5-30 分钟延迟），billing 出结算金额（T+1 财务口径），两者不可混用；
  • 遇到报错先用 doctor error 做错误码归因，再按建议分流到对应域；
  • doctor 还覆盖接入点 / 模型 / 指标专项诊断与 Ark 媒体来源特征验证。

billing#

查询火山引擎 ARK 拆分账单明细（结算金额、Token 用量计费），按账期月、月范围、Endpoint、API Key、产品编码等维度过滤。

  • 账单是财务口径：T+1 出账、按结算金额聚合，和 usage 域的近实时推理量是两个数据源；
  • 适用场景：对账、按 EP / API Key 拆账、按产品拆账、月度成本复核。

billing list#

列出 ARK 拆分账单明细（结算金额 × Token 用量），支持按账期月或月范围查询。默认按账号维度统计 ARK 账单（Product 自动锁定为 ARK 系列，排除 ark_subscription）；传 --endpoint/--apikey/--apikey-sid 可下钻，传 --split-dim 可按维度拆分账号级汇总，传 --product 可覆盖或扩展产品集合。

Bash
arkcli billing list
Flag 类型 说明
--start string（必填） 单个账期月，格式 YYYY-MM（最早 24 个月前）。单独使用即单月；与 --end 搭配表示区间。必填。
--end string 区间结束月份，格式 YYYY-MM（含当月）。省略则只查单月。区间最长 24 个月。
--day string 在 --start 内定位到某个 YYYY-MM-DD（上游的性能提示）。需要 --interval=day 或 --interval=detail；与 --end 区间不兼容
--interval string 聚合粒度：month（默认）| day | detail
--endpoint string 只统计指定 Endpoint ID（ep-...）。与 --apikey/--apikey-sid 互斥。
--apikey string 按 API Key 值过滤（ark-...）；shortcut 会通过 arkbff 自动解析为 apikey SID。与 --endpoint/--apikey-sid 互斥。
--apikey-sid string 按 API Key SID 过滤（apikey-{ts}-{xxx}，来自 arkcli api apikey.list）。跳过 arkbff 解析。与 --endpoint/--apikey 互斥。
--split-dim string 按维度拆分账号级账单：apikey | endpoint。留空 = 账号级汇总（默认）。设置 --endpoint/--apikey/--apikey-sid 时必须与隐含维度一致。
--product string_slice 按火山引擎产品编码过滤（可重复）。省略则查看全部产品；返回行的 Product 字段会告诉你该账号实际可用的编码。
--project string_slice 按项目 ID 过滤（可重复）。未设置时默认使用 profile 选定的项目（仅当 profile 无项目 / 为 'account-wide' 时跳过）；传 --project= 清空，或 --project 覆盖。
--instance-no string 只统计指定计费实例 ID
--bill-category string_slice 按账单类型过滤（可重复）：consume-use、consume-new、consume-renew、consume-formalize、consume-modify、consume-trial、refund-terminate、refund-modify、transfer-manual、transfer-system
--billing-mode string_slice 按计费模式过滤（可重复）：1（订阅）| 2（按量）| 3（合同）| 4（履约）
--ignore-zero bool 跳过折后单价为 0 的计费项
--mine bool 只统计归属于当前 SSO 子用户所有资源的账单。配合 --mine-by 选择归集维度。订阅 / 账号级账单（Agent Plan / Coding Plan）因没有 IAM 归属会被排除。与 --endpoint/--apikey/--apikey-sid/--split-dim 互斥。
--mine-by string --mine 的口径：endpoint（默认，即“基础设施归属”——我部署的 Endpoint 上的全部花费，不论调用方是谁）| apikey（费用因果——由我的 API Key 产生的账单）。两种口径互不重叠、不能相加：endpoint 按使用了哪套基础设施归集，apikey 按谁付费归集。默认与 usage stats 的 --mine-by 对齐。
--limit int 分页模式：每次请求最多返回 N 行（1-300）。在多路扇出（--end / --mine）时按每路生效；总返回量 ≤ limit × 扇出路数。求和前请务必检查 is_truncated 与 partial_failures 摘要。
--offset int 分页模式：每次请求跳过 N 行。循环 offset += limit 直到 offset >= total_records（单路扇出），多路扇出请用 shell 循环。
--output string 将完整 Output（items + summary + partial_failures）以 JSON 写入 FILE；stdout 只显示元信息（不含 items）。会自动把内部分页上限提到 1000（30 万行），便于大账号一次性导出完整明细；用户传的 --page-limit=N 仍然优先。

doctor#

运行 CLI 健康检查（安装 / 连通性 / 配置）

Bash
arkcli doctor

doctor +verify-origin#

验证 1-20 个图片或视频是否包含 Ark 生成来源特征

Bash
arkcli doctor +verify-origin <media-url> [media-url...]
Flag 类型 说明
--query-id string_slice 恢复已有验证 QueryID，不创建新任务；可重复传入，最多 20 个
--timeout string 整批执行最长等待时间，例如 2m 或 10m（默认 2m0s）
--yes bool 在已阅读价格后，对本批全部媒体仅确认一次并创建所有验证任务

doctor account#

诊断当前账号（身份 / 实名 / 余额 / IAM / VMP / TOS）

Bash
arkcli doctor account

doctor error#

诊断 Ark 错误码并跳转到对应的修复指引

Bash
arkcli doctor error <code>

doctor infer-endpoint#

诊断推理接入点（状态、模型、用量、配额压力）

Bash
arkcli doctor infer-endpoint <endpoint-id>
Flag 类型 说明
--auto-bind bool VMP 订阅 + SLR 都已开通但 telemetry 未绑定 VMP workspace 时, 自动建 ark_default + 绑 ark telemetry (订阅 / SLR 缺失时仍只给云产品开通页跳转链接, 不会替用户开通)
--window string 回溯窗口，Go duration 语法（如 1h、24h；time.ParseDuration 不支持 '7d'）

doctor metrics#

查询 VMP 中具名的 PromQL 指标（由 catalog 驱动）

Bash
arkcli doctor metrics <id>
Flag 类型 说明
--auto-bind bool VMP 未绑定 workspace 时自动建 ark_default + 绑 ark telemetry (订阅 / 跨服务授权缺失时仍给 LinkOpenMgmtCloudProduct 链接, 不会替用户开通)
--filter stringArray 注入额外的标签匹配器（可重复，label=value）；模板必须声明 ${@filters} 指令（默认 []）
--format string 输出形态（仅限裸写法 'metrics '——list/describe 始终输出 json）：json | scalar | table
--param stringArray 绑定目录参数（可重复，key=value）（默认 []）
--step string 采样步长（Go duration；默认 = window/60，限制在 [10s,60s]）
--window string 回溯窗口（Go duration；不支持 '7d'）（默认 1h）
--workspace-id string VMP workspace UUID（默认：通过 ark telemetry 配置自动解析）

doctor metrics describe#

查看某个 catalog 条目的完整元数据（仅支持 json 输出）

Bash
arkcli doctor metrics describe <id>

doctor metrics list#

列出 catalog 中全部具名 PromQL 查询（仅支持 json 输出）

Bash
arkcli doctor metrics list

doctor metrics raw#

执行任意 PromQL 查询（必须引用 ark_* 指标）

Bash
arkcli doctor metrics raw
Flag 类型 说明
--auto-bind bool VMP 未绑定 workspace 时自动建 ark_default + 绑 ark telemetry
--format string 输出形态：json | scalar | table
--promql string PromQL 表达式（必填）
--step string 采样步长（Go duration；默认自动）
--window string 回溯窗口（Go duration；不支持 '7d'）（默认 1h）
--workspace-id string VMP workspace UUID（默认：自动解析）

doctor model#

诊断基础模型（是否存在、接入点、用量、错误率、配额）

Bash
arkcli doctor model <model-name>
Flag 类型 说明
--auto-bind bool VMP 订阅 + SLR 都已开通但 telemetry 未绑定 VMP workspace 时, 自动建 ark_default + 绑 ark telemetry (订阅 / SLR 缺失时仍只给云产品开通页跳转链接, 不会替用户开通)
--window string 回溯窗口（Go duration 语法，如 1h、24h）

doctor report#

向 Ark case-platform 上报 Seedance 2.x 效果问题

Bash
arkcli doctor report
Flag 类型 说明
--account-id string task 所属账号 id; 未传时按 APIKey 反查
--badcase-type string 问题类别 (可选枚举, 见 --help Long 段)
--contact-info string 联系方式 (邮箱/电话), ≤255 字符
--dry-run bool 预览客户端执行计划，不发网络请求、无副作用
--feedback string 问题描述, 1-2000 字符, 拒绝纯空白
--source string 来源枚举: huosu | huoshan | qianzhi | case_import (默认)
--task-id stringArray seedance 2.x 的 task_id（可重复或用逗号/空白分隔；1-50 个）（默认 []）
--yes bool TTY 下跳过 Y/N 确认; headless 环境本 flag 无效, 需 ARKCLI_ALLOW_HEADLESS_REPORT=1

usage#

ARK 用量查询：usage stats（Token/请求数，5-30 分钟延迟）、usage plan（套餐额度快照）、usage plan-details（Agent Plan 按模型时间序列，套餐内外拆分）、usage balance（余额：免费额度/媒资库/套餐）、usage seats --with-usage（团队席位用量）。

  • stats 出推理量（近实时），billing 出结算金额（T+1 财务口径），两者不可混用；
  • Coding Plan 只有 quota 快照，没有按模型的套餐明细，不能用 stats 冒充。

usage balance#

Query account balance from one of three angles: free-quota (per-model 免费推理额度 / 资源包余额), media-asset (素材库 / 媒资库容量), plan (订阅套餐余额)

Bash
arkcli usage balance
Flag 类型 说明
--type string（必填） 余额类型（必填）：free-quota | media-asset | plan
--model string [free-quota] 只查单个基础模型（如 doubao-seed-1-6）
--modality string [free-quota] FoundationModelDomain 枚举：LLM | ComputerVision | Audio | Embedding | Router（不支持别名）
--page-number int [free-quota] 页码（从 1 开始）
--page-size int [free-quota] 每页条数（默认 20；从 50 下调以保证 ListModelChargeItems 落在 10s 超时预算内）
--project string [media-asset] 项目范围；默认取当前 profile 的项目
--product string [plan] 套餐 id：agent-plan | coding-plan | agent-plan-team | coding-plan-team
--all bool [plan] 查询全部支持的个人版套餐，即使未订阅也查
--seat string [plan] 只查指定 SeatID（仅企业版）

usage plan#

查询套餐用量（Agent Plan / Coding Plan 的额度与周期用量）。默认自动发现全部 4 个 SKU（个人 × 2 + 企业 × 2）；可用 --product 或 --all 覆盖。

Bash
arkcli usage plan
Flag 类型 说明
--product string 套餐产品 id：agent-plan | coding-plan | agent-plan-team | coding-plan-team。默认自动发现全部订阅。
--all bool 查询全部 4 个产品（个人 × 2 + 企业 × 2），即使未订阅也查。与 --product 互斥。
--seat string [team] 指定 SeatID；默认通过 GetSeatInfo 取调用方绑定的席位

usage plan-details#

查询 Agent Plan 的用量明细（按模型的时间序列），支持个人版或企业版。必须传 --start；--end 默认今天；--interval 默认 Day。

Bash
arkcli usage plan-details
Flag 类型 说明
--start string（必填） 开始日期（YYYY-MM-DD）。必填。后端限制区间 ≤ 31 天，历史 ≤ 6 个月。
--end string 结束日期（YYYY-MM-DD，含当天）。默认今天。
--interval string 查询粒度：Day | Hour
--model string_slice 按对外展示的 model/harness ObjectName 过滤（可重复）。省略则不按模型分组。
--product string agent-plan（默认，个人版）| agent-plan-team
--seat string_slice [team] SeatID（可重复，单次调用 ≤ 1000）；默认通过 GetSeatInfo 取调用方绑定的席位
--all-seats bool [team, admin] 先调用 ListSeatInfos 取出团队内全部席位 ID 再批量查询（与 --seat 同时给出时以 --seat 为准）
--seat-user-id string_slice [team] 服务端按子用户 ID 过滤（可重复，管理员范围）
--seat-user-name string_slice [team] 服务端按子用户名称过滤（可重复，管理员范围）

usage seats#

列出企业版套餐订阅下的全部席位（管理员视图）。需要管理员权限；子用户调用会返回 AccessDenied。project 解析顺序：--project 参数 > 字面量 default（企业席位始终创建在 default，刻意绕过 profile 的 project，以与 internal/service/agentplan/buy.go::buyTeam 的创建路径保持 1:1）。

Bash
arkcli usage seats
Flag 类型 说明
--product string（必填） 团队套餐 id（必填）：agent-plan-team | coding-plan-team
--biz-info string 按档位过滤：small/medium/large/max（AgentPlan）| lite/pro（CodingPlan）
--billing-status string_slice 按计费状态过滤（可重复）：Pending / Running / Expired / Reclaimed
--seat-status string 按席位状态过滤：Idle / Active
--user-id string_slice 按子用户 ID 过滤（可重复；超过 1 个会按用户做客户端扇出，结果按 SeatID 合并去重）
--user-name string_slice 按子用户名称过滤（可重复；超过 1 个会做客户端扇出）
--seat-id string_slice 只查指定 SeatID（可重复；会绕过项目过滤）
--project string 项目范围。解析顺序：本参数 > 字面量 default。plans buy --plan *-team 一律在 default 下创建席位，因此这里刻意忽略当前 profile 的项目——若回退到 profile 项目，当 profile 项目 != default 时会静默返回空列表。
--page-size int 每页条数（默认 100）
--page-number int 页码，从 1 开始；传入后关闭自动翻页，只取一页
--sort-by string 排序字段
--sort-order string 排序方向：ASC | DESC
--with-usage bool [仅团队产品] 关联按席位用量：AgentPlan→ListSeatAFPUsage（已用/总量/百分比），CodingPlan→ListSeatInfoUsages（仅百分比）。每行会附加 afp_usage / coding_usage。

usage stats#

按日期范围查询推理用量（Token / 请求数），可按模型、Endpoint 或 API Key 过滤

Bash
arkcli usage stats
Flag 类型 说明
--start string（必填） 开始日期，格式 YYYY-MM-DD（必填）
--end string 结束日期，格式 YYYY-MM-DD，默认今天
--interval string 查询粒度：Day | Hour
--endpoint string 按 Endpoint ID 过滤
--model string 按模型名称过滤
--apikey string 按 API Key 过滤（Values 精确匹配，旧写法）
--apikey-suffix string 按 API Key 后缀过滤（ValueLike 匹配，例如 Key 末 12 位）
--mine bool 只统计当前 SSO 子用户拥有的资源；配合 --mine-by 使用
--mine-by string --mine 的口径：endpoint（默认）| apikey
--by string 分组维度：model、endpoint、apikey
--show-window-detail bool 在响应中拆解每次调用的计费窗口