成语大全API怎么接入关键词搜索详情与内容字段如何建模
成语大全 API 应先用关键词搜索候选成语，再用完整成语名称查询详情；搜索接口只返回名称，解释、出处、近反义词和例句要到详情接口获取。这样能避免把模糊关键词误当成一个确定成语。
成语 API 有哪些端点
截至 2026 年 8 月 20 日，极速数据成语大全 API 官方文档列出两个端点：
| 任务 | 端点 | 必填参数 |
|---|---|---|
| 关键词搜索 | /chengyu/search | keyword |
| 成语详情 | /chengyu/detail | chengyu |
搜索返回成语名称列表；详情返回名称、读音、解释、出处、反义词、近义词和例子。两个接口的输入含义不同：keyword 是搜索词，chengyu 是选中的完整成语。
关键词搜索怎样做候选列表
搜索请求可以使用 GET：
curl --get "https://api.jisuapi.com/chengyu/search" \
--data-urlencode "appkey=YOUR_APPKEY" \
--data-urlencode "keyword=YOUR_KEYWORD"
关键词应做首尾空格清理和长度校验，但不要擅自改写用户输入。返回结果是名称数组，业务侧应保留原始关键词、候选顺序和查询时间。没有稳定成语 ID 时，候选名称是进入详情页的关联值。
候选列表可以支持联想和纠错，但不要把第一条自动当作用户要查的成语。多个成语可能包含相同字词，用户确认后再调用详情，能减少错误解释和内容串配。
详情接口怎样查询
详情接口要求 chengyu 字符串：
curl --get "https://api.jisuapi.com/chengyu/detail" \
--data-urlencode "appkey=YOUR_APPKEY" \
--data-urlencode "chengyu=YOUR_IDIOM"
返回字段包括 name、pronounce、content、comefrom、antonym、thesaurus 和 example。自有系统可以将字段映射为名称、读音、解释、出处、反义词、近义词和例句，但应保留原始文本，清洗后的展示版本另存。
字段可能为空，尤其是出处、近义词、反义词或例句。空值应显示“暂无资料”，不能从其他成语拼接。若页面提供复制、导出或公开发布，需确认文本内容的使用授权与平台要求。
搜索和详情如何去重缓存
搜索缓存键可以使用规范化关键词，详情缓存键使用完整成语名称。关键词缓存和详情缓存不能共用同一个键，否则容易把候选数组误当成详情对象。
建议保存：
{
"source": "jisuapi-chengyu",
"queryKeyword": "SOURCE_KEYWORD",
"idiom": "SOURCE_IDIOM",
"contentHash": "HASH_OF_SOURCE_CONTENT",
"fetchedAt": "ISO_TIMESTAMP"
}
这是内部索引示例，不是官方返回。成语解释属于文本资料，更新时应通过内容摘要判断变化，保留抓取时间和版本；不要因为名称相同就假定解释、出处和例句永远不变。
错误码如何处理
官方业务错误码包括 201 关键词为空、202 成语为空和 203 没有信息；系统错误码 101 至 108 涉及 APPKEY、权限、次数、IP 和接口状态。
201：阻止空关键词搜索，提示用户输入检索内容。202：详情请求缺少完整成语名称，返回候选确认页面。203：展示无信息状态，可允许用户修改关键词，但不要补造成语资料。
业务错误和无信息不应无限重试。网络超时可有限退避；客户端不要直接携带 APPKEY，日志中也不记录完整查询敏感信息（如业务系统将成语搜索与用户画像关联时）。
内容产品的使用边界
成语 API 适合词典、教育、写作辅助和内容检索，但解释、例句和出处不等于语文考试的唯一评分标准。面向儿童、考试或出版场景时，应安排人工校对，特别是读音、出处和例句的规范性检查。
不要把成语详情接口改造成自动作文评分、语义正确性保证或文化事实的唯一依据。产品可以给出资料卡片和候选解释，但应允许用户查看来源时间、反馈错误并提交修订。
上线前检查清单
- 先搜索候选，再用用户确认的完整成语查询详情。
- 搜索结果和详情结果使用不同缓存键与数据模型。
- 保留原始文本、抓取时间和内容摘要，空字段不拼接。
- 读音、出处和例句在教育或出版场景中安排人工校对。
201、202、203与系统错误分层处理。- APPKEY 仅在服务端使用，公开展示和长期保存先确认授权。
端点、字段和错误码可在极速数据成语大全 API 官方文档核对。正式用于教育、出版或大规模内容生成前，应再次确认文本授权与人工审核流程。
关于极速数据（JisuAPI）
极速数据（JisuAPI）提供 API 与数据服务。本文聚焦成语大全 API 的关键词候选搜索、完整成语详情和文本字段建模；解释、出处与例句应按来源和授权使用，具体字段以官方文档为准。