场景与定位
八字起名是一个典型的生活服务类接口，适用的产品形态比较明确：面向家长群体的起名工具、母婴社区的小程序、内容平台里的姓名分析插件，以及企业内部用来做批量姓名生成的辅助脚本。
这类接口的核心价值不在于“算得准”，而在于把一套复杂的规则（八字五行、五格数理、三才配置、姓名笔画、重名率）封装成一次 HTTP POST，让前端或后端同学用少量代码就能获得结构化结果。这样团队就不需要自己维护姓名库、笔画库和评分逻辑。
接口能力边界
接口地址为https://v1.apizero.cn/api/baby-naming，请求方法为 POST，QPS 限制为 2 次/秒。三种 action 分别对应：
| action 值 | 用途 | 必填参数 |
|---|---|---|
naming | 智能起名，返回评分与推荐名 | surname、birth_year、birth_month、birth_day |
duplicate | 查询某个姓名的重名情况 | surname、name |
bazi | 仅返回八字与五行分析 | birth_year、birth_month、birth_day |
其中naming是默认行为，不传 action 时即为智能起名。birth_hour当前默认 12，代表午时；gender可选 male/female/neutral，默认 neutral；count控制返回名字数量，范围 1 到 30，默认 10。
内置数据方面，接口覆盖 396 个姓氏的笔画、175 个起名字、88 个姓氏人口信息，因此在名称与姓氏的匹配上有一定的规则支撑。但要注意，这里的“评分”是接口内部的算法结果，无法在文档中看到完整的权重公式，接入方应当把它视作一个黑盒输出，而不是可解释的判词。
鉴权与请求参数
Header
调用时在请求头中携带 API Key：
X-API-Key: {你的_API_Key} Content-Type: application/json文档中 Authorization 为可选参数，实践中通常使用X-API-Key作为主鉴权方式。具体以你拿到的凭证说明为准。
请求体字段
下面以namingaction 为例，逐一说明字段含义：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| action | string | 否 | naming（默认）/ duplicate / bazi |
| surname | string | 是 | 姓氏，≤2 字，naming/duplicate 必填 |
| mother_surname | string | 否 | 母姓，仅在 naming 下生效，填写后生成双姓名 |
| birth_year | number | 否 | 出生年，范围 2000-2100，naming/bazi 必填 |
| birth_month | number | 否 | 出生月，1-12，naming/bazi 必填 |
| birth_day | number | 否 | 出生日，1-31，naming/bazi 必填 |
| birth_hour | number | 否 | 出生时辰，0-23，默认 12 |
| gender | string | 否 | male/female/neutral，默认 neutral |
| count | number | 否 | 返回名字数量，1-30，默认 10 |
| name | string | 否 | duplicate 时必填，表示要查询重名率的姓名 |
注意birth_year、birth_month、birth_day在文档示例里带双引号，属于字符串类型；但在字段定义中类型为 number。两种写法在绝大多数后端 JSON 解析器中都能兼容，不过为了减少 lint 告警，建议发送时统一使用数字类型。
curl 接入示例
先从最简单的 curl 开始。以下请求使用naming获取 5 个候选名：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "naming", "surname": "王", "birth_year": 2026, "birth_month": 5, "birth_day": 10, "birth_hour": 10, "count": 5 }' \ "https://v1.apizero.cn/api/baby-naming"如果只需要查询“梓涵”这个名的重名情况：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "duplicate", "surname": "王", "name": "梓涵" }' \ "https://v1.apizero.cn/api/baby-naming"注意：
APIZERO_API_KEY是环境变量占位符，运行前请换成你自己的 Key。
Python 调用与结果解析
在实际项目中，通常不会直接跑 curl，而是把接口封装成一个函数。下面是一个用requests实现的示例：
import os import requests API_URL = "https://v1.apizero.cn/api/baby-naming" HEADERS = { "X-API-Key": os.environ["APIZERO_API_KEY"], "Content-Type": "application/json", } def fetch_names(surname, birth_year, birth_month, birth_day, birth_hour=12, count=10): payload = { "action": "naming", "surname": surname, "birth_year": birth_year, "birth_month": birth_month, "birth_day": birth_day, "birth_hour": birth_hour, "count": count, } resp = requests.post(API_URL, json=payload, headers=HEADERS, timeout=10) resp.raise_for_status() body = resp.json() if body.get("code") != 0: raise RuntimeError(f"API error: {body.get('msg')}") return body["data"] def format_result(data): print("五行分布:", data["wu_xing_analysis"]["五行分布"]) print("五行缺失:", data["wu_xing_analysis"]["五行缺失"]) print("建议补充:", data["wu_xing_analysis"]["建议补充"]) print("八字:", data["bazi"]["八字"]) for item in data["names"]: print( f"{item['name']} 评分={item['score']} " f"五格评分={item['wuge_score']} 标签={item['meaning_tags']}" ) if __name__ == "__main__": # 示例入参：2026 年 5 月 10 日 10 时出生的王姓宝宝 result = fetch_names("王", 2026, 5, 10, count=5) format_result(result)代码里做了三件事：构造 JSON 请求体、检查业务状态码、提取 names 列表。之所以设置timeout=10，是为了避免接口异常时请求长时间挂起影响主流程。
返回参数解读
以naming为例，响应结构分为三层：
1. 顶层字段
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 状态描述 |
| request_id | string | 请求唯一标识，排障时可提供给服务方 |
| data | object | 核心业务数据 |
2. data 对象
包含四个子对象：
bazi：八字结果，包括“八字”字符串、四柱数组、日主五行wu_xing_analysis：五行统计、缺失五行、建议补充五行needed_wuxing：需要补充的五行列表names：候选名字数组
注意bazi和wu_xing_analysis的中文键名，比如“八字”“四柱”“五行分布”，在 JSON 中会原样输出，后端拿到后建议做一层字段映射，避免业务代码里四处写中文键。
3. names 内部字段
| 字段名 | 类型 | 示例 | 说明 |
|---|---|---|---|
| name | string | 王梓森 | 完整姓名 |
| surname | string | 王 | 姓氏 |
| given_name | string | 梓森 | 名 |
| score | int | 95 | 综合评分 |
| wuge_score | int | 88 | 五格数理评分 |
| wuxing_chars | string | 木+木 | 名字的五行组合 |
| meaning_tags | array | ["栋梁", "繁盛"] | 寓意标签 |
| wuge | object | 天格 5 / 人格 15 / 地格 23 / 外格 16 / 总格 27 | 五格数值 |
| duplicate_rate | object | 见下 | 重名预估 |
duplicate_rate内部包含estimated_count（全国预估重名人数）、level（较低/中等/较高等）、description（说明文案）。该预估并非实时户籍数据，而是一个模型估算值，作为产品展示时建议标注“仅供参考”。
常见调用问题与排查
1. 返回 code 非 0
先检查是否满足对应 action 的必填条件。比如bazi不需要 surname，但naming必须传；duplicate必须同时传 surname 和 name。
2. HTTP 4xx / 5xx
- 401：API Key 缺失或格式不对，确认 header 名是
X-API-Key - 404：确认请求地址没有拼错，不要带上多余路径
- 429：超过 QPS 限制，加入本地限流或退避重试
3. 参数边界问题
birth_year 必须在 2000-2100，birth_month 必须在 1-12，birth_day 必须在 1-31。前端传入日期字符串时，后端要先把字符串转成数字再传给接口，避免类型不一致引发校验失败。
4. 名字数据为空
如果names数组为空，可能是给定参数下没有满足评分阈值的组合。此时可以放宽 count、调整 gender 或换一个 birth_hour 后重试。
工程化注意事项
这部分是接入时容易被忽略的点，建议在联调前就处理好。
缓存策略
同一天同一个出生时间点的八字结果和五行分析是固定的，适合做缓存。可以用出生年月日时作为缓存键前缀，TTL 设置为 1 天即可。这样既降低 QPS 压力，也让重复查询的响应更快。
请求频率控制
接口 QPS 为 2 次/秒，单机并发场景基本够用，但要避免在循环里无脑调用。建议客户端封装一个简单的令牌桶或信号量，把请求速率压到 1.5 QPS 左右，留出余量。
结果展示上的取舍
接口返回的候选名包含评分、五行、五格、寓意标签、重名预估，不是所有字段都要展示给用户。面向普通用户时，建议只展示评分、寓意标签和重名等级，把五行分布、四柱等专业内容折叠到“详情”里，降低阅读负担。
数据映射层
由于响应字段包含中文键名，团队内应统一建一个 DTO（数据传输对象）或数据类来做字段名转换。例如 Python 里可以写一个NameCandidate的 dataclass，把wuge_score、meaning_tags解析为英文属性，这样后续渲染模板和单元测试都更可控。
参考文档
- 接口文档页：https://apizero.cn/aidocs/baby-naming
- 原始文档（raw.md）：https://apizero.cn/aidocs/baby-naming/raw.md