<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 八字起名

> 输入父母姓氏与出生时间，基于「八字五行 + 五格数理 + 三才配置」综合评分生成高分名字候选，附寓意标签与全国重名预估。三个 action：naming（智能起名）/ duplicate（重名查询）/ bazi（八字查询）。内置 396 姓氏笔画 + 175 起名字 + 88 姓人口。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `baby-naming` |
| 接口名称 | 八字起名 |
| 接口地址 | `https://v1.apizero.cn/api/baby-naming` |
| 请求方法 | `POST` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 2 req/s |
| 每日免费额度 | 50 次（已认证用户） |
| 匿名每日额度 | 30 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名可调用：QPS 1 / 每日 30 次。登录用户：QPS 2 / 每日 50 次。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `action` | `string` | 否 | naming（默认）/ duplicate / bazi | — |
| `surname` | `string` | 是 | naming/duplicate 必填；姓氏（≤ 2 字） | `王` |
| `mother_surname` | `string` | 否 | 母姓（仅 naming，可选；填写则生成双姓名） | — |
| `birth_year` | `number` | 否 | naming/bazi 必填；2000-2100 | `2026` |
| `birth_month` | `number` | 否 | naming/bazi 必填；1-12 | `5` |
| `birth_day` | `number` | 否 | naming/bazi 必填；1-31 | `10` |
| `birth_hour` | `number` | 否 | 出生时辰；0-23，默认 12 | — |
| `gender` | `string` | 否 | 性别偏好：male/female/neutral，默认 neutral | — |
| `count` | `number` | 否 | 返回名字数量；1-30，默认 10 | — |
| `name` | `string` | 否 | duplicate 必填；要查的名字（不含姓） | `梓涵` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | — | — |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/baby-naming" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "<action>",
  "surname": "王",
  "mother_surname": "<mother_surname>",
  "birth_year": "2026",
  "birth_month": "5",
  "birth_day": "10",
  "birth_hour": "<birth_hour>",
  "gender": "<gender>",
  "count": "<count>",
  "name": "梓涵"
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `bazi.八字` | `string` | 八字字符串 | — |
| `bazi.四柱` | `array` | 年/月/日/时四柱 | — |
| `bazi.日主` | `string` | 日主五行 | — |
| `wu_xing_analysis` | `object` | 五行分布 / 缺失 / 建议补充 | — |
| `needed_wuxing` | `array` | 建议补充的五行 | — |
| `names` | `array` | 推荐名字列表（含分数、五格、寓意、重名预估） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "bazi": {
            "八字": "丙午癸巳辛未癸巳",
            "四柱": [
                "丙午",
                "癸巳",
                "辛未",
                "癸巳"
            ],
            "日主": "金"
        },
        "wu_xing_analysis": {
            "五行分布": {
                "金": 1,
                "木": 0,
                "水": 2,
                "火": 4,
                "土": 1
            },
            "五行缺失": [
                "木"
            ],
            "建议补充": [
                "木"
            ]
        },
        "needed_wuxing": [
            "木"
        ],
        "names": [
            {
                "name": "王梓森",
                "surname": "王",
                "given_name": "梓森",
                "score": 95,
                "wuge": {
                    "天格": 5,
                    "人格": 15,
                    "地格": 23,
                    "外格": 16,
                    "总格": 27
                },
                "wuge_score": 88,
                "wuxing_chars": "木+木",
                "meaning_tags": [
                    "栋梁",
                    "繁盛"
                ],
                "duplicate_rate": {
                    "estimated_count": 320,
                    "level": "较低",
                    "description": "..."
                }
            }
        ]
    },
    "request_id": "abc123"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数缺失或越界（surname/birth_year/month/day/hour/count） |
| `4029` | `—` | 调用过快（QPS 超限） |
| `4030` | `—` | 今日额度用完 |

## 9. 变更日志

- **1.0.0** (2026-05-10)
  - 首次上线，支持 naming / duplicate / bazi 三种 action

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/baby-naming`

Source: `https://apizero.cn/aidocs/baby-naming/raw.md`
Last updated: 2026-05-11T16:16:07+08:00