Character（角色）

Character 是作品内角色实体。

Character 与 Project、Group 的连接由 CharacterProject 与 CharacterGroup 关系资源表达。

模型定义

主属性

主属性描述 Character 自身。Core API 只返回数据库字段，不返回视觉图或其他媒体对象。

Field	Type	supported	Description
id	string	✓	由 key 生成的稳定公开 ID；客户端应视为 opaque。
key	string	✓	全局唯一稳定 key，用于过滤和跨域引用。
name	string	✓	规范名称。
imageColor	string	✓	角色印象色，使用 #RRGGBB。
kind	string	✓	角色分类：virtual (二次元角色，可绑定声优) / real (三次元艺人本身)。

HTTP 路由

公开 OpenAPI 规范是路由契约的事实来源。

Method	Path	Description
GET	/api/v1/characters	列出 Characters。
GET	/api/v1/characters/{key}	通过 key 获取单个 Character。

列表路由支持 cursor 分页：

Query	Type	Description
limit	number	每页数量。默认 100，最大 500。
cursor	opaque string	上一次响应 meta.nextCursor 返回的 opaque cursor。

列表响应包含 meta.limit、meta.cursor、meta.nextCursor 和 meta.hasMore。

Character data payload

{
  "id": "character_takamatsu_tomori",
  "key": "takamatsu_tomori",
  "name": "高松燈",
  "imageColor": "#77BBDD",
  "kind": "virtual"
}

Character 列表响应

{
  "data": [
    {
      "id": "character_takamatsu_tomori",
      "key": "takamatsu_tomori",
      "name": "高松燈",
      "imageColor": "#77BBDD",
      "kind": "virtual"
    }
  ],
  "meta": {
    "limit": 100,
    "cursor": "",
    "nextCursor": "",
    "hasMore": false
  }
}