Character (角色)¶

Character 模型代表项目中的一个角色。

获取角色¶

for character in project.characters():
    print(f"{character.name} ({character.name_en})")

属性¶

属性	类型	说明
`id`	`str`	角色唯一标识
`name`	`str`	角色名称（日文）
`name_en`	`str \| None`	角色英文名
`name_alias`	`list[str] \| None`	名称别名列表
`description`	`str`	角色描述
`features`	`list[str]`	角色特征列表
`character_index`	`int`	角色序号
`is_protagonist`	`bool`	是否为主角
`image_url`	`str \| None`	角色形象图 URL
`image_path`	`str \| None`	角色图片路径
`reference_images`	`list[str] \| None`	参考图片路径列表
`reference_image_urls`	`list[str] \| None`	参考图片 URL 列表
`ai_classification_status`	`AIClassificationStatus \| None`	AI 分类状态
`project_id`	`str \| None`	所属项目 ID
`related_infos`	`list[CharacterRelatedInfo]`	相关信息
`video_characters`	`list[VideoCharacter] \| None`	出现的视频关联信息
`created_at`	`datetime`	创建时间
`updated_at`	`datetime`	更新时间

方法¶

`save_image(path) -> None`¶

下载并保存角色形象图：

character.save_image("output/character.jpg")

`save_bytes_image() -> bytes`¶

获取角色形象图的字节数据：

data = character.save_bytes_image()

`save_reference_images(folder) -> None`¶

将角色的所有参考图片下载到指定文件夹：

character.save_reference_images("output/references/")
# 文件将保存为: 角色名_0.jpg, 角色名_1.jpg, ...

`save_bytes_reference_images() -> list[bytes]`¶

获取所有参考图片的字节数据列表：

images_data = character.save_bytes_reference_images()
for i, data in enumerate(images_data):
    print(f"参考图 {i}: {len(data)} bytes")

辅助模型¶

导入路径

CharacterRelatedInfo、VideoCharacter 已统一定义在 aimage.search.models.type 中，详见枚举与类型。

CharacterRelatedInfo¶

角色相关信息。

属性	类型	说明
`id`	`str`	信息 ID
`message`	`str`	信息内容
`subject`	`str \| None`	主题
`updated_at`	`str`	更新时间

VideoCharacter¶

角色与视频的关联关系。

属性	类型	说明
`video_id`	`str`	视频 ID
`character_id`	`str`	角色 ID

在搜索中使用角色¶

角色对象可直接用于搜索过滤：

characters = list(project.characters())

# 使用 Character 对象过滤
protagonist = next(c for c in characters if c.is_protagonist)
results = project.search(
    query="打斗",
    include_characters=[protagonist],
)

# 也可以直接使用名称字符串
results = project.search(
    query="打斗",
    include_characters=["太郎"],
)

使用示例¶

# 列出所有角色信息
for char in project.characters():
    role = "主角" if char.is_protagonist else "配角"
    print(f"[{role}] {char.name}")
    if char.name_en:
        print(f"  英文名: {char.name_en}")
    if char.name_alias:
        print(f"  别名: {', '.join(char.name_alias)}")
    print(f"  特征: {', '.join(char.features)}")
    print(f"  描述: {char.description}")

    # 下载角色图片
    if char.image_url:
        char.save_image(f"output/{char.name}.jpg")

    # 下载参考图
    if char.reference_image_urls:
        char.save_reference_images("output/references/")