给起名工具接入八字起名 API：参数设计、JSON 示例和应用场景

做宝宝起名、姓名推荐、小程序取名工具时，接口最核心的价值不是只返回一个名字，而是把出生时间、五行分析、名字评分、寓意标签和重名预估组合成一份结构化结果。ApiZero 的 baby-naming 接口就是这样一个 POST JSON API，适合直接接入 Web 页面、后台服务、App 或小程序后端。

本文用一篇 CSDN 接口文档的方式，把八字起名 API 的请求方式、参数含义、返回结构和 Python/JavaScript 调用示例整理出来，方便开发时直接参考。

接口介绍

八字起名 API 的接口能力主要分为三个 action：

action	作用	适合场景
`naming`	智能起名，默认 action	根据姓氏和出生时间生成名字候选
`duplicate`	重名查询	查询指定姓名组合的重名预估
`bazi`	八字查询	单独返回出生时间对应的八字和五行分析

接口会围绕「八字五行 + 五格数理 + 三才配置」生成名字候选，并在结果里返回分数、五格、五行组合、寓意标签和重名预估字段。对于需要做起名结果页、名字推荐列表、候选名对比页的项目，这种结构化返回会比较好处理。

基本接入信息

项目	内容
请求地址	`https://v1.apizero.cn/api/baby-naming`
请求方法	`POST`
Content-Type	`application/json`
鉴权方式	`Authorization: Bearer <你的 API Key>`
返回格式	JSON

请求头示例：

http 复制代码

Content-Type: application/json
Authorization: Bearer <你的 API Key>

请求参数

参数名	类型	是否必填	说明
`action`	string	否	`naming` / `duplicate` / `bazi`，默认 `naming`
`surname`	string	条件必填	`naming`、`duplicate` 必填，姓氏，建议不超过 2 个字
`mother_surname`	string	否	母姓，`naming` 场景可选，填写后可生成双姓名
`birth_year`	number	条件必填	`naming`、`bazi` 必填，出生年份
`birth_month`	number	条件必填	`naming`、`bazi` 必填，出生月份
`birth_day`	number	条件必填	`naming`、`bazi` 必填，出生日期
`birth_hour`	number	否	出生时辰，0-23，默认按中午处理
`gender`	string	否	性别偏好：`male` / `female` / `neutral`，默认 `neutral`
`count`	number	否	返回名字数量，默认返回一组候选
`name`	string	条件必填	`duplicate` 必填，要查询的名字，不含姓

最常用的智能起名请求体如下：

json 复制代码

{
  "action": "naming",
  "surname": "王",
  "birth_year": 2026,
  "birth_month": 5,
  "birth_day": 10,
  "birth_hour": 10,
  "gender": "neutral",
  "count": 2
}

如果只想查询八字和五行分析，可以把 action 设置为 bazi：

json 复制代码

{
  "action": "bazi",
  "birth_year": 2026,
  "birth_month": 5,
  "birth_day": 10,
  "birth_hour": 10
}

如果要查询某个名字的重名预估，可以使用 duplicate：

json 复制代码

{
  "action": "duplicate",
  "surname": "王",
  "name": "梓涵"
}

返回字段

智能起名的返回结果主要看 data 下的几个字段：

字段	类型	说明
`bazi.八字`	string	八字字符串
`bazi.四柱`	array	年、月、日、时四柱
`bazi.日主`	string	日主五行
`wu_xing_analysis`	object	五行分布、缺失项和建议补充项
`needed_wuxing`	array	建议补充的五行
`names`	array	推荐名字列表
`names[].name`	string	完整姓名
`names[].given_name`	string	名字部分
`names[].score`	number	综合评分
`names[].wuge`	object	天格、人格、地格、外格、总格
`names[].wuge_score`	number	五格评分
`names[].wuxing_chars`	string	名字用字五行组合
`names[].meaning_tags`	array	寓意标签
`names[].duplicate_rate`	object	重名预估信息

返回示例：

json 复制代码

