Artist Atlas
ARTIST ATLAS / API

接口文档

从申请 Key 到查询和补充歌手资料，了解如何接入 Artist Atlas。

开始使用

  1. 在首页注册并验证邮箱，然后登录工作台。
  2. 在「我的 API Key」提交应用名称（最多 50 字符）和使用用途（最多 500 字符），等待管理员审核。
  3. 审核通过后在工作台创建 Key，保存仅在创建或重置时显示一次的明文。
  4. 在请求头中携带 Key，开始搜索歌手。

每个用户最多保留 2 个待审核或已通过的申请及已创建的 Key。已拒绝的申请不占名额，禁用 Key 不释放名额。待审核或已拒绝的申请可自行删除。

邮箱验证码有效期为 30 分钟；注册密码至少 6 个字符，包含英文字母和数字。审核结果不会自动发送邮件，请在工作台查看。

身份认证与响应

下面的公开接口需要在请求头中携带开发者 Key。请通过 HTTPS 传输，不要将 Key 放在 URL 或公开代码中。重置后旧 Key 立即失效。

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

响应统一包含 code、msg 和 body；成功创建资源通常返回 HTTP 201。以下命令中的 BASE_URL 是部署地址，API_KEY 是你的 Key。

{"code": 200, "msg": "success", "body": {"results": []}}

按名称获取歌手详情

GET /api/v1/artists?name={artist_name}&lang=zh-Hans

name 必填，最长 255 字符，按名称或别名精确匹配；请对参数进行 URL 编码。lang 可选，例如 zh-Hans、zh-Hant、en。

结果位于 body.results 数组。同名歌手分别返回，不会自动合并；未命中返回空数组，并将查询加入所属用户的待补充列表。

每条详情包含 artist_id、名称、类型、区分说明、外部 ID、所有语言的名称和别名（names）、按代码分组的属性（attributes）、图片及来源信息。简介优先返回指定语言，缺少时回退英文；未指定时默认英文。其他属性返回指定语言和通用资料（包括未标语言的资料、日期和性别）；未指定语言时返回所有语言。不会自动翻译。

curl -G "$BASE_URL/api/v1/artists" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode 'name=刘德华' --data-urlencode 'lang=zh-Hans'

提交资料

POST /api/v1/submissions

提交均需审核，不会立即发布；source 必填，最多 500 字符。language 可选，使用语言标签格式。非新增歌手的提交需要正整数 artist_id。也可在工作台先搜索、选择歌手后提交，待审核的工作台投稿可以修改或撤回。

curl -X POST "$BASE_URL/api/v1/submissions" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"kind":"name","artist_id":1,"name":"Example","type":"alias","language":"en","source":"Source description"}'

常用 kind 与字段：

  • artist：name、type（person、group、band、other），可选 disambiguation。
  • name：artist_id、name、type（primary、alias、stage、legal、former、translation）。
  • attribute：artist_id、code、value。代码以小写字母开头，只能包含小写字母、数字和下划线，例如 biography。
  • image：artist_id、HTTPS url。只保存 URL，不下载图片；请在来源中说明授权。

纠错使用 name_replace 或 attribute_replace，除正常字段外还需提供原条目的 target_id、expected_version 和 expected_value。若审核时原内容已变化，将返回冲突，投稿仍待审核。同一属性在同一语言下不能重复，通用属性与各语言的同类属性不能重复；出生日期与出生或成立日期、出生地与出生或成立地视为同类。

删除名称或属性使用 name_delete 或 attribute_delete，提交 artist_id、target_id、expected_version、expected_value 和 source。审核通过后生效；每位歌手至少保留一个名称。

成功响应的 body 包含 submission_id 和 status。使用 GET /api/v1/submissions/{id} 查看当前 Key 自己的投稿状态。

限流与错误

每个 Key 每分钟最多 60 次、每天最多 3,000 次；投稿另限每小时 20 次。日额度按 UTC 0 点重置，受分钟限流拦截的请求不计入日额度。超限时返回 HTTP 429，Retry-After 给出等待秒数。

常见状态码：400 参数错误，401 Key 无效或已禁用，404 资源不存在，409 资料发生冲突，429 请求过于频繁。请检查响应中的 msg 并根据状态处理。