ClipSeek MCP 接口参考

本页面向开发者和高级 MCP 客户端。日常使用可先阅读连接 Codex或常用工作流。

连接与返回结果

使用设置 → AI Agent 中显示的地址：

http://127.0.0.1:<port>/mcp
Authorization: Bearer <token>

传输方式为 Streamable HTTP。成功的工具数据位于 structuredContent；业务失败标记为 tool error，并包含 { "code", "message" }。身份验证失败会在工具执行前返回 HTTP 401。

多数工具接受可选 libraryId。省略或传 null 时，使用桌面端当前素材库；明确指定 ID 时，访问对应库，但不切换桌面界面。list_libraries 和 get_operation 不接受 libraryId。

标识、单位与结果字段

字段	含义
libraryId	稳定的素材库标识。
assetId	素材库内的数字 ID，由素材摘要返回；可用于将搜索限定为单个素材的帧。
assetUid、frameUid	素材和帧的稳定 UUID。工具要求指定素材时使用 assetUid。
folderId、tagId	仅在当前素材库内有效的整数 ID。
operationId	导入、图片变体或视频片段任务的标识。
importedAt、createdAt、dateFrom、dateTo、expiresAt	Unix 秒时间戳。
timestampMs、durationMs、startMs、endMs	毫秒。
文件大小 / 宽高比	字节 / 宽除以高。

请求和结构化结果使用 camelCase。素材摘要包含文件名、类型、MIME、大小、尺寸、时长、文件夹、标签、预览 URI 和下载可用状态。画面搜索还返回得分、命中帧 UID、时间和帧预览 URI。get_asset 额外提供导入阶段、主色和帧列表。不暴露数据库或源文件路径。

工具总览

搜索和素材读取都排除垃圾箱。开启 Agent 访问即可读取素材、下载原件和生成临时文件；四个整理与导入工具需要额外权限。

工具	用途	必填输入
list_libraries	列出已登记素材库及 isCurrent。	无
get_library_context	获取素材库、文件夹、标签和有效数量。	无
search_assets	搜索画面或按信息筛选。	无
get_asset	获取素材详情和预览引用。	assetUid
get_video_subtitles	读取已导入字幕及时间。	assetUid
search_subtitles	搜索已建立索引的字幕正文。	query
get_operation	获取后台任务状态与结果。	operationId
create_asset_download	获取临时原件下载链接。	assetUid
create_image_variant	生成缩放或裁剪后的图片。	assetUid，至少一个尺寸
create_video_clip	生成 H.264/AAC MP4 片段。	assetUid、startMs、endMs
create_folder	新建逻辑文件夹。需额外权限。	name
update_asset_tags	添加或移除标签。需额外权限。	assetUid
move_assets_to_folder	修改文件夹归属。需额外权限。	assetUids
import_assets	导入本机文件或目录。需额外权限。	paths

搜索素材

非空 semanticQuery 按画面含义搜索；省略时按素材信息查询。filenameContains 在两种模式下都执行不区分大小写的文件名包含匹配。

{
  "semanticQuery": "雨夜中的霓虹街道",
  "filters": { "kinds": ["video"], "minWidth": 1920 },
  "page": 1,
  "pageSize": 20
}

结果包含 items、total、page、pageSize 和 hasMore。page 默认 1；pageSize 默认 20，限制为 1–50。画面搜索按相关度排序，同一视频可能返回多个命中帧。画面搜索需要本机模型，普通信息查询不需要。

全部筛选参数与匹配规则

筛选参数	含义
assetId	限定素材库内的单个数字素材 ID，包括其可搜索帧。
folderId	单个文件夹，优先于 folderIds 和 uncategorized。
folderIds、uncategorized	任一选中文件夹，可同时包含未分类素材。
tags	素材必须拥有列出的全部标签。
kinds	image、video、gif 中任一类型。
colors	任一选中的颜色桶。
minWidth、minHeight	最小像素尺寸。
minAspect、maxAspect	宽高比范围，包含边界。
minSize、maxSize	字节大小范围，包含边界。
dateFrom、dateTo	导入日期范围，Unix 秒，包含边界。
visualIndexed、subtitleIndexed	按相应索引是否已建立筛选；省略表示不限制。
sort	imported_desc（默认）、imported_asc、name_asc、name_desc、size_desc，仅对普通查询生效。

