易源合一调用失败扣不扣费：ret_code 与 showapi_fee_num 实测对照表
易源合一计费规则ret_codefee_num成本控制 # 易源合一调用失败扣不扣费：ret_code 与 showapi_fee_num 实测对照表
> 接入点：3054-1 / 3054-2 / 3054-3 | 请求方式：POST | 返回格式：JSON | 计费：5.5 厘/次，失败不扣费 | 最后实测核对：2026-09-15
## 核心要点
- 官方价格页的规则「调用成功才计费，失败不扣费」经实测成立。24 次重复调用中，`ret_code: 0` 的全部 `showapi_fee_num: 1`，`ret_code: -1` 的全部为 `0`。
- **「失败不扣费」不等于「不成功就不花钱」**：命中了一个你不需要的意图也算成功，照样扣费。
- `showapi_res_code`、`ret_code`、`result[i].ret_code` 是三层不同的码位，只有第二层决定计费。
## 三层码位与计费的关系
先把三个码位摆清楚，不然日志里的「成功」会是假的。
| 字段 | 层级 | 实测取值 | 与计费的关系 |
|------|------|---------|-------------|
| `showapi_res_code` | 通道层 | `0` | 与计费无关，通道异常时通常没有业务数据 |
| `showapi_res_body.ret_code` | 业务层 | `0` 或 `-1` | **决定扣费**。`0` 扣 1 次，`-1` 扣 0 次 |
| `result[i].ret_code` | 子业务层 | 快递实测出现过 `2` | 与计费无关，此时业务层仍是 `0`，已经扣费 |
第三层容易被误读。快递查询「查不到物流信息」时，`result[0].ret_code` 是 `2`，`data` 是空数组，但这笔调用**已经扣费了**。因为业务层认为「意图识别 + 调用执行」都成功了，只是底层没查到数据。
## 实测扣费对照表
2026-09-15，3054-1 逐条调用，共 24 次有效样本：
| 输入 | `ret_code` | `ret_msg` | `showapi_fee_num` |
|------|-----------|-----------|------------------|
| 帮我查找一下昆明今天的天气 | 0 | 无 | 1 |
| 讲个笑话（重复 6 次） | 0 | `查询成功！` | 1（每次都是） |
| 帮我查快递 7788990011223 | 0 | `调用成功` | 1 |
| 今天有什么新闻 | 0 | 无 | 1 |
| 你好（命中笑话） | 0 | `查询成功！` | 1 |
| 你好（命中新闻） | 0 | 空字符串 | 1 |
| 你好（没听懂） | -1 | `must input content field` | 0 |
| 你好（推理异常） | -1 | `调用失败：推理失败3` | 0 |
| 北京限行尾号是多少（重复 6 次） | -1 | `抱歉，您的问题我还没有学会，请等待我的更新和完善1` | 0（每次都是） |
| 把这句话翻译成英文：今天天气不错 | -1 | `摘要失败了，可以换个文本试试哦！` | 0 |
规律很干净：业务层 `ret_code` 为 `0` 就扣 1 次，为 `-1` 就扣 0 次。24 次样本没有例外。
3054-2 的规则一样：意图识别成功（`ret_code: 0`）扣 1 次，识别失败（`ret_code: -1`）不扣费。
## 「成功」也可能是无效花费
对照表里有一行值得单独说：
```
输入：你好
ret_code: 0
ret_msg: ""
intent: query_news
showapi_fee_num: 1
```
这次调用被判定为成功，扣了费，但返回的是一批和「你好」毫无关系的新闻。用户看到的是答非所问。
这就是把成本控制寄托在「失败不扣费」上的问题。真正烧钱的是这类**成功了但没用**的调用。同一个「你好」在 6 次重复里，2 次命中 `joke`、1 次命中 `query_news`，都算成功都扣费。
能不能压住这部分开销，取决于你在调 3054-1 之前有没有做意图判断。用 3054-2 先看 `confidence`，低分档直接走追问、不调 3054-1，一次能省 5.5 厘。相关写法见 [易源合一只返回 55 分置信度时：阈值设定、兜底路径与二次追问](https://www.showapi.com/guides/united-api-low-confidence-3054)。
## 计费参数与成本换算
| 项目 | 实测/文档值 |
|------|-----------|
| 单次费用 | 5.5 厘/次（三个接入点同价） |
| 50 元专用资源包 | 只用本接口可调 9090 次 |
| 并发量 | 10 次/秒 |
| 有效期 | 一年（全站统一） |
| 购买限制 | 不限购买次数，资源包自动递延串联 |
| 计费规则 | 调用成功才计费，失败不扣费 |
| 通用资源包 | 按各接入点单价扣费，可调用全站付费接口 |
按 5.5 厘/次换算：1000 次约 5.5 元，10000 次约 55 元。走两段式（3054-2 + 3054-1）时，请求数翻倍，成本也翻倍。
专用资源包的可调用次数是产品价格页给出的口径（50 元对应 9090 次）。其他档位与对应次数的关系以官方产品价格页显示为准。
## 一份把花费记清楚的日志中间件
```python
import logging, requests
APP_KEY = "YOUR_APPKEY"
log = logging.getLogger("showapi")
FEE_PER_CALL = 0.0055 # 元/次，来源：产品价格页 5.5 厘/次
def call(point, text, timeout=20):
r = requests.post(f"https://route.showapi.com/{point}?appKey={APP_KEY}",
data={"text": text}, timeout=timeout)
d = r.json()
body = d.get("showapi_res_body", {}) or {}
fee_num = d.get("showapi_fee_num", 0)
# 通道层
if d.get("showapi_res_code") != 0:
log.error("channel_error point=%s err=%s", point, d.get("showapi_res_error"))
return None, 0.0
# 业务层：决定计费
if body.get("ret_code") != 0:
log.info("biz_fail point=%s msg=%s fee_num=%s", point, body.get("ret_msg"), fee_num)
assert fee_num == 0, "协议变化：失败却扣费了，需要核对计费规则"
return None, 0.0
# 成功：扣费
cost = fee_num * FEE_PER_CALL
log.info("ok point=%s intent=%s fee_num=%s cost=%.4f元 text=%r",
point, (body.get("intent") or {}).get("name") if isinstance(body.get("intent"), dict)
else body.get("intent"), fee_num, cost, text)
return body, cost
def handle(text):
"""两段式：意图先判，再决定要不要花钱调对话。"""
b2, c2 = call("3054-2", text)
if b2 is None:
return {"reply": "没听懂", "cost": c2}
conf = b2.get("confidence")
if conf is not None and conf < 90:
return {"reply": "能说得再具体一点吗", "cost": c2} # 省下 3054-1 的 5.5 厘
b1, c1 = call("3054-1", text)
if b1 is None:
return {"reply": "查询失败", "cost": c2 + c1}
return {"reply": b1["reply_msg"]["text"], "cost": c2 + c1}
```
代码里那句 `assert fee_num == 0` 是故意的。计费规则的假设一旦变了，这条断言会让你在测试阶段就发现，而不是月底对账时才发现。
## FAQ
**Q1：`ret_code: -1` 会扣费吗？**
不会。实测 24 次样本中，业务层 `ret_code` 为 `-1` 的调用 `showapi_fee_num` 全部为 `0`。
**Q2：`result[0].ret_code` 是 2，为什么还扣费了？**
因为计费看的是业务层 `ret_code`。快递意图识别成功、底层接口正常返回了「查不到物流信息」这个结果，流程算走通，扣 1 次。子业务层的 `2` 只是底层业务码。
**Q3：同一个问题问两次会扣两次吗？**
会。接口是无状态的单句识别，没有会话缓存。相同输入重复调用按次计费。要压成本就在自己那侧做缓存。
**Q4：失败不扣费，那是不是可以随便试错？**
试错的直接成本是零，但要留意「成功了但没用」的调用照样扣费。实测「你好」这类短句会在 6 次里命中笑话、新闻等不同意图，每次都算成功。低信息量输入建议先走意图判断。
**Q5：怎么知道每次调用花了多少钱？**
每次成功调用的响应里带 `showapi_fee_num`，实测值为 1，乘单价 5.5 厘就是这次的成本。3054-3 是透传模式，不返回这个字段，走流式只能从账单侧统计。
**Q6：通用资源包和专用资源包怎么选？**
专用资源包只适用于本接口，通用资源包按各接入点单价扣费、可调用全站付费接口。只做易源合一个接口的话，专用资源包的换算关系更直观（50 元对应 9090 次）。档位与次数的对应以官方产品价格页为准。
## 下一步阅读
- [易源合一返回三层结构：reply_msg / intent / result 逐层拆解](https://www.showapi.com/guides/united-api-response-structure-3054)
- [易源合一只返回 55 分置信度时：阈值设定、兜底路径与二次追问](https://www.showapi.com/guides/united-api-low-confidence-3054)
- [易源合一、直连单接口、自建意图识别：三条路线怎么选](https://www.showapi.com/guides/united-api-vs-direct-integration-3054)
- **本系列共 12 篇**：查看[易源合一指南总目录](https://www.showapi.com/guides/united-api-guides-3054)
