---
title: "角色搜索"
method: POST
path: "/v0/search/characters"
tags: ["角色"]
---

# 角色搜索

`POST /v0/search/characters`

## Request

- The document declares no server URL.
- Auth: none declared

## 实验性 API， 本 schema 和实际的 API 行为都可能随时发生改动

目前支持的筛选条件包括:
- `nsfw`: 使用 `include` 包含NSFW搜索结果。默认排除搜索NSFW条目。无权限情况下忽略此选项，不会返回NSFW条目。

## Query parameters

- `limit` integer
- `offset` integer

## Request body

- object
  - `keyword` string, required
  - `filter` object: 不同条件之间是 `且` 的关系
    - `nsfw` boolean: 无权限的用户会直接忽略此字段，不会返回 R18 角色。 默认或者 `null` 会返回包含 R18 的所有搜索结果。 `true` 只会返回 R18 角色。 `false` 只会返回非 R18 角色。

## Response `200`

返回搜索结果

- PagedCharacter
  - `total` integer
  - `limit` integer
  - `offset` integer
  - `data` Character[]
    - `id` integer, required
    - `name` string, required
    - `type` 1 | 2 | 3 | 4, required: type of a character 角色，机体，舰船，组织...
    - `images` PersonImages
      - `large` string, required
      - `medium` string, required
      - `small` string, required
      - `grid` string, required
    - `summary` string, required
    - `locked` boolean, required
    - `infobox` object[]: server parsed infobox, a map from key to string or tuple null if server infobox is not valid
    - `gender` string: parsed from wiki, maybe null
    - `blood_type` 1 | 2 | 3 | 4: Blood type of a person. A, B, AB, O
    - `birth_year` integer: parsed from wiki, maybe `null`
    - `birth_mon` integer: parsed from wiki, maybe `null`
    - `birth_day` integer: parsed from wiki, maybe `null`
    - `stat` Stat, required
      - `comments` integer, required
      - `collects` integer, required

## Changes

- **2024-12-08** (v0) `1c001229cd88`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bangumi/apis/bangumi-open-api/changes/v0/search/characters/post.md)

---

[API](https://skmtc.dev/bangumi/apis/bangumi-open-api.md) - [All operations](https://skmtc.dev/bangumi/apis/bangumi-open-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bangumi/apis/bangumi-open-api/revisions/6aafdbda7895?raw)