首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >娱乐工具箱 API 接口文档(数据鱼API)

娱乐工具箱 API 接口文档(数据鱼API)

原创
作者头像
用户12862874
发布于 2026-11-20 21:57:37
发布于 2026-11-20 21:57:37
210
举报

接口简介

「娱乐工具箱」是数据鱼API平台提供的轻量创意生成接口,Base 路径 /api/entertainment-suite,共 3 个端点,当前包含两项能力:幻想风格名称生成与乐理和弦构成计算。名称生成基于前缀与后缀的规则组合产出奇幻风格的虚构人名;和弦构成按十二平均律音级推算指定根音与和弦类型的组成音及音程关系。

名称生成的词库由 7 个前缀(El、Aer、Bel、Dal、Fin、Gal、Had)与 7 个后缀(on、ian、or、us、el、ra、th)组合而成,共 49 种可能结果,每次调用随机输出一个,并在响应中回显传入的种族参数与生成时间。和弦端点覆盖自然音级与升记号共 12 个根音,支持 major(大三和弦)、minor(小三和弦)、dim(减三和弦)、aug(增三和弦)四种类型,返回组成音名与相对根音的音程半音数。

数据鱼API 将两个能力合并为一个套件接口对外提供,端点数量少、响应体量小,适合游戏工具、写作辅助与乐理教学类应用按需嵌入。调用方式上名称生成走 GET,和弦构成仅支持 POST。

端点总览

方法

路径

说明

鉴权

GET

/api/entertainment-suite/ping

健康检查(免鉴权)

免鉴权

GET

/api/entertainment-suite/name

生成幻想风格人名

API Key

POST

/api/entertainment-suite/chord

计算和弦组成音与音程

API Key

通用约定

鉴权使用数据鱼API全站统一 Key,通过 X-API-Key 请求头或 ?api_key= 查询参数携带;缺失返回 4011,无效返回 4013。响应统一为 {code, msg, data} 结构。和弦端点对根音做合法性校验,非法根音返回 4001(Invalid root note)与 HTTP 400;该路径仅支持 POST,使用 GET 会返回 4050(方法不允许),并在响应中带回允许的方法列表。

核心端点详解

生成人名(GET /api/entertainment-suite/name)

随机生成一个奇幻风格虚构人名。

参数

类型

必填

默认

说明

race

string

否

elf

种族标识,仅作回显,不做取值校验

返回字段:name(生成的人名)、race(回显的种族标识)、generated_at(服务器生成时间)。race 为自由文本,接口原样返回,客户端可用它区分精灵、矮人等自定义分类。

代码语言:javascript
复制
GET /api/entertainment-suite/name?race=dwarf

计算和弦(POST /api/entertainment-suite/chord)

按根音与和弦类型推算组成音。

参数

类型

必填

默认

说明

root

string

否

C

根音,十二平均律音名(C、C#、D、D#、E、F、F#、G、G#、A、A#、B),大小写不敏感

type

string

否

major

和弦类型:major / minor / dim / aug

返回字段:root 与 type(回显)、notes(组成音名数组,按根音到三音、五音的顺序)、intervals(相对根音的半音数数组)。例如 root=C、type=major 返回 notes 为 C、E、G,intervals 为 0、4、7。

代码语言:javascript
复制
POST /api/entertainment-suite/chord
Content-Type: application/json

{"root": "A", "type": "minor"}

健康检查(GET /api/entertainment-suite/ping)

免鉴权,返回套件名称与版本号,用于探活与接入自检。

代码语言:javascript
复制
GET /api/entertainment-suite/ping

数据与限制

  • 人名词库共 49 种组合,随机源为服务端随机数,连续调用可能重复。
  • 和弦根音仅支持十二平均律 12 个音名,含升记号写法(C#),不含降记号写法(Db);非法根音返回 4001。
  • 和弦类型仅 4 种三和弦,不含七和弦及以上扩展和弦。
  • 单次响应均为小对象,无分页与批量能力。

典型使用场景

  • 游戏角色创建页为玩家提供「随机起名」按钮。
  • 网络小说写作工具批量生成配角人名备选。
  • 乐理教学应用做和弦构成音的课堂演示与练习校验。

注意事项

  • type 传入四种枚举之外的取值(如 m7)时不会报错,接口静默按 major 的音程返回,响应中的 type 字段仍回显原值;调用方应自行保证取值合法,或校验返回的 intervals 与请求类型是否匹配。
  • root 参数经大小写归一后匹配,但降记号音名(Db、Ab 等)不在支持范围,需改用升记号写法。
  • 人名为随机组合的虚构词,上线的命名类产品应在展示层做敏感词过滤;和弦结果为标准乐理定义,不涉及演奏指法。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 生成人名(GET /api/entertainment-suite/name)
    • 计算和弦(POST /api/entertainment-suite/chord)
    • 健康检查(GET /api/entertainment-suite/ping)
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档