Autonomously manage the CATIMATION portrait library (人像库)
The portrait library is a persistent, content-deduplicated pool of image /
video / audio assets. It feeds generate_video (reference images, first/last
frames) and keeps the SAME character or scene consistent across clips. Four
catimation MCP tools let you manage it — use them proactively; you do not
need permission to add, search, organize, or download on the user's behalf.
When to Use
- 用户提到 人像库 / 素材库 / 参考素材 / 角色库,要 收藏 / 搜索 / 整理 / 重命名 / 分组 / 删除 / 下载 素材。
- 视频生成需要参考素材(角色 / 场景一致性)→ 先入库拿
asset://assetId 再喂 generate_video(视频/音频类素材先用 ffmpeg-win 抽静帧/抽音轨再入库当参考,不直传原始视频)。
- 用户要复用「上次那个人 / 同一个角色 / 同一个场景」→ 先
list_portrait_library 找回锚点。
- 用户喜欢刚生成的图、之后可能复用 → 主动入库。
Tools
add_to_portrait_library — upload ONE asset. source may be a local
file path, data: URL, https URL, or an existing asset://assetId. Kind
(image/video/audio) is auto-detected (override with kind); for people use
imageCategory: image_people (default). Identical content dedupes to the same
assetId. Returns { assetId, assetUrl, name, duplicated }. 图像 asset 的
assetUrl (asset://…) 可直传 generate_video;但视频/音频 asset 不直接当视觉参考
——先用 ffmpeg-win 抽干净关键帧 / 拼宫格图(或抽音轨),把静帧 / 音频入库再喂,原始
视频仅留底(尤其是 Seedance 自产片段,整段回喂会二次编码、画质打折)。
list_portrait_library — search / browse. Optional query (name text),
kind (all/image_people/image_environment/video/audio),
group, page, pageSize, includeHidden. Returns items with
assetId, display name, kind, custom group, and asset://assetId. This
is how you FIND material and look up assetIds before editing/downloading.
edit_portrait_library — organize via action:
rename (assetId + name), move_group (assetIds + group; omit
group to ungroup), hide / unhide (assetIds; hide = soft-delete,
recoverable), new_group / delete_group (group). Edits appear live on
the user's 人像库 page.
download_portrait_asset — save an asset locally; pass the sourceUrl
from list_portrait_library. Returns the saved local path.
审核闸门(上传后别立刻拿去生成 ⚠️)
add_to_portrait_library 上传新素材后,上游会先做内容审核(审核)。审核
未通过 / 仍在审核中的素材,直接把它的 asset://assetId 喂给 generate_video
会让生成任务直接失败(如 内容审核未通过 / 素材不可用)。所以:
- ✅ 复用库里已存在的素材最稳——它们早已审核通过。
- ✅
add_to_portrait_library 返回 duplicated: true = 命中去重 = 已在库 =
已审核,可以立刻用。
- ⛔ 全新上传(
duplicated: false)不要审核没过就抢着生成:先确认审核通过
——用 list_portrait_library 能正常查到、人像库页面对该素材无「审核中 / 待审核」
标记后再 generate_video;或直接告诉用户「素材正在审核,通过后再生成」并停下,
不要赌它已通过。
- 一句话:先入库 → 等审核过 → 再生成,顺序不能颠倒。
Proactive workflows
- User mentions video generation with material →
add_to_portrait_library
each provided image/video/audio FIRST. Then — only after it clears review
(see 审核闸门 above; a duplicated:true result is already reviewed) —
reference the returned asset://assetId in generate_video. (Images passed
directly to generate_video are auto-imported; videos/audio and any "save
for later" material are on you.)
- Reuse a character/scene ("还是上次那个人 / 同一个角色 / 同一个场景") →
list_portrait_library to find the matching asset://assetId, then
reference it — this is what keeps identity consistent.
- User likes a generated image and may reuse it → proactively
add_to_portrait_library it (imageCategory: image_people for people).
- Tidy up → give new assets clear names (
rename) and group related
material (new_group + move_group) when it helps the user find things.
- Save/export →
list_portrait_library to get the sourceUrl, then
download_portrait_asset.
Notes
- The library can be LARGE.
list_portrait_library is paginated — narrow first
with query/kind/group, read the returned page/totalPages/hasMore,
and when hasMore is true page through with page:N+1. Do NOT crank up
pageSize to dump everything (large results get truncated and waste context).
- Always
list_portrait_library to obtain assetId / sourceUrl before any
edit_portrait_library or download_portrait_asset call — do not guess ids.
- The library exists only on platform balance (the user is logged in and
generating on 平台余额; it is the 素材库 of the active billing pool). With the
user's own Miau key there is NO portrait library:
list_portrait_library
returns an empty page with a note and add_to_portrait_library fails. Relay
that to the user (switch to 平台余额 to use the library) instead of retrying.
asset:// ids are not interchangeable between billing pools.
- Renaming / grouping / hiding is a local organizing layer shared with the UI;
it never deletes upstream data (hide is reversible via
unhide).
Common Mistakes
- 新上传的素材审核没过就抢着
generate_video(任务必失败):见上「审核闸门」,
先等审核通过(或复用 duplicated:true 的已审核素材)再生成。
- 凭空猜
assetId / sourceUrl;必须先 list_portrait_library 查到再用。
- 漏
list 直接 edit_portrait_library / download_portrait_asset。
- 调高
pageSize 一次性 dump 整库(结果会被截断、浪费上下文),应先用 query/kind/group 收窄再翻页。
- 自填 Miau Key 模式下仍硬调入库(那边没有人像库);转告用户切到平台余额再用,别反复重试。
1---2name: catimation-portrait-library3description: >-4 Autonomously manage the CATIMATION portrait library (人像库 / 素材库) — the5 persistent, deduplicated pool of image / video / audio reference assets that6 keeps characters & scenes consistent. Use when the user mentions 人像库 / 素材库 /7 参考素材 / 角色库, wants to save / 收藏 / 搜索 / 整理 / 重命名 / 分组 / 删除 / 下载 a reference8 asset, or when a reference asset is needed for 视频生成 / video generation. Add,9 search, organize, rename, group, hide, download proactively.10metadata:11 source: https://skillmd.com/skills/2799662352/catimation-portrait-library12---1314# Autonomously manage the CATIMATION portrait library (人像库)1516<!-- skill-budget: fast -->1718The portrait library is a persistent, content-deduplicated pool of image /19video / audio assets. It feeds `generate_video` (reference images, first/last20frames) and keeps the SAME character or scene consistent across clips. Four21`catimation` MCP tools let you manage it — use them proactively; you do not22need permission to add, search, organize, or download on the user's behalf.2324## When to Use2526- 用户提到 人像库 / 素材库 / 参考素材 / 角色库,要 收藏 / 搜索 / 整理 / 重命名 / 分组 / 删除 / 下载 素材。27- 视频生成需要参考素材(角色 / 场景一致性)→ 先入库拿 `asset://assetId` 再喂 `generate_video`(**视频/音频类素材先用 `ffmpeg-win` 抽静帧/抽音轨再入库当参考,不直传原始视频**)。28- 用户要复用「上次那个人 / 同一个角色 / 同一个场景」→ 先 `list_portrait_library` 找回锚点。29- 用户喜欢刚生成的图、之后可能复用 → 主动入库。3031## Tools3233- **`add_to_portrait_library`** — upload ONE asset. `source` may be a local34 file path, `data:` URL, `https` URL, or an existing `asset://assetId`. Kind35 (image/video/audio) is auto-detected (override with `kind`); for people use36 `imageCategory: image_people` (default). Identical content dedupes to the same37 `assetId`. Returns `{ assetId, assetUrl, name, duplicated }`. **图像** asset 的38 `assetUrl` (`asset://…`) 可直传 `generate_video`;但**视频/音频 asset 不直接当视觉参考**39 ——先用 `ffmpeg-win` 抽干净关键帧 / 拼宫格图(或抽音轨),把**静帧 / 音频**入库再喂,原始40 视频仅留底(尤其是 Seedance 自产片段,整段回喂会二次编码、画质打折)。41- **`list_portrait_library`** — search / browse. Optional `query` (name text),42 `kind` (`all`/`image_people`/`image_environment`/`video`/`audio`),43 `group`, `page`, `pageSize`, `includeHidden`. Returns items with44 `assetId`, display name, kind, custom `group`, and `asset://assetId`. This45 is how you FIND material and look up assetIds before editing/downloading.46- **`edit_portrait_library`** — organize via `action`:47 `rename` (`assetId` + `name`), `move_group` (`assetIds` + `group`; omit48 `group` to ungroup), `hide` / `unhide` (`assetIds`; hide = soft-delete,49 recoverable), `new_group` / `delete_group` (`group`). Edits appear live on50 the user's 人像库 page.51- **`download_portrait_asset`** — save an asset locally; pass the `sourceUrl`52 from `list_portrait_library`. Returns the saved local path.5354## 审核闸门(上传后别立刻拿去生成 ⚠️)5556`add_to_portrait_library` 上传**新**素材后,上游会先做**内容审核(审核)**。审核57未通过 / 仍在审核中的素材,直接把它的 `asset://assetId` 喂给 `generate_video`58**会让生成任务直接失败**(如 `内容审核未通过` / 素材不可用)。所以:5960- ✅ **复用库里已存在的素材最稳**——它们早已审核通过。61- ✅ `add_to_portrait_library` 返回 `duplicated: true` = 命中去重 = 已在库 =62 已审核,**可以立刻用**。63- ⛔ 全新上传(`duplicated: false`)**不要审核没过就抢着生成**:先确认审核通过64 ——用 `list_portrait_library` 能正常查到、人像库页面对该素材无「审核中 / 待审核」65 标记后再 `generate_video`;或直接告诉用户「素材正在审核,通过后再生成」并停下,66 **不要赌它已通过**。67- 一句话:**先入库 → 等审核过 → 再生成**,顺序不能颠倒。6869## Proactive workflows70711. **User mentions video generation with material** → `add_to_portrait_library`72 each provided image/video/audio FIRST. Then — only after it clears review73 (see 审核闸门 above; a `duplicated:true` result is already reviewed) —74 reference the returned `asset://assetId` in `generate_video`. (Images passed75 directly to `generate_video` are auto-imported; videos/audio and any "save76 for later" material are on you.)772. **Reuse a character/scene** ("还是上次那个人 / 同一个角色 / 同一个场景") →78 `list_portrait_library` to find the matching `asset://assetId`, then79 reference it — this is what keeps identity consistent.803. **User likes a generated image and may reuse it** → proactively81 `add_to_portrait_library` it (`imageCategory: image_people` for people).824. **Tidy up** → give new assets clear names (`rename`) and group related83 material (`new_group` + `move_group`) when it helps the user find things.845. **Save/export** → `list_portrait_library` to get the `sourceUrl`, then85 `download_portrait_asset`.8687## Notes8889- The library can be LARGE. `list_portrait_library` is paginated — narrow first90 with `query`/`kind`/`group`, read the returned `page`/`totalPages`/`hasMore`,91 and when `hasMore` is true page through with `page:N+1`. Do NOT crank up92 `pageSize` to dump everything (large results get truncated and waste context).93- Always `list_portrait_library` to obtain `assetId` / `sourceUrl` before any94 `edit_portrait_library` or `download_portrait_asset` call — do not guess ids.95- The library exists **only on platform balance** (the user is logged in and96 generating on 平台余额; it is the 素材库 of the active billing pool). With the97 user's own Miau key there is NO portrait library: `list_portrait_library`98 returns an empty page with a note and `add_to_portrait_library` fails. Relay99 that to the user (switch to 平台余额 to use the library) instead of retrying.100 `asset://` ids are not interchangeable between billing pools.101- Renaming / grouping / hiding is a local organizing layer shared with the UI;102 it never deletes upstream data (hide is reversible via `unhide`).103104## Common Mistakes105106- **新上传的素材审核没过就抢着 `generate_video`**(任务必失败):见上「审核闸门」,107 先等审核通过(或复用 `duplicated:true` 的已审核素材)再生成。108- 凭空猜 `assetId` / `sourceUrl`;必须先 `list_portrait_library` 查到再用。109- 漏 `list` 直接 `edit_portrait_library` / `download_portrait_asset`。110- 调高 `pageSize` 一次性 dump 整库(结果会被截断、浪费上下文),应先用 `query`/`kind`/`group` 收窄再翻页。111- 自填 Miau Key 模式下仍硬调入库(那边没有人像库);转告用户切到平台余额再用,别反复重试。