颜色桶：red、orange、yellow、green、cyan、blue、purple、magenta、brown、black、white、gray。

文件夹、类型、颜色各组内部是“满足任一”；不同筛选组叠加。assetId 在画面匹配前就限制搜索范围。不提供垃圾箱或“仅导入失败”查询模式。

读取与搜索字幕

这两个工具使用已经导入 ClipSeek 的字幕，不会转录音频、扫描视频旁的字幕文件，也不会构建搜索索引。准备方法见字幕搜索。

get_video_subtitles：读取字幕轨道

{
  "assetUid": "视频 UUID",
  "page": 1,
  "pageSize": 50
}

可选参数：libraryId、version。page 从 1 开始，默认 1；pageSize 为 1–50，默认 50。不需要字幕搜索索引。

返回 assetUid、字幕信息 subtitle（version、sourceName、encoding、warnings）、台词 cues（startMs、endMs、text）、total、page、pageSize 和 hasMore。

读取后续页时，把首屏的 subtitle.version 原样作为 version 传入。若字幕已替换或移除，subtitle_changed 表示需从第一页重新读取。不要解析或推断版本值的格式。

未导入字幕属于成功的空结果：subtitle: null、cues: []、total: 0。超出末页也返回空台词。非视频输入返回 invalid_argument；素材不存在或已在垃圾箱时返回 asset_not_found。

search_subtitles：查找台词

{
  "query": "欢迎回家",
  "mode": "phrase",
  "porter": false,
  "filters": { "tags": ["selected"] },
  "pageSize": 20
}

参数	规则
libraryId	可选目标素材库。
assetUid	可选视频 UID，优先于 filters.assetId；省略时搜索素材库。
query	1–200 个字符，至少包含文字或数字。
mode	keyword（默认，关键词）、phrase（完整短语）或 contains（包含文字）。
porter	在 keyword 模式下启用英文词形扩展，默认 false；不会翻译查询。
filters	使用上方的信息筛选参数；仅匹配未进入垃圾箱且已建立字幕索引的视频。
pageSize	1–50，默认 20。
cursor	后续请求传入上次返回的 nextCursor。

每个 items 条目包含素材摘要 asset、字幕 version、startMs、endMs 和命中台词 cues。台词高亮使用 UTF-16 偏移，start 包含、end 不包含。

结果还包含 hasMore、nextCursor、scanned 和 partial。partial: true 表示达到扫描预算；若 hasMore 为 true，即使当前页未满，也应继续使用游标。分页时保持查询、模式、词形扩展和筛选不变；条件变化时清空游标。

能读取字幕、但尚未建立字幕搜索索引的视频，不会命中搜索。

整理与导入

未开启允许整理与导入时，这些工具返回 write_disabled。ClipSeek 不提供逐次调用确认框；客户端审批单独控制。

参数、示例与导入限制

创建文件夹

{ "name": "Campaign 2026" }

create_folder 创建逻辑文件夹，返回 folder。名称去除首尾空白后不能为空、不能包含 / 或 :，也不能以 . 开头。不创建磁盘目录。

更新标签

{ "assetUid": "素材 UUID", "add": ["minimal", "blue"], "remove": ["draft"] }

update_asset_tags 返回 assetUid 和更新后的完整 tags。add、remove 默认空数组。标签名不能为空或含逗号；添加不存在的标签时会创建标签。每次调用原子更新。

调整文件夹归属

{ "assetUids": ["素材 UUID 1", "素材 UUID 2"], "folderId": 8 }

move_assets_to_folder 接受 1–100 个 UID，返回 moved。folderId 为 null 或省略时表示未分类。任一素材无效、不存在或在垃圾箱时，调用失败。不移动源文件。

导入本机素材

{ "paths": ["/绝对路径/reference.jpg", "/绝对路径/campaign"], "folderId": 8 }

import_assets 接受运行 ClipSeek 的电脑上的 1–100 个绝对路径，目录递归最多 16 层，不跟随符号链接；支持的素材会排队复制进素材库。folderId 可省略或为 null，表示未分类。无效路径和不支持的文件会被忽略，没有可接受文件时返回 invalid_argument。

支持的扩展名：jpg、jpeg、png、webp、bmp、svg、heic、heif、gif、mp4、mov、webm、mkv、avi、m4v。实际解码仍取决于文件与平台。

