接入概述

本文档描述的是 月幕Galgame 站点（简称：月幕 或 ymgal）可供开发者接入的 HTTPS API。

部分接口可能需要访问权限，如用户登录、数据修改等，但大部分查询接口 —— 通常来说，这代表着游客在月幕可以阅览的所有数据，在我们的API中是没有权限判定的，您可以自由访问。

月幕的开放接口使用 OAuth2.0 协议认证，包括公共接口，这是为了保证后台设计的同一性而决定的。 调用时，您需要 client_id 与 client_secret 作为客户端凭证，通过允许的认证方式获取到一个 access_token 后，携带此token实行请求。

我们提供了公共的 client_id 与 client_secret 供您使用，它能够满足大部分人的学习、实验、整理、调研等需求。

月幕不能保证各API的可访问性，我们只能保证它在大部分地区，以及境外是可访问的。

月幕不能保证域名的变动可控，它可能会在某次DNS污染后被更换，发生这种情况时，我们会尽可能延续旧域名的可用性，这并不受到保障，不代表您可以直接使用旧域名、或拒绝更新。

文档中所陈列的接口均为稳定状态。

开发者须知

（默认接入方已阅读）

• 月幕的API服务仅适用于非商业用途，请不要将其用于商业项目。
• API访问有速率限制以便控制服务器资源，请避免使用并发、循环等调用方式，对于静态资源需做好缓存。
• 若您申请了专属的 client_id 与 client_secret，请不要将其发布到互联网中（如交流论坛、开源代码），当然，你发布了也行，只是在被坏东西滥用时，走的是您的流量池，这可能会导致您正常的业务受到影响。
• 若您的项目是一个可在互联网访问、查看的项目，您需要在项目的说明区域（如README、关于、页脚等）提到月幕Galgame。
• 在开发出现问题时，可以通过接口调用的返回码，来发现和解决问题，具体请查看全局返回对象。
• 您的服务需要收集用户任何数据的，必须事先获得用户的明确同意，且仅应当收集为运营及功能实现目的而必要的用户数据， 同时应当告知用户相关数据收集的目的、范围及使用方式等，保障用户知情权。
• 您收集用户的数据后，必须采取必要的保护措施，防止用户数据被盗、泄漏等。
• 请勿公开表达或暗示您与月幕之间存在合作关系，或声称月幕对您的认可。

Public client identifier

• client_id: ymgal
• client_secret: luna0327

暂未开启站内申请渠道（懒得写，有需要的话再看），若您想申请专属的 client_id，请通过提出 issue 的方式，言明您的用途与项目主页

当然，访问速率限制总归是有的，无非是多与少、共享与否的区别

若您开发的是服务型、分发型应用，为了避免影响业务，请自行实现一个妥善的请求拒绝策略，您可以在全局返回对象中查看相关错误码

关于

月幕的开放API并未提供所有服务功能。

一般情况下，日常更新迭代的API可能只是因为站长写代码写嗨了才得以实现，不一定会是按照业务线或模块顺序提供，同时，一不小心鸽它大半年也是很正常的一件事，不得不品鉴。

在 issues 内已同意实现的不会鸽，若有相关需求，请在 issues 提出。

总之，别急。

另外，本文档是个单文件HTML，由程序自动构建，其内容由多个 Markdown 文件组成。

若你发现文档错误、显示异常、渲染失败等情况，欢迎前往此文档的 Github 仓库提交 PR 或 issue。

和 IE 相关的不受理，老哥换个浏览器吧。

• 源文档
• 页面构建程序

获取 Access Token

access_token 是月幕开放API的全局唯一接口调用凭据，调用各接口时都需使用 access_token， 开发者需要进行妥善保存。

access_token 的有效期为 1 个小时，通过相同的认证参数在有效期内重复获取时，将获得重复的 access_token。 access_token 有效期未受到完全的保障，所以请 不要使用定时器 实现更新逻辑，而是在 拒绝策略 中实现。

基本概念

月幕的开放API基于 OAuth2.0 认证协议，您或许会需要以下文档对此协议进行深入了解：

• https://www.oauth.com/

• https://datatracker.ietf.org/doc/html/rfc6749

在这里需要指出：就算你完全没接触过 OAuth2.0，也并不影响你对接月幕的开放API，你只要把这个文档看完，照着做就行了。

在月幕的认证、授权流程中，接口返回值不遵循全局返回对象的返回值实现

在月幕的认证、授权流程中，不需要遵循HTTP 请求设置的规范

通过 Token 端点获取 Access Token

端点: GET /oauth/token

重复请求: 返回相同的 access_token

过期时间: 1h

Client Credentials

