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

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 可覆盖或扩展产品集合。

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 选择归集维度。订阅 / 账号级账单因没有 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 健康检查（安装 / 连通性 / 配置）

doctor +verify-origin

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

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

doctor account

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

doctor error

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

doctor infer-endpoint

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

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 驱动）

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 输出）

doctor metrics list

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

doctor metrics raw

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

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

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

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 效果问题

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 (订阅套餐余额)

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 覆盖。

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。

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）。

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	按计费状态过滤（可重复）：Running / Expired / Reclaimed / Inactive
--seat-status	string	按席位状态过滤：Active / Inactive
--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 过滤

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	在响应中拆解每次调用的计费窗口

火山方舟