易源合一指南总目录：3054 三个接入点与 12 篇实测笔记
# 易源合一指南总目录：3054 三个接入点与 12 篇实测笔记
> 接口：易源合一（apiCode=3054，官方自营） | 接入点：3 个 | 请求方式：POST | 返回格式：JSON | 计费：5.5 厘/次，失败不扣费 | 最后实测核对：2026-09-15
## 接口一句话速览
showapi 易源合一接口（apiCode=3054）是一个入口调用多种 API 的自然语言网关：把用户原话交给它，它识别意图、调用对应能力，返回已整理的答复文本和底层业务数据。实测覆盖到的意图有 8 类，包括天气、快递、新闻查询、车牌限行、笑话、口算批改、身份证 OCR、手写体识别。
## 三个接入点速查
| 接入点 | 接口地址 | 请求方式 | 说明 |
|--------|---------|---------|------|
| 3054-1 智能对话 | `https://route.showapi.com/3054-1` | POST | 同步返回，走 `showapi_res_body` 封装，返回 `reply_msg` / `intent` / `result` |
| 3054-2 意图分析 | `https://route.showapi.com/3054-2` | POST（文档标注亦支持 GET） | 只判意图，返回 `intent` / `name` / `args` / `confidence`，不执行业务 |
| 3054-3 智能对话(流式) | `https://route.showapi.com/3054-3` | POST | 透传模式，SSE 分块返回，无 `showapi_res_body` 封装，不返回计费字段 |
三个接入点共用两个请求参数：`text`（String，必填，意图内容）、`args_list`（List，可选，图片 URL 或 base64）。鉴权用 `appKey`，放在 URL 的 query 里。
## 全系列 12 篇
### 入门层
**01. [易源合一快速接入：用 curl 把「昆明今天天气」变成结构化数据](https://www.showapi.com/guides/united-api-quickstart-3054)**
从注册到第一条请求，含 cURL / Python / Node 三版可跑代码，附一份完整的真实天气返回。
**02. [易源合一实测能识别哪些意图：8 类 intent 编码逐一验证](https://www.showapi.com/guides/united-api-intent-list-3054)**
15 条真实中文语料的识别结果表，含 `intent`、`name`、`args`、`confidence` 四个字段的实测取值。
**03. [易源合一返回三层结构：reply_msg / intent / result 逐层拆解](https://www.showapi.com/guides/united-api-response-structure-3054)**
三个 `ret_code` 分层说明，五种意图的 `result` 结构实测对照，附一份按意图分派的解析函数。
### 场景实战层
**04. [易源合一 3054-2 与 3054-1 的搭配方式：先判意图，再决定要不要发起对话](https://www.showapi.com/guides/united-api-intent-precheck-3054)**
两段式调用不省钱的实算过程，以及它真正解决的问题：意图能识别但对话未接通。
**05. [易源合一 args_list 传图：base64 与图片 URL 两种传法实测](https://www.showapi.com/guides/united-api-args-list-image-3054)**
两种传参形态的完整代码，OCR 返回的 `all_str` 与四角坐标 `range` 怎么用。
**06. [易源合一接进客服机器人：一次接入拿到天气、快递、新闻三类答复](https://www.showapi.com/guides/united-api-chatbot-skill-3054)**
一份 Flask webhook 实现，三类意图的返回差异与展示处理，含一处措辞自相矛盾的实测坑点。
**07. [易源合一在对话式应用里的位置：意图层与执行层的切分方案](https://www.showapi.com/guides/united-api-dialog-architecture-3054)**
三种放置方式的时序对比、实测延迟预算，以及接口无多轮上下文时的会话状态维护写法。
### 技术深挖层
**08. [易源合一只返回 55 分置信度时：阈值设定、兜底路径与二次追问](https://www.showapi.com/guides/united-api-low-confidence-3054)**
纠正 `confidence` 的量纲误区，给出实测分数分布与三档阈值落地代码。
**09. [易源合一流式接入点 3054-3：SSE 分块解析与选型取舍](https://www.showapi.com/guides/united-api-streaming-3054)**
`id` / `event` / `data` 三字段解析，四种事件的处理写法，以及「只收到一个 finish 块」的实测事实。
**10. [易源合一调用失败扣不扣费：ret_code 与 showapi_fee_num 实测对照表](https://www.showapi.com/guides/united-api-retcode-fee-3054)**
24 次调用样本的扣费对照，失败文案全集，以及「成功但无效」的隐形成本。
### 选型对比层
**11. [易源合一、直连单接口、自建意图识别：三条路线怎么选](https://www.showapi.com/guides/united-api-vs-direct-integration-3054)**
三条路线的中立逐项对比，明确列出「这个场景别用易源合一」的判据。
### 集成层（MCP / OpenAPI）
**12. [易源合一的两条集成路径：MCP 直连与 OpenAPI 导入 Postman](https://www.showapi.com/guides/united-api-mcp-openapi-3054)**
MCP 三步握手的手工验证过程与排错对照表，OpenAPI 规格要点与导入 Postman / Swagger UI 的注意事项。
## 相关资源
| 资源 | 地址 |
|------|------|
| 接口详情页 | `https://www.showapi.com/apiGateway/view/3054` |
| 接入点文档（智能对话） | `https://www.showapi.com/apiGateway/view/3054/1` |
| 接入点文档（意图分析） | `https://www.showapi.com/apiGateway/view/3054/2` |
| 接入点文档（智能对话流式） | `https://www.showapi.com/apiGateway/view/3054/3` |
| OpenAPI 文档（YAML） | `https://www.showapi.com/openapi/market/3054.yaml` |
| OpenAPI 文档（JSON） | `https://www.showapi.com/openapi/market/3054.json` |
| MCP 服务地址 | `http://www.showapi.com.cn/mcp/3054/{your_appKey}` |
| 在线调试 | `https://www.showapi.com/apitest/market/3054/1` |
| AppKey 管理 | `https://www.showapi.com/console#/myApp` |
计费口径：三个接入点单次费用同为 5.5 厘，并发量 10 次/秒，有效期一年（全站统一），不限购买次数，调用成功才计费。专用资源包与通用资源包都可用，具体档位与对应可调用次数以官方产品价格页为准。
## FAQ
**Q1：易源合一有三个接入点，我该先看哪个？**
只想尽快跑通一次调用，看 3054-1 智能对话。只想要意图标签不想要答复文案，看 3054-2 意图分析。前端要边收边渲染，再看 3054-3 流式。
**Q2：易源合一免费吗？**
不免费。三个接入点的单次费用同为 5.5 厘，调用成功才计费，失败不扣费。可以用专用资源包，也可以用通用资源包按接入点单价扣费。
**Q3：接口支持多轮对话吗？**
不支持。请求参数只有 `text` 和 `args_list`，没有会话或上下文参数，每次调用都是独立的单句识别。多轮状态要在调用方自己维护。
**Q4：文档和实测对不上的地方以哪个为准？**
以你的实测为准，本文的实测结论也标注了日期。本系列已确认的偏差有：`confidence` 实测为 0~100 整数（文档示例是小数）、`args.date` 实测返回标准化日期（文档示例是相对日期）、3054-3 实测只返回单个 `finish` 块。
**Q5：这套指南里的实测数据是怎么来的？**
用真实 AppKey 对三个接入点发请求，覆盖 3054-1 的 7 类输入（含重复调用）、3054-2 的 15 条语料、3054-3 的 3 类意图、2 次图片传参与 MCP 完整握手，实测日期 2026-09-15。
## 阅读建议
**只想尽快跑通一次调用** → 第 01 篇，代码复制即用。
**要判断这个接口能不能覆盖你的业务** → 第 02 篇看意图覆盖，第 11 篇看路线取舍。
**已经被 `result` 的结构差异坑过** → 第 03 篇，五种意图的结构对照表能省下不少调试时间。
**在做架构设计** → 第 07 篇的分层方案，配合第 04 篇的两段式成本实算。
**准备上线前** → 第 08 篇定置信度阈值，第 10 篇把扣费判定写进日志。
**要用 MCP 接 AI 客户端** → 第 12 篇的排错对照表，`-32601` 和 `400` 两个现象都能对上。
## 全系列的实测口径说明
本系列的每条实测结论都标注了实测日期（2026-09-15）。实测用真实 AppKey 发起请求，样本包括：3054-1 的 7 类输入各 1~6 次重复、3054-2 的 15 条语料探测与 2 条语料各 6 次重复、3054-3 的 3 类意图调用、1 次 base64 传图与 1 次 URL 传图、MCP 的完整三步握手与 2 次 `tools/call`。
其中存在偏差或不确定的地方，文中已逐处标注。特别提醒三处：
- `confidence` 实测为 0~100 整数，与官方文档示例的 `0.99572587013245` 不一致；
- `args.date` 实测返回标准化日期（如 `2026-09-15`），与文档示例的相对日期表述不一致；
- 3054-3 实测三类意图均只返回单个 `finish` 块，未观察到 `add` 增量分片。
以上结论基于 2026-09-15 的实测，接口行为如有调整，以官方文档与你的实测为准。
