适用场景与接口能力边界八字起名 API 提供三个核心动作actionnaming根据父母姓氏与出生时间智能生成名字综合八字五行、五格数理和三才配置评分附带寓意标签与重名预估。duplicate查询指定姓名在全国范围内的重名预估数量与等级。bazi仅返回指定出生时间的八字排盘与五行分析不涉及起名。该接口设计为生活服务类 API单用户 QPS 限制为 2 次/秒适合中小规模应用的后台调用。调用方应在客户端做好节流与重试逻辑避免触发限频。鉴权与请求头API 使用 API Key 进行鉴权。素材中 curl 示例使用X-API-Key头传递密钥但官方 Header 参数列表中列出的Authorization字段为requiredfalse实际接入时请以文档页https://apizero.cn/aidocs/baby-naming为准。建议优先采用X-API-Key方式二者选其一即可。# 请求头示例二选一 # 方式一X-API-Key X-API-Key: your_api_key_here # 方式二Authorization Authorization: Bearer your_api_key_here请求参数详解请求方法为POST地址https://v1.apizero.cn/api/baby-namingContent-Type 固定为application/json。参数名类型必填说明取值范围/示例actionstring否默认 naming选择动作naming/duplicate/bazisurnamestringnaming/duplicate 必填姓氏≤2汉字王mother_surnamestring否母姓填写后生成双姓名字李birth_yearnumbernaming/bazi 必填出生年份2000 – 2100如2026birth_monthnumbernaming/bazi 必填出生月份1 – 12如5birth_daynumbernaming/bazi 必填出生日期1 – 31如10birth_hournumber否默认12出生时辰24小时制0 – 23genderstring否默认neutral性别偏好male/female/neutralcountnumber否默认10返回候选名字数量1 – 30namestringduplicate 必填要查询重名的全名含姓氏王梓涵注意素材中参数表birth_year的 example 为字符串2026但其 type 为number。实际请求传入数字或字符串均可服务端可能做类型转换但建议按 type 传入数字以避免歧义。可复制的 curl 示例以下示例请求执行naming动作为姓氏“王”、出生日期 2026 年 5 月 10 日默认午时生成 5 个候选名字。curl -sS -X POST \ -H X-API-Key: YOUR_API_KEY \ -H Content-Type: application/json \ -d { action: naming, surname: 王, birth_year: 2026, birth_month: 5, birth_day: 10, count: 5, gender: male } \ https://v1.apizero.cn/api/baby-naming若需要查询重名使用actionduplicate并传入待查全名curl -sS -X POST \ -H X-API-Key: YOUR_API_KEY \ -H Content-Type: application/json \ -d { action: duplicate, name: 王梓森 } \ https://v1.apizero.cn/api/baby-naming返回值解读成功响应 HTTP 状态码为 200JSON 结构如下{ code: 0, msg: 成功, request_id: abc123, data: { bazi: { 八字: 丙午癸巳辛未癸巳, 四柱: [丙午, 癸巳, 辛未, 癸巳], 日主: 金 }, names: [ { surname: 王, given_name: 梓森, name: 王梓森, score: 95, wuge_score: 88, wuxing_chars: 木木, wuge: { 天格: 5, 人格: 15, 地格: 23, 外格: 16, 总格: 27 }, meaning_tags: [栋梁, 繁盛], duplicate_rate: { estimated_count: 320, level: 较低 } } ], needed_wuxing: [木], wu_xing_analysis: { 五行分布: {土: 1, 木: 0, 水: 2, 火: 4, 金: 1}, 五行缺失: [木], 建议补充: [木] } } }字段类型说明codeint0 表示成功非零为错误码msgstring状态描述request_idstring请求唯一标识可用于排查问题data.baziobject八字排盘结果仅 naming/bazi 时返回data.namesarray候选名字列表仅 naming 返回每个包含评分、五格、寓意标签、重名统计data.needed_wuxingarray命理所缺/建议补充的五行data.wu_xing_analysisobject出生时刻的五行分布、缺失与建议常见错误与排错指南401 Unauthorized现象返回 401 或{code: 401, msg: 验证失败}。原因API Key 未传递或传递格式错误。排错检查请求头是否包含X-API-Key或Authorization确认 Key 未过期、未泄漏空格。可先用 curl 的-v参数查看实际发送的 Header。400 Bad Request – 参数类型错误现象返回{code: 400, msg: 参数错误}通常伴随详细描述如birth_year must be a number。原因将字符串传入了数字字段或字段名拼写错误。排错对比 API 文档的字段名大小写全部小写 snake_case确保birth_year、birth_month、birth_day使用数字而非字符串。422 Unprocessable Entity – 必填字段缺失或越界现象{code: 422, msg: 缺少必填参数: surname}或birth_year must be between 2000 and 2100。原因action 为naming或bazi时缺少birth_year/birth_month/birth_day或年份超出范围。排错按上文参数表逐一核对必填条件注意mother_surname和gender为可选但不要传空对象。503 Service Unavailable – QPS 超限现象HTTP 503响应体可能包含{code: 503, msg: 请求频率过高}。原因单秒调用超过 2 次。排错加入本地节流令牌桶或退避重试检查是否有并发请求或循环中未加延迟。其他错误 – 姓名用字不在内置库现象返回{code: 400, msg: 姓氏不在支持列表中}或类似提示。原因API 内置 396 个姓氏笔画库、175 个起名字库极生僻字可能不支持。排错尝试更换常用姓氏或单字若需查询姓氏是否支持可调用baziaction 先行验证bazi不依赖姓名用字。网络层问题现象连接超时、DNS 解析失败、SSL 证书异常。原因客户端网络不通、防火墙拦截、或使用了不支持的 TLS 版本。排错用curl -v查看握手阶段确保 HTTPS 证书验证通过-k仅用于测试。工程化注意事项限流与重试QPS 上限 2建议在客户端使用指数退避重试如 1s、2s、4s最大 3 次避免短时内爆请求。缓存策略同一个出生时间组合的八字排盘结果baziaction几乎是确定的可缓存 24 小时起名结果受count、gender等影响可酌情缓存较短时间如 1 小时。日志记录记录每次请求的request_id和code便于后期排查错误日志中保留完整请求体脱敏 API Key。参数校验前置在调用前在客户端先校验年份范围2000-2100、月份1-12、日期1-31、姓氏长度≤2 字减少无效调用。错误码对照表建立本地映射将code转为可读提示如503→服务繁忙请稍后重试。参考文档八字起名 API 文档页面 – 最新参数、示例与更新记录。原始文档 Markdown – 可用于离线集成。注本文仅提供技术集成指南接口的可用性与数据准确性以官方文档为准。