UIGF API 文档

[Masterain98]

UIGF API

请求审阅，判断接口是否符合需求

介绍

在接下来的统一可交换祈愿记录标准版本中，我们计划将item_id的优先度提高，成为必填的字段。
这将允许 UIGF 数据集支持国际服的多语言环境，进而将更多的原神工具连接在一起。

但是，一些程序运行于受限的环境中，在将祈愿获取物品名称转化为物品 ID 的过程中有困难。所以 UIGF-Org 提供了一个用于翻译物品文本的 API，供需要该资源的任何开源程序使用。

本 API 已开源于 UIGF-org/UIGF-API，采用 Dimbreath/GenshinData 作为数据源。

使用

UIGF API 有三个常用接口，示例如下
对于所有lang参数，目前可接受的语言参数包括：

• 推荐值：
  • zh-cn, zh-tw, de-de, en-us, es-es, fr-fr, id-id, ja-jp, ko-kr, pt-pt, ru-ru, th-th, vi-vn
• 兼容值：
  • chs, cht, de, en, es, fr, id, jp, kr,pt, ru, th, vi
• 在会返回语言值的接口中，会以推荐值为返回标准

翻译接口

• 接口 URL
  • https://api.uigf.org/translate/{lang}/{text}
• lang 参数：
  • 需要翻译的文本的原始语言
• text 参数：
  • 需要翻译的文本（单条数据查询时）
    • 比如：神里绫华
  • 或者一个包含翻译文本的列表（多条数据查询时）
    • 由方括号包裹字串符，以英文半角逗号间隔，不需要包含空格和引号
    • 比如：[神里绫华,神里绫人]
• 返回格式：
  • 当请求单个文本翻译
    • 成功时，将返回一个Json，item_id键的值即为对应物品 ID
    • 失败时，将返回 HTTP 404 NOT FOUND 错误
  • 当请求多个文本翻译
    • 成功时，将返回一个Json，item_id的值为一个整数值列表，列表中每一个 ID 对应请求的物品文本
      • 当列表中有文本不存在于数据库中，则会为该记录返回值为0的 ID
      • 使用该方法请求 API 时需要检验请求的列表长度是否等于返回的列表的长度
    • 失败时，将返回 HTTP 404 NOT FOUND 错误

::: tabs
@tab 单条查询

https://api.uigf.org/translate/chs/神里绫华

@tab 单条查询结果

{
  "item_id": 10000002
}

@tab 多条查询

https://api.uigf.org/translate/chs/[神里绫华,神里绫人,一个不存在的角色,神里绫人]

@tab 多条查询结果

{
  "item_id": [
    10000002,
    10000066,
    0,
    10000066
  ]
}

:::

语言判断接口

该接口用于当无法判断原始文本语言时使用，不应该依赖其作为物品文本和物品 ID 之间的批量转换

• 接口 URL
  • https://api.uigf.org/generic-translate/{text}
• text 参数
  • 单个需要翻译的文本
    • 比如：神里绫华
• 返回格式
  • 成功时，将返回一个Json
    • item_id键的值即为对应物品 ID
    • lang键的值为一个列表，其包含找到的对应语言。通常情况，该列表仅会有一个语言代码。但在少数情况下，一个文本可能在多个语言下代表同一个物品。
      这种情况下，列表中会有多个语言代码。
  • 失败时，将返回 HTTP 404 NOT FOUND 错误

::: tabs
@tab 样例

https://api.uigf.org/generic-translate/神里绫华

@tab 返回值

{
  "item_id": 10000002,
  "lang": [
    "chs"
  ]
}

:::

字典下载接口

对于有能力在服务端或用户端进行物品文本和物品 ID 转换的工具，我们推荐减少对 UIGF 在线翻译 API 的依赖。

你可以通过字典下载接口获取到各个语言的物品文本和物品 ID 转换关系的 Json 文件

• 接口 URL
  • https://api.uigf.org/dict/{lang}.json
• lang 参数
  • 语言代码
  • 也可以使用all以获取包含全部语言的字典
• 返回格式
  • Json 文件的下载

::: tabs
@tab 样例

https://api.uigf.org/dict/jp.json

@tab 返回值

{
  "無鋒の剣": 11101,
  "銀の剣": 11201,
  "冷刃": 11301,
  "黎明の神剣": 11302,
  "旅道の剣": 11303,
  "...":"...",
  "重雲（テスト）": 11000042,
  "お試しキャラ": 11000043,
  "七七（テスト）": 11000044
}

[Lightczx]

@biuuu @sunfkny

[sunfkny]

一个问题，如果 Dimbreath/GenshinData 数据源没了或者翻译失败了怎么办

[sunfkny]

另外一个问题, https://api.uigf.org/generic-translate/一个不存在的角色 接口应该404，实际是500

[Masterain98]

另外一个问题, https://api.uigf.org/generic-translate/一个不存在的角色 接口应该404，实际是500

已修复 5d965dc

[biuuu]

建议整个包含所有语言的 JSON 文件下载。

[Masterain98]