{
  "code": 0,
  "msg": "成功",
  "data": {
    "bazi": {
      "八字": "丙午癸午甲戌己巳",
      "四柱": ["丙午", "癸午", "甲戌", "己巳"],
      "日主": "木"
    },
    "wu_xing_analysis": {
      "五行分布": {
        "金": 0,
        "木": 1,
        "水": 1,
        "火": 4,
        "土": 2
      },
      "五行缺失": ["金"],
      "建议补充": ["金"]
    },
    "needed_wuxing": ["金"],
    "names": [
      {
        "name": "王培铭",
        "surname": "王",
        "given_name": "培铭",
        "score": 87.9,
        "wuge": {
          "天格": 5,
          "人格": 15,
          "地格": 25,
          "外格": 18,
          "总格": 29
        },
        "wuge_score": 100,
        "wuxing_chars": "土+金",
        "meaning_tags": ["培养", "铭记"],
        "duplicate_rate": {
          "estimated_count": 257,
          "level": "较低",
          "description": "预估全国约有 257 人与此同名同姓"
        }
      }
    ]
  },
  "request_id": "req_example"
}

curl 调用示例

bash 复制代码

curl -X POST 'https://v1.apizero.cn/api/baby-naming' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <你的 API Key>' \
  -d '{
    "action": "naming",
    "surname": "王",
    "birth_year": 2026,
    "birth_month": 5,
    "birth_day": 10,
    "birth_hour": 10,
    "gender": "neutral",
    "count": 2
  }'

Python 调用示例

Python 后端可以用 requests 直接调用。实际项目里建议把 API Key 放到环境变量或密钥管理服务中。

python 复制代码

import os
import requests

url = "https://v1.apizero.cn/api/baby-naming"
api_key = os.getenv("APIZERO_API_KEY", "<你的 API Key>")

payload = {
    "action": "naming",
    "surname": "王",
    "birth_year": 2026,
    "birth_month": 5,
    "birth_day": 10,
    "birth_hour": 10,
    "gender": "neutral",
    "count": 2,
}

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}",
}

response = requests.post(url, json=payload, headers=headers, timeout=15)
response.raise_for_status()

result = response.json()
if result.get("code") == 0:
    data = result["data"]
    print("八字：", data["bazi"]["八字"])
    for item in data.get("names", []):
        print(item["name"], item["score"], item["meaning_tags"])
else:
    print("接口返回：", result.get("msg"))

在业务里可以把 names 数组映射成候选名卡片，例如展示完整姓名、评分、五行组合、寓意标签和重名预估描述。

JavaScript 调用示例

如果是在 Node.js 服务端或前端代理层中接入，可以使用 fetch：

javascript 复制代码

const url = "https://v1.apizero.cn/api/baby-naming";

const payload = {
  action: "naming",
  surname: "王",
  birth_year: 2026,
  birth_month: 5,
  birth_day: 10,
  birth_hour: 10,
  gender: "neutral",
  count: 2,
};

const res = await fetch(url, {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    Authorization: "Bearer <你的 API Key>",
  },
  body: JSON.stringify(payload),
});

const json = await res.json();

if (json.code === 0) {
  const names = json.data.names || [];
  const options = names.map((item) => ({
    label: item.name,
    score: item.score,
    wuxing: item.wuxing_chars,
    tags: item.meaning_tags,
    duplicate: item.duplicate_rate?.description,
  }));

  console.log(options);
}

适合接入的页面和功能

这个接口比较适合放在需要「输入信息 -> 生成候选结果 -> 展示详情」的产品流程里，例如：

场景	接入方式
宝宝起名工具	表单收集姓氏、出生时间、性别偏好，调用 `naming` 返回名字候选
姓名推荐页面	用 `names` 数组渲染多个候选名卡片
八字五行分析页	用 `bazi` 和 `wu_xing_analysis` 展示基础分析结果
重名查询组件	用 `duplicate` 查询指定姓名的预估重名情况
内容运营工具	批量生成候选名，再由人工选择适合展示的结果

返回结构里的 score、wuge_score、wuxing_chars、meaning_tags 都很适合直接做前端展示。比如一个候选名卡片可以包含：

姓名：王培铭
综合评分：87.9
五行组合：土+金
寓意标签：培养、铭记
重名预估：预估全国约有 257 人与此同名同姓

这样前端不需要再额外拼大量解释文本，直接按字段组合就能形成比较完整的结果页。