当前位置：首页 > news >正文

八字起名接口接入笔记：请求参数、返回字段与工程化落地

news 2026/8/6 0:48:18

场景与定位

八字起名是一个典型的生活服务类接口，适用的产品形态比较明确：面向家长群体的起名工具、母婴社区的小程序、内容平台里的姓名分析插件，以及企业内部用来做批量姓名生成的辅助脚本。

这类接口的核心价值不在于“算得准”，而在于把一套复杂的规则（八字五行、五格数理、三才配置、姓名笔画、重名率）封装成一次 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	见下	重名预估