<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 本草纲目·中药查询

> 传统中药材知识查询接口，覆盖《本草纲目》及常见中药材数据。输入药材名称（如「人参」「丁香」「甘草」「枸杞」），返回该药材的释名、气味、主治、附方等详细记载。

【典型场景】
- 中医养生 / 食疗 App 的药材百科
- 中药知识科普类小程序
- AI 中医问诊辅助参考
- 古籍数字化项目
- 国学 / 中医文化教学

【调用示例】
GET /api/bencao?msg=人参
GET /api/bencao?msg=丁香
GET /api/bencao?msg=甘草

【模糊匹配】
- 精确名称查得到 → 直接返回详情（matched=exact）
- 找不到时返回 4040 + suggestions 数组（最多 10 个相关建议）
- 比如查「人参枸杞」会建议「人参、枸杞」等单味药

【⚠️ 数据来源说明】
本接口数据整理自《本草纲目》及网络公开整理资料，仅供学习参考；中医药疗用请遵医嘱。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `bencao` |
| 接口名称 | 本草纲目·中药查询 |
| 接口地址 | `https://v1.apizero.cn/api/bencao` |
| 请求方法 | `GET` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 10000 次（已认证用户） |
| 匿名每日额度 | 1000 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

本接口对未登录用户开放每日 1000 次体验额度；登录用户每日 10000 次免费。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `msg` | `string` | 是 | 药品名称（中文），如：人参、丁香、甘草、当归、枸杞。最长 50 个字符。 | `人参` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | 可选 API Key 鉴权。未登录每天 30 次免费体验 | — |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/bencao?msg=%E4%BA%BA%E5%8F%82&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `code` | `integer` | 业务状态码，0=成功，4040=未找到 | `0` |
| `msg` | `string` | 人类可读的状态消息 | `成功` |
| `data.name` | `string` | 药材名称（精确匹配的药名） | `人参` |
| `data.detail` | `string` | 详细描述（含释名、气味、主治、附方等，纯文本带换行） | `「释名」黄参...` |
| `data.matched` | `string` | 匹配方式：exact 精确匹配 | `exact` |
| `data.query` | `string` | 【未找到时】回显输入的查询词 | `xxx` |
| `data.suggestions` | `array<string>` | 【未找到时】相关药材建议列表（最多 10 个） | `["人参","党参"]` |
| `request_id` | `string` | 本次请求 ID | `mqx8x12345abc` |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "name": "人参",
        "detail": "「释名」黄参、神草、土精、血参...\n「气味」（根）甘、温、无毒...\n「主治」补五脏，安精神...",
        "matched": "exact"
    },
    "request_id": "mqx8x12345abc"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `0` | `OK` | 成功 |
| `4000` | `Bad Request` | 参数错误：缺少 msg / msg 长度超过 50 个字符 |
| `4011` | `Unauthorized` | API Key 无效（仅在带 Key 调用时触发） |
| `4013` | `Forbidden` | API Key 已暂停 |
| `4014` | `Forbidden` | 当前 IP 不在 API Key 白名单内 |
| `4022` | `Payment Required` | 余额不足 |
| `4029` | `Too Many Requests` | 调用过快（QPS 限制） |
| `4030` | `Too Many Requests` | 今日免费额度已用完 |
| `4044` | `Not Found` | 未找到匹配的药材（响应里附带相关建议 suggestions） |
| `5000` | `Internal Server Error` | 中药数据库暂未就绪（运维问题，极少出现） |

## 9. 变更日志

- **1.0.0** (2026-05-06)
  - 首次发布
  - 基于《本草纲目》及网络公开整理数据
  - 精确匹配 + 模糊建议双模式查询
  - 匿名用户每日 30 次免费体验

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/bencao`

Source: `https://apizero.cn/aidocs/bencao/raw.md`
Last updated: 2026-05-11T16:16:07+08:00