适用场景概述八字起名 API 面向需要根据出生时间、姓氏等信息自动生成符合中国传统命理学的名字候选的场景。典型的用户群体包括新生儿命名服务父母提供孩子出生时刻、父母姓氏接口返回多组包含五行补益、五格数理评分和重名预估的名字结果。起名辅助工具集成到移动端 App 或微信小程序中作为智能起名模块的核心后端。重名查询输入一个名字接口预估全国重名人数及重名等级适合用户确认名字是否有较高重复率。八字排盘仅输入出生时间返回八字四柱、五行分布及缺失信息可作为独立八字查询功能。该接口将三个子功能naming / duplicate / bazi统一封装为一个端点开发者只需更改 action 参数即可复用同一套鉴权和请求结构降低了集成复杂度。接口能力边界5. 功能边界子功能action 值必填参数返回核心数据智能起名naming默认surname, birth_year, birth_month, birth_day名字列表含寓意标签、五行属性、五格数理、重名预估、综合评分重名查询duplicatesurname, name全国预估重名人数及等级八字查询bazibirth_year, birth_month, birth_day八字四柱、日主五行、五行分布及缺失5. 参数约束边界姓氏 (surname)≤2 个汉字仅支持常见姓氏。接口内置 396 个姓氏的笔画数据超出范围的姓氏可能返回笔画缺失或评分不准确。父母姓氏双姓 (mother_surname)可选填写后生成包含父姓和母姓的四个字名字如“王李铭轩”。需确保母姓也在内置集内。出生时间范围出生年份必须在 2000–2100 之间月份 1–12日 1–31小时 0–23可选默认 12 时。若需精确时辰建议传入birth_hour使八字排盘更准确。性别偏好 (gender)可选 male / female / neutral默认 neutral。接口内部会根据性别调整用字偏好的权重。名字数量 (count)1–30默认 10。注意返回数量受候选池限制若请求 30 个但未找到足够高分的名字可能少于 30 个。QPS 限制2 次/秒。超过限制会返回 429 状态码。对于高并发场景建议客户端做限流或使用队列。5. 数据来源与局限性名字库内置 175 个起名字常见汉字并非所有汉字均可使用。若用户指定名字包含库外汉字接口在 duplicate 或 naming 中可能无法计算相关笔画或五格。重名预估基于 88 个常见姓氏的人口统计数据对罕见姓氏的预估偏差较大。文档中duplicate_rate.estimated_count为近似值不应作为精确统计使用。八字五行分析仅基于出生时间未考虑真太阳时或出生地点经纬度修正对于专业星座/命理场景可能存在误差。鉴权与请求头接口使用X-API-Key自定义 Header 传递密钥。在请求中需要设置X-API-Key: YOUR_API_KEY Content-Type: application/jsonAuthorization 参数虽在字段中列出但并非强制requiredfalse建议仍按上述方式使用。请求参数详解请求体为 JSON 格式核心字段如下参数类型必填说明actionstring否naming / duplicate / bazi默认 namingsurnamestring是naming/duplicate姓氏≤2 字mother_surnamestring否母姓用于生成双姓名字birth_yearnumber是naming/bazi出生年份2000-2100birth_monthnumber是naming/bazi出生月份1-12birth_daynumber是naming/bazi出生日1-31birth_hournumber否出生时辰0-23默认 12genderstring否male / female / neutralcountnumber否返回名字数量1-30默认 10namestring是duplicate要查询重名的名字不含姓氏注意action为 duplicate 时必须提供surname和name为 bazi 时只提供surname虽然 bazi 不需要姓氏但接口要求仍传surname作为占位建议传空字符串或固定值。具体以官方文档为准。curl 请求示例智能起名namingcurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { action: naming, surname: 张, mother_surname: 李, birth_year: 2024, birth_month: 10, birth_day: 15, birth_hour: 8, gender: male, count: 5 } \ https://v1.apizero.cn/api/baby-naming重名查询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-naming八字查询bazicurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { action: bazi, surname: , birth_year: 2024, birth_month: 10, birth_day: 15, birth_hour: 8 } \ https://v1.apizero.cn/api/baby-naming请将环境变量APIZERO_API_KEY替换为实际密钥。返回值字段解读以 naming 返回为例响应 JSON 结构已节选顶层字段字段类型说明codeint业务状态码0 表示成功非 0 表示错误msgstring状态描述request_idstring请求唯一标识可用于日志追踪dataobject具体数据data 对象bazi对象包含八字信息。八字字符串如“丙午癸巳辛未癸巳”四柱数组四个干支字符串日主字符串日干五行金木水火土needed_wuxing数组建议补充的五行如[木]wu_xing_analysis对象包含五行分布、缺失和建议补充五行分布对象各五行计数五行缺失数组缺失的五行建议补充数组需补充的五行names数组名字候选列表。每个元素包含name全名如“张梓森”surname姓氏given_name名字score综合评分0-100 整数越高越好meaning_tags寓意标签数组如[栋梁,繁盛]wuge五格数理各格数值天格、人格、地格、外格、总格wuge_score五格评分0-100wuxing_chars名字汉字的五行组合如“木木”duplicate_rate重名预估对象包含estimated_count全国预估人数、level等级如“较低”、description描述文字关于评分参参考系score是基于八字五行补益、五格数理、三才配置及用字含义的综合打分满分 100。通常 90 分以上为佳选。wuge_score只反映五格数理方面的得分可能高于或低于综合分。常见错误与处理建议错误场景可能的 HTTP 状态码错误码解决措施API Key 无效或缺失401-检查 Header 中 X-API-Key 是否正确参数校验失败如年份超出范围4001001按字段约束纠正参数超过 QPS 限制429-降低请求频率或加入重试逻辑退避姓氏不在内置集200非 0如 2001更换为常见姓氏或联系平台更新库起名时未找到足够符合要求的名字2000但 names 数组长度小于 count接受现有结果或放宽性别/数量参数特别注意接口返回业务错误时通常 status 仍为 200需通过code字段判断。常见业务错误码可查阅官方文档。工程化注意事项缓存策略对于一个相同的出生时间组合起名结果在一定时间内是确定性的假设算法不更新。可在服务端缓存结果以减少重复调用但注意缓存过期后应重新拉取。降级处理当接口不可用或限流时前端应展示缓存数据或友好提示避免空白页面。异步与超时建议设置合理的 HTTP 超时如 5 秒对超时请求进行重试最多 2 次指数退避。名称审核接口返回的名字可能包含不适用的字如方言谐音建议集成二次筛选逻辑或人工审核。QPS 预留2 QPS 对于多数个人项目足够但若存在并发用户建议在客户端做请求队列或使用消息队列削峰。参考文档八字起名 API 原始文档API 控制台与密钥管理本文仅作为技术对接参考接口行为以官方最新文档为准。