# 用量与诊断

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

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

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

<span id="domain-billing"></span>
## billing

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

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

<span id="billing-list-command"></span>
### 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 <id> 覆盖。 |
| `--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 仍然优先。 |

<span id="doctor-command"></span>
## doctor

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

```Bash
arkcli doctor
```

<span id="doctor-verify-origin-command"></span>
### 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 | 在已阅读价格后，对本批全部媒体仅确认一次并创建所有验证任务 |

<span id="doctor-account-command"></span>
### doctor account

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

```Bash
arkcli doctor account
```

<span id="doctor-error-command"></span>
### doctor error

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

```Bash
arkcli doctor error <code>
```

<span id="doctor-infer-endpoint-command"></span>
### 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'） |

<span id="doctor-metrics-command"></span>
### 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 <id>'——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 配置自动解析） |

<span id="doctor-metrics-describe-command"></span>
### doctor metrics describe

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

```Bash
arkcli doctor metrics describe <id>
```

<span id="doctor-metrics-list-command"></span>
### doctor metrics list

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

```Bash
arkcli doctor metrics list
```

<span id="doctor-metrics-raw-command"></span>
### 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（默认：自动解析） |

<span id="doctor-model-command"></span>
### 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） |

<span id="doctor-report-command"></span>
### 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 |

<span id="domain-usage"></span>
## 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 冒充。

<span id="usage-balance-command"></span>
### 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（仅企业版） |

<span id="usage-plan-command"></span>
### 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 取调用方绑定的席位 |

<span id="usage-plan-details-command"></span>
### 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] 服务端按子用户名称过滤（可重复，管理员范围） |

<span id="usage-seats-command"></span>
### 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。 |

<span id="usage-stats-command"></span>
### 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 | 在响应中拆解每次调用的计费窗口 |