Fun API

前言

这是一个用于娱乐的API工具，来猜测提供的姓名的性别，自建的，参考项目：observerss:NGender
使用该接口请在贵网站或项目标注“仅供娱乐”
当然，如果你的agent有call web的能力，可以用的

如果你要看的是自部署文档，请前往自部署Fun API

开始使用

接口URL

https://fun.serveryyswys.top

猜测性别

GET /api/v1/genderguess

请求参数(Query)

参数名	类型	必填	默认值	说明
`name`	string	是	无	用于猜测性别的姓名，支持纯中文字符（默认长度 2-4 个字符）
`method`	integer	否	`0`	API 模式： `0` 正常（原始算法） `1` 反转性别（对概率取反并） `2` 反向性别（交换男女得分） `3` 随机模式（随机返回性别和概率 0.5-1）
`nolimit`	string	否	`false`	是否取消姓名字数限制。支持值：`1`、`on`、`true`（不区分大小写）。启用后姓名可为任意长度的纯中文字符。
`mapping`	string (JSON)	否	无	自定义姓名映射表，JSON 字符串格式。优先级高于算法。支持两种格式： • 对象格式：`{"张三":{"gender":"male","min":0.8,"max":0.95}}` • 索引数组格式：`{"李四":["female",0.9,1]}` 概率范围必须 `0.5 ≤ min ≤ max ≤ 1`。
`debug`	integer	否	`0`	是否返回调试信息。`1` 开启，`0` 关闭。开启后返回字段 `debug_info`，包含请求参数、映射表解析过程、随机数生成值、概率计算中间结果等（不包含随机到的趣味文案）。

返回示例

常规查询

例如，只传入一个name参数，你需要构建：

随后会返回：

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "name": "张三",
        "gender": "male",
        "gender_cn": "男",
        "probability": 0.79134,
        "fun_tip": "<随机提示文案>",
        "nolimit_used": false,
        "mode": 0,
        "ismodified": false
    }
}

这是最基本的查询方式，通过GET实现

API模式

API提供了四种可用的模式：常规、反转、反向和随机：

正常模式就是不改变算法

反转模式是将概率取反，也就是1-原概率

反向模式为交换男女得分

随机模式为分两次抽取，一次抽取性别，一次抽取概率

正常模式和常规查询的返回结果相同，这里不展示

要使用反转模式，你需要构建：

随后会返回：

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "name": "张三",
        "gender": "female",
        "gender_cn": "女",
        "probability": 0.20866,
        "fun_tip": "<随机提示文案>",
        "nolimit_used": false,
        "mode": 1,
        "ismodified": false
    }
}

此时你会发现，“mode”字段变为了“1”，代表模式生效

其次是反转模式，你需要构建：

随后会返回：

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "name": "张三",
        "gender": "female",
        "gender_cn": "女",
        "probability": 0.79134,
        "fun_tip": "<随机提示文案>",
        "nolimit_used": false,
        "mode": 2,
        "ismodified": false
    }
}

你会发现，原本男性概率为“0.79134”，现在变为了女性

最后是随机模式，要使用，你需要构建：

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "name": "张三",
        "gender": "male",
        "gender_cn": "男",
        "probability": 0.741462,
        "fun_tip": "<随机提示文案>",
        "nolimit_used": false,
        "mode": 3,
        "ismodified": false
    }
}

如果你再次发送GET请求，结果会变化：

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "name": "张三",
        "gender": "female",
        "gender_cn": "女",
        "probability": 0.988106,
        "fun_tip": "<随机提示文案>",
        "nolimit_used": false,
        "mode": 3,
        "ismodified": false
    }
}

取消字数限制

取消字数限制是第一版ngender-php-api就有的功能，要使用，你需要构建：

会返回：

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "name": "张三李四王五",
        "gender": "male",
        "gender_cn": "男",
        "probability": 0.941328,
        "fun_tip": "<随机提示文案>",
        "nolimit_used": true,
        "mode": 0,
        "ismodified": false
    }
}