• 此节说明的示例基于 OAuth2.0 Client Credentials Grant，适用于所有公共接口

• Client Credentials 模式不支持 Refresh Token

Example

curl 'https://www.ymgal.games/oauth/token?grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=public'

Success

{
  "access_token": "2fdace3c-651f-4484-85ac-9a449da43f05",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "public"
}

Failed

{
  "error": "invalid_client",
  "error_description": "Bad client credentials"
}

其他

暂无需求，所以暂未提供。

如果后续提供了 Authorization Code Grant 的实现，也只会是在需要用户权限的接口被发布时。

不同认证模式获取的 access_token 在相同的 scope 之下访问 API 没有任何区别。

Scopes

全局返回对象

月幕的 API Response 有一个固定的格式，具体返回的数据会作为 data 字段嵌套在其中，这适用于没有显示声明特例的所有情况。

后续的接口文档中，所有阐述的返回值均遵循此规则，不会额外说明在外侧包装的全局返回对象。

API Response

在接口调用出现异常、参数检查不通过等无法正确响应时，HTTP Status 也仍然会保持 200， 错误内容在 code msg 等字段中体现。

• 例外情况：认证、授权失败时，对应的 HTTP Status 同步变更为 401、403。

如果接口调用失败，success 字段固定为 false

示例&说明

{
  "success": true, // 本次调用是否成功
  "code": 0, // 详情见 —— 返回码
  "msg": "", // 接口反馈的信息，可能会为 null
  "data": {}// 接口实际返回的数据，可能会为 null
}

一个仅代表调用成功的返回值可能是这样的，没有 data，也没有 msg

{
  "success": true,
  "code": 0
}

Java 模型

@Data
public class R<T> {
    
    private boolean success = false;

    private int code = RCode.SUCCESS.getCode();

    private String msg;

    private T data;

    public R(int code, String msg, T data) {
        this.code = code;
        this.msg = msg;
        this.data = data;

        this.success = RCode.SUCCESS.valueIs(code);
    }
}

Kotlin 模型

data class R<T>(
    var code: Int = RCode.SUCCESS.code,
    var data: T? = null,
    var message: String? = null
) {

    var success: Boolean = true

    init {
        success = this.code == RCode.SUCCESS.code
    }
}

TS 模型

declare interface R<T = any> {
    success: boolean;
    code: RCode;
    msg?: string;
    data?: T;
}

Page

如果您请求的是一个分页接口，那么默认返回值的 data 格式如下所示

请求的列表会作为数组保存在 result 字段中

{
  "result": [], // 响应的列表
  "total": 0, // 可供查询的总数
  "hasNext": false, // 是否有下一页
  "pageNum": 1, // 当前页
  "pageSize": 10 // 页大小
}

我们访问一个分页接口，得到的最终 HTTP Response Body 完整形态会长成这样

{
  "success": true,
  "code": 0,
  "data": {
    "result": [
      {
        "name": "月に寄りそう乙女の作法",
        "chineseName": "近月少女的礼仪"
      },
      {
        "name": "月に寄りそう乙女の作法２",
        "chineseName": "近月少女的礼仪2"
      }
    ],
    "total": 2,
    "hasNext": false,
    "pageNum": 1,
    "pageSize": 10
  }
}

全局返回码

返回码是全局返回对象中的 code 字段，标识了这个响应的状态

当 code === 0 时，返回对象中的 success 字段恒定为 true

Java 模型

public enum RCode {
    SUCCESS(0),//成功
    OTHER(7),//其他
    TIME_OUT(30),//超时
    SYSTEM_ERROR(50),//系统内部错误
    ILLEGAL_VERSION(51),//非法版本
    UNAUTHORIZED(401),//未经认证
    FORBIDDEN(403), //  未经授权
    NOT_FOUNT(404), //  找不到
    TOO_MANY_REQUEST(429), //请求过多
    ILLEGAL_PARAM(614);//非法参数

    private int code;

    RCode(int code) {
        this.code = code;
    }
    
    public int getCode() {
        return code;
    }
}

Kotlin 模型

enum class RCode(val code: Int, val defaultMessage: String) {
    SUCCESS(0, ""),
    OTHER(7, "未知错误"),
    TIME_OUT(30, "超时"),
    SYSTEM_ERROR(50, "系统内部错误"),
    ILLEGAL_VERSION(51, "非法版本"),
    INITIALIZATION_FAILED(52, "初始化失败"),
    UNAUTHORIZED(401, "未经认证"),
    FORBIDDEN(403, "未经授权"),
    NOT_FOUND(404, "找不到"),
    TOO_MANY_REQUEST(429, "请求过多"),
    ILLEGAL_PARAM(614, "非法参数");
}

