# 调用与计费

> Herline MCP 返回结构化结果。生产工具会带 Her能 扣减信息；余额不足会返回可恢复状态。

更新:2026-06-29
页面:https://herline.vip/developers/billing

---


MCP 工具返回结构化结果。涉及扣费的工具会在结果中返回 `units`，便于 agent 直接判断本次消耗和剩余额度。

## 成功返回

```json
{
  "status": "ok",
  "data": { "task_id": "...", "status": "QUEUED" },
  "units": {
    "deducted": 99,
    "remaining": 4173,
    "balance_before": 4272,
    "balance_after": 4173,
    "reason": "本次计费原因",
    "transaction_id": "..."
  },
  "request_id": "...",
  "idempotency_key": "..."
}
```

- `data`：本次调用的业务结果（异步能力先回任务标识，再轮询）。
- `units`：本次扣减、剩余额度、扣减原因和交易标识。只读工具不扣费，通常不返回 `units`。
- `request_id`：本次调用的追踪标识。
- `idempotency_key`：幂等键。使用相同键重试，不应重复扣费或重复产出。

## 余额不足

余额不足时，工具返回可识别状态和恢复选项：

```json
{
  "status": "insufficient_units",
  "code": "INSUFFICIENT_UNITS",
  "units": { "deducted": 0, "remaining": 12, "required": 99 },
  "recovery": { "options": ["upgrade", "purchase", "enable_auto_recharge"] }
}
```

`required` 是本次所需，`remaining` 是当前余额。agent 应提示用户升级会员、补充额度或开启自动充值。

## 计费原则

- MCP 与网页端同价，不单独加价或折扣。
- 生产类工具按用量消耗 Her能。
- API Key 路径有独立的日额度和频率限制。
- Her能、会员档与业务身份的关系见使用指南的[会员、Her能与业务身份](/docs/membership-units)。

## 接着看

- [错误与限制](/developers/errors)：状态、限流、重试与能力边界。