一、接口概述与适用场景本草纲目·中药查询接口/api/bencao提供基于《本草纲目》及常见中药材的查询能力。输入药材中文名称如“人参”“甘草”返回该药材的释名、气味、主治、附方等详细文本。数据经过整理便于开发者快速集成到中医养生App、中药知识科普小程序、AI问诊辅助、古籍数字化或国学教学系统中。接口采用标准 RESTful 设计QPS 限制为 10 次/秒适合中小规模调用。注意数据仅供学习参考实际用药请遵医嘱。二、接口能力边界精确匹配输入完整药材名称返回matched: exact的详情。模糊匹配若名称不存在返回 HTTP 4040 状态码并附带suggestions数组最多 10 条相关药材。例如查询“人参枸杞”会建议“人参”“枸杞”等单味药。字段限制msg参数最长 50 个字符仅支持中文。鉴权方式可选 API Key通过X-API-Key请求头传递。未携带 Key 时每日允许 30 次调用超出后返回鉴权错误。三、请求参数与鉴权Query 参数参数名类型必填说明示例msgstring是药品中文名称最长 50 字符人参Header 参数参数名类型必填说明X-API-Keystring否API 密钥用于提升调用额度若未提供 API Key接口仍可调用但受每日 30 次体验限制。正式接入建议申请 Key请参考官方文档获取。四、curl 接入示例以下示例展示了带 API Key 的 GET 请求。将$APIZERO_API_KEY替换为你实际的密钥。curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/bencao?msg人参若不携带 API Key直接调用curl -sS \ -X GET \ https://v1.apizero.cn/api/bencao?msg丁香返回示例JSON 格式{ code: 0, data: { detail: 「释名」黄参、神草、土精、血参...\n「气味」根甘、温、无毒...\n「主治」补五脏安精神..., matched: exact, name: 人参 }, msg: 成功, request_id: mqx8x12345abc }五、代码接入示例Python 3使用requests库发起请求并处理响应。import requests API_URL https://v1.apizero.cn/api/bencao API_KEY your_api_key_here # 如无密钥留空 params {msg: 甘草} headers {} if API_KEY: headers[X-API-Key] API_KEY try: resp requests.get(API_URL, paramsparams, headersheaders, timeout10) data resp.json() if data.get(code) 0: herb data[data] print(f药材: {herb[name]}) print(f详情:\n{herb[detail]}) else: print(f请求失败: {data[msg]}) except requests.exceptions.RequestException as e: print(f网络错误: {e})JavaScript (Node.js)使用axios或原生fetch。以下为 fetch 示例const API_URL https://v1.apizero.cn/api/bencao; const API_KEY your_api_key_here; // 可选 async function queryHerb(name) { const params new URLSearchParams({ msg: name }); const headers {}; if (API_KEY) headers[X-API-Key] API_KEY; try { const res await fetch(${API_URL}?${params}, { headers }); const json await res.json(); if (json.code 0) { console.log(药材: ${json.data.name}); console.log(json.data.detail); } else { console.error(错误: ${json.msg}); } } catch (err) { console.error(请求异常:, err); } } queryHerb(当归);六、返回字段详解成功响应HTTP 200JSON 结构如下字段类型说明codeint0 表示成功非 0 表示错误msgstring状态描述如“成功”或错误原因request_idstring本次请求的唯一标识符dataobject包含name药材名、matched匹配类型、detail完整文本其中data.detail字符串通常包含多行以\n分隔内容为释名、气味、主治等章节。开发者可直接显示或按需解析。错误响应4040 状态码未找到精确匹配响应体含有suggestions数组。示例{ code: 4040, data: { suggestions: [人参, 枸杞] }, msg: 未找到匹配项以下为相关建议, request_id: abc123 }400 参数错误msg为空或超长。401 鉴权失败API Key 无效或超出调用次数限制。七、常见错误排查返回 4040 而非 200请检查药材名称是否准确或利用suggestions提示正确名称。HTTP 401确认 API Key 是否正确或当日接口调用已达上限。请求超时网络环境不稳定建议设置合理的超时时间如 10 秒。返回乱码确保请求头Accept为application/json并正确解码 UTF-8。八、工程化注意事项缓存策略中药材数据几乎不变可对相同msg的响应缓存较长时间如 24 小时减少重复调用。并发控制QPS 10/s建议在客户端实现请求队列或限流避免触发限频。错误重试对 5xx 错误可进行指数退避重试最多 3 次对 4xx 错误则需修正请求。数据解析detail字段的换行符\n在不同平台需正确处理如网页渲染为br。医疗合规前端展示应明确标注“数据仅供学习参考不构成医疗建议”。九、参考文档官方文档页https://apizero.cn/aidocs/bencao原始文档Markdownhttps://apizero.cn/aidocs/bencao/raw.md