TS模型

declare const enum RCode {
    SUCCESS = 0, // 成功
    OTHER = 7, // 其他
    TIME_OUT = 30, // 超时
    SYSTEM_ERROR = 50, // 系统内部错误
    ILLEGAL_VERSION = 51, // 非法版本
    UNAUTHORIZED = 401, // 未经认证
    FORBIDDEN = 403, //  未经授权
    NOT_FOUNT = 404, //  找不到
    TOO_MANY_REQUEST = 429, //  请求过多
    ILLEGAL_PARAM = 614// 非法参数
}

注意事项

• 出于对某些开发语言、环境的礼貌，以及敬畏，月幕的所有接口中，若出现数字精度大于 2^53 的情况（比如有些模型是通过 SnowFlake 算法生成的 ID），接口中返回的所有 数字长整型（int64） 都会转变为 字符串， 这可能会使您感到疑惑，实际是正常的，一般情况下您不需要为此付出额外的心智负担， 各语言主流的 JSON 处理库不会因此出现异常。

HTTP 请求设置

域名：https://www.ymgal.games

API 端点均基于该域名实行请求。

在请求月幕的开放 API 时，需要遵守相关的规定才能成功访问。

简单的来说，你只需要在 Request Header 中设置几个字段即可。

Accept

我们默认所有的接口均使用 JSON 格式返回。

请在你的请求头中设置：

Accept: application/json;charset=utf-8

Authorization

我们默认所有的接口调用均需要 access_token

请在你的请求头中设置：

Authorization: Bearer access_token

如:

Authorization: Bearer 2fdace3c-651f-4484-85ac-9a449da43f05

version

我们默认所有的接口调用均需要指定 version ，接口文档中会声明接口版本

请在你的请求头中设置 （版本为1的情况）：

version: 1

⭐ 档案业务API

档案业务模型

业务对象建模，在 Archive 模块中有 4 种平级的档案模型，他们互相之间通过某些形式约定了多对多的关系

• Game，游戏
• Organization，机构
• Character，角色
• Person，真实人物

其中, 游戏档案 (Game) 包含以下实体关系， 一对多

characters - CharacterRelation[]
staff  -  Staff[]
releases  -  Release[]

并且通过以下字段和其他的模型产生关联， 多对多

developerId -  Organization
staff  -  Staff#pid  -  Person
characters - CharacterRelation#cid -  Character
characters - CharacterRelation#cvid - Person

游戏之外的几种模型都比较简单，查看对应小节的字段解释与 JSON 样例即可

Archive

首先请先看一下这个抽象的档案模型，本模型定义了月幕中档案的公用基本参数

Game、Organization、Character、Person 均属于该模型的一种具体实现

虽然在后端的设计中它们之间并不是一个直接的继承或组合关系，但是在 API 对接时，你可以理解为上述四种档案模型均是继承自 Archive 的子类，这与请求、响应的现状是相符的

ExtensionName、MoreEntry 均属于单纯为了承载信息的内容字段，并不与任何档案之间具备任何关联关系，在本章节最后面统一列出详细信息

ArchiveStateEnum

ArchiveStateEnum 是一个枚举，标识了这个档案处于什么状态，不同的状态可能需要不同的访问权限才可以查看。

共三种类型：

• FREEZE
• PROTECTED_PUBLISHED
• PUBLIC_PUBLISHED

绝大部分接口中接入者都不需要关心这个东西

Game

游戏档案，JSON示例请查看最后一节

Website 属于单纯为了承载信息的内容字段，在本章节最后面统一列出详细信息

CharacterRelation

Release

Staff

游戏制作人员

Organization

组织机构，可能是发行商、开发商、工作室等等等等

Character

角色档案

GenderEnum

这个枚举也会在人那里用到，虽然真实人物没有扶她 = =

Java

public enum GenderEnum {

    UNKNOWN(0, "未知"),
    MAN(1, "男"),
    WOMAN(2, "女"),
    // ふたなり
    FUTANARI(3, "扶她");

    private int code;
    private String desc;

    GenderEnum(int code, String desc) {
        this.code = code;
        this.desc = desc;
    }
}

TypeScript

export enum Gender {
    UNKNOWN = 0, //"未知"
    MAN = 1, //男
    WOMAN = 2,//女
    // ふたなり
    FUTANARI = 3,//扶她
}

Person

现实人类个体

需要注意的是 Person 档案的 name 并不一定就是那个人的真名。 自称、约定速成的名字 都可能存在

内容字段建模

ExtensionName

拓展名称字段

MoreEntry