如果你没加上nolimit参数，会返回：

{
    "code": 400,
    "msg": "姓名必须是2-4个纯中文字符",
    "data": []
}

映射表

映射表是一项用于更正类似于“李胜男”这种误判，也可以用于其他场景

要使用，你需要构建：

此时会返回：

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "name": "李胜男",
        "gender": "female",
        "gender_cn": "女",
        "probability": 0.82397,
        "fun_tip": "<随机提示文案>",
        "nolimit_used": false,
        "mode": 0,
        "ismodified": true
    }
}

又因为支持区间随机数，所以若再次发送GET请求，结果又会刷新

debug模式

debug模式是一项调试功能，可用于查看生成过程
要使用，你需要构建：

此时会返回：

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "name": "张三",
        "gender": "male",
        "gender_cn": "男",
        "probability": 0.79134,
        "fun_tip": "<随机提示文案>",
        "nolimit_used": false,
        "mode": 0,
        "ismodified": false,
        "debug_info": {
            "request": {
                "name": "张三",
                "method": 0,
                "mapping": null
            },
            "calc_prob": {
                "male": {
                    "prob_log": -17.08244730529224,
                    "char_logs": [
                        {
                            "char": "张",
                            "count": 3985,
                            "p": 0.00018726024169023867,
                            "logP": -8.583011241787704
                        },
                        {
                            "char": "三",
                            "count": 7445,
                            "p": 0.0003498500625806341,
                            "logP": -7.95800588789391
                        }
                    ]
                },
                "female": {
                    "prob_log": -18.41547029373985,
                    "char_logs": [
                        {
                            "char": "张",
                            "count": 1274,
                            "p": 0.00011810489661603514,
                            "logP": -9.043937374011362
                        },
                        {
                            "char": "三",
                            "count": 2196,
                            "p": 0.00020357798506186276,
                            "logP": -8.49946140751405
                        }
                    ]
                }
            },
            "normal": {
                "pM_log": -17.08244730529224,
                "pF_log": -18.41547029373985,
                "maxP": -17.08244730529224,
                "eM": 1,
                "eF": 0.2636789568347862,
                "pMale": 0.791340232890133,
                "pFemale": 0.208659767109867
            },
            "mode": "normal"
        }
    }
}

你会看到每一步的返回结果
如果你使用了映射表，则会在过程中展示“命中映射表”

多项功能使用

所有功能除映射表外都互不干扰，因此你可以完成以下场景：

长名字+API模式

多模式+debug

等等等等

错误一览

400

{
    "code": 400,
    "msg": "缺少参数name",
    "data": []
}

你没传name字段

{
    "code": 400,
    "msg": "姓名必须是2-4个纯中文字符",
    "data": []
}

你传的不是中文姓名

{
    "code": 400,
    "msg": "姓名必须是2-4个纯中文字符",
    "data": []
}

加上nolimit试试呢？

{
    "code": 400,
    "msg": "mapping参数JSON格式错误: Syntax error",
    "data": []
}

你的json格式错了

玄学错误

1.传了映射表但为："ismodified": false

检查格式是否正确

更新历程：

2026/03/27

增加了映射表（mapping）、调试（debug）的功能和参数，也为网页版适配了功能

为自部署版编写了一份文档

2026/02/06

增加了method（1和2，对应反转性别和反向性别）

编写了本文档

2026/02/03：

第一个版本诞生

当时只是支持最基本的性别猜测功能

前言#

开始使用#

猜测性别#

请求参数(Query)#

返回示例#

常规查询#

API模式#

取消字数限制#

映射表#

debug模式#

多项功能使用#

错误一览#

400#

玄学错误#

更新历程：#

前言

开始使用

猜测性别

请求参数(Query)

返回示例

常规查询

API模式

取消字数限制

映射表

debug模式

多项功能使用

错误一览

400

玄学错误

更新历程：