> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 按能力层级统计成本

> 获取咏唱引擎 ROUTER 按能力层级（competence tier）归因的成本，以及能力感知降级的预计节省。

这个接口把请求按 `competence_tier`（`small`/`mid`/`large`）聚合，同时估算「全部走 large 层级」的假设成本，用来对比能力感知降级省了多少。

## 接口

```http theme={null}
GET /v1/router/cost/by-competence
```

## 认证

使用会话 Cookie 或 `Authorization: Bearer <api-key>` 认证。

## 响应

<ResponseField name="by_tier" type="object">
  按层级聚合的成本，每个层级包含：

  <Expandable title="层级字段">
    <ResponseField name="requests" type="integer">
      这个层级的请求数。
    </ResponseField>

    <ResponseField name="cost_usd" type="number">
      这个层级的成本（美元）。
    </ResponseField>

    <ResponseField name="tokens" type="integer">
      这个层级的令牌总数（prompt + completion）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="actual_cost_usd" type="number">
  实际总成本（美元）。
</ResponseField>

<ResponseField name="notional_large_cost_usd" type="number">
  假设全部走 large 层级的估算成本（美元）。
</ResponseField>

<ResponseField name="estimated_savings_usd" type="number">
  能力感知降级省下的成本（美元），取 `notional_large_cost_usd - actual_cost_usd` 和 0 中的较大值。
</ResponseField>

## 示例

```bash theme={null}
curl -s https://router.example.com/v1/router/cost/by-competence \
  -H "Authorization: Bearer <api-key>"
```

```json theme={null}
{
  "by_tier": {
    "small": { "requests": 120, "cost_usd": 0.30, "tokens": 9000 },
    "mid":   { "requests": 80,  "cost_usd": 1.20, "tokens": 24000 },
    "large": { "requests": 10,  "cost_usd": 2.50, "tokens": 5000 }
  },
  "actual_cost_usd": 4.00,
  "notional_large_cost_usd": 16.00,
  "estimated_savings_usd": 12.00
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.