额外键值对， 补充说明用

有的编辑老哥会额外加些东西，比如：

• 18X补丁发布时间：xxx
• 特殊码：xxx
• 发售价格：xxx
• 等等……

Website

和档案相关的网站

JSON Example (Game)

{
      "publishVersion": 0,
      "publishTime": "2021-08-07 00:00:00",
      "name": "月に寄りそう乙女の作法",
      "chineseName": "近月少女的礼仪",
      "extensionName": [
        {
          "name": "つり乙",
          "type": "",
          "desc": ""
        },
        {
          "name": "Tsuriotsu",
          "type": "",
          "desc": ""
        }
      ],
      "introduction": "主人公大藏游星，作为代表了日本财界的“华丽一族”的大藏家的末端......",
      "state": "PUBLIC_PUBLISHED",
      "weights": 0,
      "mainImg": "http://store.dev-ymgal.com/archive/main/3d/3d99dc3f2888479f98eadb3501c50713.webp",
      "moreEntry": [],
      "gid": 31147,
      "developerId": 10041,
      "haveChinese": true,
      "typeDesc": "",
      "releaseDate": "2012-10-26",
      "restricted": true,
      "country": "",
      "website": [
        {
          "title": "官中网站",
          "link": "https://hikarifield.co.jp/tsukiniyorisou/"
        }
      ],
      "characters": [
        {
          "cid": 19365,
          "cvId": 11333,
          "characterPosition": 1
        },
        {
          "cid": 19366,
          "cvId": 10954,
          "characterPosition": 2
        }
      ],
      "releases": [
        {
          "id": 110064,
          "releaseName": "近月少女的礼仪",
          "relatedLink": "https://hikarifield.co.jp/tsukiniyorisou/",
          "platform": "Windows",
          "releaseLanguage": "Chinese",
          "restrictionLevel": "全年龄"
        },
        {
          "id": 110065,
          "releaseName": "A moon a sun and three macaroons",
          "relatedLink": "https://drive.google.com/file/d/1vTyy7AY0MG6RWJmi-qLsgPERjmm44WiG/view?usp=sharing",
          "platform": "Windows",
          "releaseDate": "2021-07-05",
          "releaseLanguage": "English",
          "restrictionLevel": "未分级"
        }
      ],
      "staff": [
        {
          "sid": 126376,
          "pid": 11083,
          "empName": "鈴平 ひろ",
          "empDesc": "",
          "jobName": "原画"
        },
        {
          "sid": 126377,
          "pid": 11236,
          "empName": "西又 葵",
          "empDesc": "",
          "jobName": "原画"
        }
      ],
      "type": "GAME",
      "freeze": false
    }

搜索游戏-精确

精确搜索游戏，直接返回对应目标 详情

具体的来说，此接口要求传入一个尽可能符合游戏名（或游戏中文名）的关键字以供查询

对于单个档案而言，将同时判定原名与中文名，取高值

本接口命中到复数档案时，返回名称相似度最高的数据

keyword 匹配根据 Trigram 算法实现

此接口并不能保证匹配精确性，只能说，它在满足以下条件时，是可靠的

• 入参 keyword 是游戏的全名，如：月に寄りそう乙女の作法、近月少女的礼仪
• 游戏的全名所对应的游戏档案只有 1 个

如果你的入参 keyword 是游戏别名、简称、外号等，大概率你是查不到的，除非它正好和某个游戏名的匹配度较高

Resource Path

GET /open/archive/search-game

version: 1

Request Parameter

Request Body

无

Response Body

{
    "game": {},
    "cidMapping": {
        "19366": {
            "cid": 19366,
            "name": "桜小路 ルナ", // 此档案名称，原名
            "mainImg": "",  // 一个完整的图片路径
            "state": "PUBLIC_PUBLISHED",  // 此档案状态
            "freeze": false   // 是否属于一个被冻结的档案
        }
    },
    "pidMapping": {
        "10018": {
            "pid": 10018,
            "name": "橋本 みゆき",
            "mainImg": "",
            "state": "PUBLIC_PUBLISHED",
            "freeze": false
        }
    }
}

说明：

• game 字段数据和 档案业务模型 中定义的 Game 模型一致，内部嵌套了 character、staff 等关联关系
• cidMapping 是一个映射表(cid -> data)，返回此游戏涉及到的所有 character 基础信息
• pidMapping 是一个映射表(pid -> data)，返回此游戏涉及到的所有 person 基础信息

找不到的 Response body（完整）

{
  "success": false,
  "code": 614,
  "msg": "根据关键字找不到对应档案"
}

搜索游戏列表

同月幕Galgame主站搜索功能。