建议整个包含所有语言的 JSON 文件下载。

877567c 现在使用 https://api.uigf.org/dict/all.json 可下载全语言的 JSON

[biuuu]

100	新手祈愿
200	常驻祈愿
301	角色活动祈愿
400	角色活动祈愿-2
302	武器活动祈愿

可能还需要这些 gacha type 的翻译。
实时翻译应该是不必要的，这些毕竟是固定的，但可以整理个表供参考。

[sunfkny]

可以参考 抽卡页面 bundle_xxxxxx.js 中的 itemTypeNameMap，还有一个 itemTypeMap 不包括 400

[MoRanYue]

400没有用呀，抽卡记录的角色池1和2是一起记录的呀。返回数据list是空的。

[Lightczx]

400没有用呀，抽卡记录的角色池1和2是一起记录的呀。返回数据list是空的。

400用于标识2池物品，查询时使用302

[Lightczx]

@TremblingMoeNew 有想法么

[TremblingMoeNew]

语言参数建议还是和祈愿项的lang一致，即ISO 639-1两位语言代码+ISO 3166-1两位国家或地区代码
理了一下

语言	参数
简中	zh-cn
繁中	zh-tw
英语	en-us
韩语	ko-kr
日语	ja-jp
西班牙语	es-es
法语	fr-fr
俄语	ru-ru
泰语	th-th
越南语	vi-vn
德语	de-de
印尼语	id-id
葡萄牙语	pt-pt

[TremblingMoeNew]

和祈愿项不一致的语言代码会造成需要额外的映射关系维护，没必要，改现在还没正式敲定的API更省事
@Lightczx @Masterain98 @biuuu @sunfkny

[TremblingMoeNew]

@Masterain98 all.json寄了

[Masterain98]

407ab98
增加了支持。但原有的语言参数仍然保留，主要是因为连字符 -不适宜作为 MySQL 的列表名。

[Masterain98]

@Masterain98 all.json寄了

fixed 75f6ff8

[TremblingMoeNew]

item_type的”角色“、”武器“，以及uigf_gacha_type的”角色活动祈愿和角色活动祈愿-2“（虽然这个不会出现在原始数据表/JSON里）也需要提供翻译文本
还有”原始数据“这个表名也需要确定是中英两个就够了还是上面13个语言每个语言整一个

[TremblingMoeNew]

这个item_id虽然值还是官方的，但这是一个官方API中的已弃用字段，现在是对其进行重新填充。应当和uigf_gacha_type一样特殊标注为注入字段

[Lightczx]

也不能说是弃用吧，官方故意不给显示罢了

[Lightczx]

如果填充了item_id, name字段就不需要填充了

[TremblingMoeNew]

如果填充了item_id, name字段就不需要填充了

还是填上吧，向下兼容，删它也没啥必要（

[Lightczx]

@Scighost

[Scighost]

最近在摸鱼，暂时不打算跟进新规范。

[monsterxcn]

接口只作翻译用吗？是否允许加点别的接口，比如返回全部卡池之类的？

我在米游社翻了翻似乎只从 活动祈愿历史记录 看见了一个最新角色卡池的接口：

https://api-takumi.mihoyo.com/common/blackboard/ys_obc/v1/gacha_pool?app_sn=ys_obc

这里面五星的名字好处理，四星就有些麻烦了。页面上其他的卡池信息似乎也只是被当成了普通帖子的内容，以传统艺能的 html-in-json 形式返回了。

如果做 UP 抽数期望分析之类的就需要自行维护卡池信息，感觉有些笨拙了，不知道 UIGF API 能否代劳呢 💕🤣

[Lightczx]

卡池信息可以看看 https://github.com/DGP-Studio/Snap.Metadata/blob/main/Output/GachaEvent.json

[sysescool]

API: https://api.uigf.org/dict/[LANGUAGE].json

For applications have ability converting item text and item IDs on the server or client side, we recommend reducing reliance on the UIGF Online Translation API.
对于有能力在服务端或用户端进行物品文本和物品 ID 转换的工具，我们推荐减少对 UIGF 在线翻译 API 的依赖。

It is necessary to add an api to confirm whether the json file is up to date.
Otherwise, you have to download it every time in order to confirm the json file is latest.

很有必要有一个新的 API 来确保 json 文件的实时性, 否则, 为了使用最新的 json 文件每次都要从新下载.

such as: https://api.uigf.org/dict/json-update.json
return:

{
"chs": 2022-01-03,
"cht": 2022-01-03,
"...": ...,
"th": 2022-01-03,
"vi": 2022-01-03
}

or return:

{
  "update": 2022-01-03
}

The client saves the update date to local disk after calling this API and compares the dates to decide if it should be downloaded next time.
客户端在调用此 api 后将更新日期保存到本地磁盘，
并比较日期决定下次是否下载。

[Masterain98]

会在下一次更新中包含

[Lightczx]

文件的Checksum更好用吧

[sysescool]

yes, checksum is ok.

[Masterain98]

UIGF-org/UIGF-API@c5bfb50