适用场景与接口能力概述在开发面向新生儿起名、游戏角色命名或品牌命名的应用时往往需要结合传统文化中的八字五行、五格数理与三才配置进行综合评分。八字起名API正是为此类需求设计它通过输入父母姓氏与出生时间返回按综合评分排序的名字候选列表并附有寓意标签、全国重名预估以及八字分析结果。该接口归属于生活服务分类采用RESTful POST方式调用官方提供三个action动作naming默认智能起名返回多个候选名及其评分、五格数理、五行属性等。duplicate重名查询输入姓氏和名字返回全国重名预估。bazi八字查询仅返回出生时间的八字四柱、五行分布及弥补建议。接口内置396个姓氏笔画库、175个起名用字库和88个姓人口数据QPS限制为2次/秒适合个人开发者或中小型服务的低频调用场景。接口能力边界起名范围仅支持简体中文汉字姓氏最长2字名字长度由API内部算法决定通常2字名。出生年份20002100年月份112日期131时辰023默认12。性别偏好可选male/female/neutral影响名字用字倾向。返回数量count参数控制130个候选名默认10个。双姓名填写mother_surname后可生成父姓母姓的双姓名如“王李XX”但需注意双姓名在五格数理计算上的特殊性。局限性不提供音频读音、拼音等附加信息重名预估基于历史人口统计非实时数据QPS限制较低高并发场景需做队列或降级处理。请求参数与鉴权鉴权方式无需强制鉴权但受限于QPS建议通过API Key识别使用者。Header中可传入Authorization字段Bearer Token形式或使用自定义HeaderX-API-Key如curl示例所示。获取API Key的方式详见官方文档。请求体字段详解字段名类型必填说明actionstring否动作类型naming/duplicate/bazi默认namingsurnamestring是naming/duplicate姓氏最多2字mother_surnamestring否母姓仅naming可用填写则生成双姓名birth_yearnumber是naming/bazi出生年份2000-2100birth_monthnumber是naming/bazi出生月份1-12birth_daynumber是naming/bazi出生日1-31birth_hournumber否出生时辰0-23默认12午时genderstring否性别偏好male/female/neutral默认neutralcountnumber否返回名字数量1-30默认10namestring是duplicate要查询重名的名字不含姓氏注意当action为bazi时只需提供birth_year、birth_month、birth_day、birth_hour可选surname非必填当action为duplicate时必须提供surname和name。curl接入示例以下演示三种action的调用方式。请先将您的API Key设置为环境变量$APIZERO_API_KEY。1. 智能起名namingcurl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { action: naming, surname: 张, mother_surname: , birth_year: 2025, birth_month: 8, birth_day: 15, birth_hour: 14, gender: male, count: 5 } \ https://v1.apizero.cn/api/baby-naming2. 重名查询duplicatecurl -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-naming3. 八字查询bazicurl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { action: bazi, birth_year: 2025, birth_month: 8, birth_day: 15, birth_hour: 14 } \ https://v1.apizero.cn/api/baby-naming响应字段解析成功响应的HTTP状态码为200返回JSON格式结构如下{ code: 0, msg: 成功, request_id: abc123, data: { bazi: { /* 八字信息 */ }, wu_xing_analysis: { /* 五行分析 */ }, needed_wuxing: [木], names: [ /* 候选名数组 */ ] } }核心字段说明data.bazi八字完整四柱八字字符串如 丙午 癸巳 辛未 癸巳。四柱数组形式分别对应年柱、月柱、日柱、时柱。日主出生日的天干对应的五行属性如 金。data.wu_xing_analysis五行分布各五行出现次数统计土、木、水、火、金。五行缺失列表形式如 [木]。建议补充算法建议的五行属性列表。data.names[]仅naming返回每个候选名对象包含字段类型说明surnamestring姓氏given_namestring名字不含姓氏namestring全名scorenumber综合评分0-100越高越好wuge_scorenumber五格数理评分0-100wugeobject天格、人格、地格、外格、总格数理值wuxing_charsstring名字字形的五行组合如 木木meaning_tagsstring[]寓意标签如 [栋梁, 繁盛]duplicate_rateobject重名预估estimated_count预估人数level较低/中等/较高注意duplicate_rate.estimated_count为历史人口统计估算非实时数据仅供参考。常见错误与处理错误表现可能原因解决方案HTTP 400缺少必填参数或参数值非法检查surname、birth_year等必填字段年份范围2000-2100月份1-12日期1-31HTTP 401/403API Key无效或未传确认环境变量$APIZERO_API_KEY已设置或检查Authorization头HTTP 429QPS超过2次/秒增加调用间隔或添加本地重试机制指数退避code ! 0业务错误msg中描述原因根据msg调整参数如name字数超限、不支持的汉字返回空names未找到符合条件的高分名字调整gender、count或更换姓氏重新尝试工程化注意事项1. 参数预校验在调用前应本地校验姓氏长度 ≤ 2且只含汉字。出生年月日必须合法考虑闰年、2月天数等。count在1-30之间。2. 结果缓存策略同一出生时间搭配同一姓氏的起名结果通常不会变化建议将actionnaming的结果以{surname}_{birth_year}_{birth_month}_{birth_day}_{birth_hour}为key缓存到本地或Redis减少重复调用。3. 并发控制QPS只有2如果应用需要轮询多个候选方案建议引入队列或控制并发数。可以使用令牌桶算法限制每秒最多2个请求。4. 错误重试对于429状态码实现指数退避重试如第一次重试间隔1秒第二次2秒第三次4秒最多3次。5. 重名预估数据的呈现duplicate_rate.estimated_count仅为历史估算值在UI中建议加注“数据基于历史人口统计仅供参考”避免用户误解为实时精确数据。6. 请求超时设置由于API响应时间取决于计算复杂度建议客户端超时设置为10秒以上默认网络超时可能为5秒。参考文档八字起名API官方文档原始接口文档Markdown本文仅做技术接口接入参考如需获取最新参数及版本更新请以上述文档为准。