Clip (片段)¶

Clip 模型代表视频中的一个片段（通常对应一个镜头/Cut），是搜索结果的基本单位。

获取片段¶

片段可以通过两种方式获取：

# 方式一：通过视频获取所有片段
for clip in video.clips():
    print(clip)

# 方式二：通过搜索获取
for clip in project.search(query="夕焼け"):
    print(clip)

属性¶

属性	类型	说明
`id`	`str`	片段唯一标识
`index`	`int`	片段序号
`start_time`	`float`	起始时间（秒）
`end_time`	`float`	结束时间（秒）
`subtitle`	`str \| None`	字幕/台词内容
`description`	`str \| None`	片段描述
`episode_title`	`str \| None`	集标题
`view_count`	`int`	查看次数
`similarity`	`float \| None`	搜索相似度分数
`ai_tags`	`ClipAITag \| None`	AI 自动生成的标签
`tags`	`ClipTag \| None`	人工确认的标签
`metadata`	`ClipMetadata \| None`	元数据信息
`characters`	`list[Character] \| None`	出现的角色列表
`custom_tags`	`list[ClipCustomTag] \| None`	自定义标签
`thumbnail_url`	`str \| None`	缩略图 URL
`clip_url`	`str \| None`	片段视频 URL
`project_id`	`str \| None`	所属项目 ID
`created_at`	`datetime`	创建时间
`updated_at`	`datetime`	更新时间

方法¶

`fetch_detail() -> None`¶

从 API 获取片段的完整详情信息，更新当前对象的所有属性。当通过搜索获取的片段信息不完整时使用。

clip = next(project.search(query="..."))
clip.fetch_detail()  # 获取完整信息
print(clip.ai_tags)
print(clip.metadata)

注意

fetch_detail() 需要片段对象拥有 client 引用（通过 video.clips() 或内部方法设置）。

`save_thumbnail(path) -> None`¶

下载并保存片段缩略图：

clip.save_thumbnail("output/clip_thumb.jpg")

`save_clip(path) -> None`¶

下载并保存片段视频：

clip.save_clip("output/clip.mp4")

`save_bytes_thumbnail() -> bytes`¶

获取缩略图的字节数据：

thumb_data = clip.save_bytes_thumbnail()

`save_bytes_clip() -> bytes`¶

获取片段视频的字节数据：

clip_data = clip.save_bytes_clip()

AI 标签 (ClipAITag)¶

AI 自动为每个片段生成的标签信息，涵盖画面内容分析的多个维度。

导入路径

ClipAITag、ClipTag、ClipScriptInfo、ClipMetadata、ClipCustomTag 等类型已统一定义在 aimage.search.models.type 中，详见枚举与类型。

ClipTag¶

继承自 ClipAITag，表示经过人工确认的标签，属性与 ClipAITag 完全一致。

ClipMetadata¶

片段的元数据信息，详细字段说明请参阅枚举与类型 - ClipMetadata。

ClipScriptInfo (剧本对齐信息)¶

描述片段与剧本的对齐关系，详细字段说明请参阅枚举与类型 - ClipScriptInfo。

ClipCustomTag¶

自定义标签，详细字段说明请参阅枚举与类型 - ClipCustomTag。

使用示例¶

# 获取片段详情并查看 AI 标签
for clip in video.clips():
    if clip.ai_tags:
        tags = clip.ai_tags
        print(f"Cut #{clip.index}")
        print(f"  角色: {tags.characters}")
        print(f"  景别: {tags.object_size}")
        print(f"  运镜: {tags.camera_work}")
        print(f"  场景: {tags.location}")
        print(f"  情感: {tags.dialog_sentiment}")

    # 查看剧本对齐信息
    if clip.metadata and clip.metadata.script_info:
        info = clip.metadata.script_info
        print(f"  剧本 Cut: {info.cut_ids}")
        print(f"  对齐置信度: {info.confidence}")
        print(f"  对齐类型: {info.relation_type}")
        print(f"  画面: {info.script_screen}")
        print(f"  音频: {info.script_audio}")