# 藏头诗生成：5 分钟接入，从注册到第一行诗句
> 接口/接入点：藏头诗生成（apiCode=950，接入点 950-1）· 免费 · 请求方式 POST/GET · 返回格式 JSON · 适用人群：新注册用户、初级开发者、文案/运营 · 阅读时间：5 分钟
## 核心要点
- 接口免费，注册即送可调用档位；调用只需 4 个参数（`num`/`type`/`yayuntype`/`key`）。
- 鉴权用 query 里的 `appKey`，无需额外签名；返回统一包裹在 `showapi_res_body` 内。
- 三行代码即可拿到诗句：请求 → 判断 `ret_code` → 遍历 `list` 输出。
## Why：这跟我有什么关系
做新媒体、活动运营、文创或表白文案时，经常需要"有诗意又带特定字"的句子。藏头诗生成接口把这件事变成一次 API 调用：你给关键字（如对方名字），它返回多首藏头诗句，直接用于祝福卡、海报、情书、签名档。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/950-1?appKey={your_appKey}` |
| 接入点 | 950-1（本接口仅此一个接入点） |
| 请求方式 | POST / GET |
| 鉴权 | query 参数 `appKey` |
| 返回格式 | JSON |
| 计费 | 免费（注册后默认可调用，有使用档次限制） |
| 更新频率 | 以官方接口为准（as-needed） |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档（无订阅推送/批量） |
**必填请求参数**：`num`（五言=5/七言=7）、`type`（1藏头/2藏尾/3藏中/4递增/5递减）、`yayuntype`（1双句一压/2双句押韵/3一三四押）、`key`（要藏入的句/字，最多八个字）。
## How：第一次调用
### 步骤 1：获取 AppKey
登录易源控制台 → [AppKey 管理](https://www.showapi.com/console#/myApp) → 复制你的 AppKey，替换下面代码中的 `YOUR_APPKEY`。
### 步骤 2：发起请求并解析
下面以 `key=易源接口`、五言藏头、双句一压为例。
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/950-1"
params = {"appKey": "YOUR_APPKEY"}
data = {
"num": "5", # 5=五言, 7=七言
"type": "1", # 1藏头 2藏尾 3藏中 4递增 5递减
"yayuntype": "1", # 1双句一压 2双句押韵 3一三四押
"key": "易源接口", # 要藏入的句/字，最多八个字
}
try:
r = requests.post(url, params=params, data=data, timeout=30)
r.raise_for_status()
res = r.json()
body = res.get("showapi_res_body", {})
if body.get("ret_code") != "0":
print("调用失败:", res.get("showapi_res_error"))
else:
for poem in body["list"]: # list 为字符串数组，每首独立成项
print(poem)
except requests.RequestException as e:
print("请求异常:", e)
```
**Node.js（fetch）**
```javascript
const url = "https://route.showapi.com/950-1?appKey=YOUR_APPKEY";
const body = new URLSearchParams({
num: "5",
type: "1",
yayuntype: "1",
key: "易源接口",
});
try {
const resp = await fetch(url, { method: "POST", body, signal: AbortSignal.timeout(30000) });
const res = await resp.json();
const b = res.showapi_res_body;
if (b.ret_code !== "0") {
console.error("调用失败:", res.showapi_res_error);
} else {
b.list.forEach((poem) => console.log(poem));
}
} catch (e) {
console.error("请求异常:", e);
}
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/950-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "num=5&type=1&yayuntype=1&key=%E6%98%93%E6%BA%90%E6%8E%A5%E5%8F%A3"
```
> 注：`list` 在 OpenAPI schema 中标注为 string，但官方返回示例实为**字符串数组**，按数组遍历即可。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": "0",
"list": [
"易识浮生理，源发在深空。接叶制茅亭，口眼不相营。",
"易成还易衰，源出昆仑中。接武在文章，口传不死方。",
"易此从远方，源水不离秦。接膝犹嫌远，口宣雨露言。"
]
}
}
```
`showapi_res_body.list` 即为多首诗句；`ret_code` 为 `"0"` 表示成功。
## 进阶 / 边界
- 免费接口有使用档次限制，高频场景见[藏头诗生成：免费档位与积分兑换，如何控制调用成本](https://www.showapi.com/guides/cangtoushi-cache-cost-950)。
- `key` 最多八个字，超长会被截断或影响成诗质量，详见[藏头诗生成：key 参数怎么写效果最好](https://www.showapi.com/guides/cangtoushi-key-optimize-950)。
## FAQ
**Q1：返回 401/无数据？** 检查 AppKey 是否替换、是否在控制台启用；确认接口地址带 `?appKey=`。
**Q2：ret_code 非 0 怎么办？** 取 `showapi_res_error` 看具体信息，按[错误处理与超时](https://www.showapi.com/guides/cangtoushi-error-handle-950)排查。
**Q3：能一次出七言吗？** 把 `num` 改为 `7` 即可。
**Q4：有批量接口吗？** 本接口为同步请求-响应，无批量/订阅推送；多组需客户端循环调用，见[节日祝福批量实战](https://www.showapi.com/guides/cangtoushi-blessing-950)。
## 相关能力 / 下一步阅读
- [藏头诗生成：返回字段全解（list / ret_code / showapi_res_*）](https://www.showapi.com/guides/cangtoushi-response-fields-950)
- [藏头诗生成：藏头/藏尾/藏中/递增/递减五种玩法（type 参数全解）](https://www.showapi.com/guides/cangtoushi-acrostic-tail-950)
- **本系列共 12 篇**：查看[藏头诗生成指南总目录](https://www.showapi.com/guides/cangtoushi-guides-950)