传入查询 keyword 时，此接口会根据以下要素命中数据：

• 中文名与原名的完全匹配
• 与中文名或原名相似度 > 0.5
• keyword 分词后，根据倒排索引命中的文本向量，按权重大小直出

以上优先度依次递减。

同时此接口支持别名、外号、圈内称呼等查询。

比如：罚抄

可以命中：Rewrite（改写）

当然，能查 != 查的对，查询不等式秒了。

Resource Path

GET /open/archive/search-game

version: 1

Request Parameter

Request Body

无

Response Body

此接口返回一个 Page，下方示例仅为 Page 中列表的单条数据

字段说明请与档案API章节的档案模型对照，这里并没有需要额外注意的参数。

{
  "orgId": 0,
  "orgName": "",
  "releaseDate": "2024-05-10",
  "haveChinese": false,
  "id": 0,
  "name": "",
  "chineseName": "",
  "state": "FREEZE",
  "weights": 0,
  "mainImg": "",
  "publishVersion": 0,
  "publishTime": "2024-05-10 16:15:16",
  "publisher": 0,
  "score": ""
}

查询游戏详情

通过 gid 查询单个游戏的详情

和搜索游戏-精确这个接口的返回值一模一样

除非你是瞎几把传的 gid， 否则不会出现 NOT FOUND 的错误

https://www.ymgal.games/GA31147

GA31147 === Game archive with id 31147

Resource Path

GET /open/archive

version: 1

Request Parameter

Request Body

无

Response Body

{
    "game": {},
    "cidMapping": {
        "19366": {
            "cid": 19366,
            "name": "桜小路 ルナ", // 此档案名称，原名
            "mainImg": "",  // 一个完整的图片路径
            "state": "PUBLIC_PUBLISHED",  // 此档案状态
            "freeze": false   // 是否属于一个被冻结的档案
        }
    },
    "pidMapping": {
        "10018": {
            "pid": 10018,
            "name": "橋本 みゆき",
            "mainImg": "",
            "state": "PUBLIC_PUBLISHED",
            "freeze": false
        }
    }
}

说明：

• game 字段数据和 档案业务模型 中定义的 Game 模型一致，内部嵌套了 character、staff 等关联关系
• cidMapping 是一个映射表(cid -> data)，返回此游戏涉及到的所有 character 基础信息
• pidMapping 是一个映射表(pid -> data)，返回此游戏涉及到的所有 person 基础信息

查询机构下的游戏

指定机构

返回所有该机构下的游戏，没有则为空数组

Resource Path

GET /open/archive/game

version: 1

Request Parameter

Request Body

无

Response Body

[
  {
    "gid": 0,
    "developerId": 0,
    "name": "",
    "chineseName": "",
    "haveChinese": false,
    "mainImg": "",
    "releaseDate": "2024-05-13",
    "state": "FREEZE"
  }
]

查询日期区间内发行的游戏

传入一个日期区间，查询出发行时间在该区间内的游戏

一般可用作查询 本月新作、上月新作 等

Resource Path

GET /open/archive/game

version: 1

Request Parameter

1. 开始时间不能在结束时间之后
2. 区间内的天数不能超过 50
3. 开始时间必须在 1980 年之后
4. 开始时间不能超过当前五年，假设今年是2020年，则 releaseStartDate 不能是 2026-01-01

Request Body

无

Response Body

正确返回的话内容不会为 null，如指定区间内不存在发行游戏则返回空数组

[
  {
    "restricted": false,
    "orgName": "",
    "gid": 0,
    "developerId": 0,
    "name": "",
    "chineseName": "",
    "haveChinese": false,
    "mainImg": "",
    "releaseDate": "2024-05-13",
    "state": "FREEZE"
  }
]

随机游戏

随机出一个游戏列表，可指定数量

经过默认的筛选，不会返回一些特别小众的、未经过修订的游戏

Resource Path

GET /open/archive/random-game

version: 1

Request Parameter

Request Body

无

Response Body

本接口必定能返回符合期望的数据条数

[
  {
    "gid": 0,
    "developerId": 0,
    "name": "",
    "chineseName": "",
    "haveChinese": false,
    "mainImg": "",
    "releaseDate": "2024-05-13",
    "state": "FREEZE"
  }
]

Change list

2024-05-15

经过观察，较稳定，正式发布

• API：查询机构下的游戏
• API：查询日期区间内发行的游戏
• API：随机游戏

2024-05-11

预发布，稳定性及易用性待考察

• OAuth2.0 认证接口已测试
• API：搜索游戏-精确
• API：搜索游戏列表
• API：查询游戏详情
• HTML 生成稳定