排队前检查授权额度、剩余磁盘空间和冲突任务。按内容哈希跳过重复文件；同一时刻只运行一个导入任务。立即返回的 { "operationId", "queued" } 不代表完成，请用 get_operation 获取最终数量。

下载与生成文件

这些工具不需要整理与导入权限，也不修改原件。原件和生成文件的下载信息包含 downloadId、url、fileName、mimeType、size 和 expiresAt。

原件下载、图片变体与视频片段参数

create_asset_download

必填：assetUid。可选：libraryId、fileName。自定义文件名只影响下载响应，不能包含路径或控制字符。

下载通常在 10 分钟后失效；关闭 MCP 或重新生成令牌，会撤销已有下载授权。URL 包含独立于 MCP Bearer Token 的下载凭据，请对完整地址保密。支持 GET/HEAD 和单段 Range；多段 Range 返回 HTTP 416。

create_image_variant

{
  "assetUid": "图片 UUID",
  "width": 1200,
  "height": 630,
  "fit": "cover",
  "format": "webp",
  "quality": 85,
  "background": "#ffffff"
}

只接受静态图片。width、height 至少提供一个，各为 1–8192；只提供一边时保持比例。两边都有时，contain（默认）用背景补边，cover 居中裁剪。格式为 jpeg、png、webp；省略时尽量保留这三种源格式，否则输出 WebP。quality 为 JPEG 编码质量，1–100，默认 85。背景为 #RRGGBB，默认白色。应用 EXIF 方向，输出不复制原始元数据。

create_video_clip

{
  "assetUid": "视频 UUID",
  "startMs": 12500,
  "endMs": 18000,
  "maxWidth": 1920,
  "quality": "balanced"
}

只接受视频，不含 GIF。要求 0 <= startMs < endMs <= durationMs。可选 maxWidth 为 320–3840，保持比例且不放大。quality 为 compact、balanced（默认）或 high。输出为 H.264 MP4，源视频有音轨时使用 AAC。不提供烧录字幕或导出字幕文件的参数。

两种派生工具都接受可选 libraryId，并返回 operationId；任务完成后的 result 提供下载信息。

后台任务

用 { "operationId": "任务 UUID" } 调用 get_operation，直到 status 为 completed 或 failed。

• 状态为 queued、running、completed、failed；progress 范围为 0–1。
• kind 为 import、image_variant 或 video_clip；stage 表示当前阶段。
• 导入时检查 total、done、failed 和 duplicates。任务失败也可能已经成功导入部分文件。
• result 包含最终数量或下载信息；error 提供失败代码和说明。
• 任务记录只存在于当前 ClipSeek 进程内。重启或清理后，旧 ID 返回 invalid_argument。

预览资源

资源模板与大小限制

通过 resources/templates/list 发现，再用 resources/read 读取：

clipseek://libraries/{libraryId}/assets/{assetUid}/preview
clipseek://libraries/{libraryId}/frames/{frameUid}

使用素材结果和帧列表返回的 URI。结果是不超过 20 MiB 的 Base64 图片，格式为 JPEG、PNG、GIF 或 WebP。只解析素材库中已登记的图片路径，拒绝无效 ID、路径穿越和符号链接逃逸。不通过这些资源返回原始视频。资源错误在 error data 中包含业务 code。

常见错误

代码	处理方式
library_not_open、library_not_found	打开素材库，或从 list_libraries 返回的列表选择 ID。
asset_not_found	刷新结果；素材可能不存在或已在垃圾箱。
invalid_argument	检查 ID、参数、数量限制、游标或任务是否仍有效。
subtitle_changed	从第一页重新读取字幕。
write_disabled、mcp_disabled	检查服务及整理与导入开关。
quota_exceeded、quota_usage_unavailable、disk_space_insufficient	检查可用额度、已登记素材库和磁盘空间，再重试导入。
operation_busy、too_many_operations	等待冲突任务结束，或等待派生任务空位。
asset_type_unsupported、invalid_time_range	检查素材类型和源视频时长。
derivative_failed	查看错误说明，检查源素材和磁盘空间。
download_expired、download_not_found	重新获取下载链接。
rate_limited	降低请求频率，稍后重试。

其他运行时错误可能包含 library_upgrade_required、unauthorized、db、io、json、library_state、generic。请结合返回的说明判断；模型加载失败时还需检查本机模型设置。处理方法见设置与故障排查和 MCP 安全与权限。