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.
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 } — pass
assetUrl (asset://…) straight into generate_video.
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.
Proactive workflows
- User mentions video generation with material →
add_to_portrait_library
each provided image/video/audio FIRST, then 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.
- All four tools need the Seedance API Key AND API Secret configured
(Settings → Seedance; the library interface is HMAC-signed). If missing, the
tool tells you to ask the user to set them — relay that and stop.
- Renaming / grouping / hiding is a local organizing layer shared with the UI;
it never deletes upstream data (hide is reversible via
unhide).
1---2name: catimation-portrait-library-23description: Autonomously manage the CATIMATION portrait library (人像库 / 素材库) — the persistent, deduplicated pool of image / video / audio assets that powers video generation and keeps characters & scenes consistent. Use whenever the user mentions 人像库 / 素材库 / 参考素材 / 角色库, wants to save / 收藏 / 搜索 / 整理 / 重命名 / 分组 / 删除 / 下载 a reference asset, or whenever you need an asset for 视频生成 / video generation. Add, search, organize, rename, group, hide, download proactively.4---56# Autonomously manage the CATIMATION portrait library (人像库)78The portrait library is a persistent, content-deduplicated pool of image /9video / audio assets. It feeds `generate_video` (reference images, first/last10frames) and keeps the SAME character or scene consistent across clips. Four11`catimation` MCP tools let you manage it — use them proactively; you do not12need permission to add, search, organize, or download on the user's behalf.1314## Tools1516- **`add_to_portrait_library`** — upload ONE asset. `source` may be a local17 file path, `data:` URL, `https` URL, or an existing `asset://assetId`. Kind18 (image/video/audio) is auto-detected (override with `kind`); for people use19 `imageCategory: image_people` (default). Identical content dedupes to the same20 `assetId`. Returns `{ assetId, assetUrl, name, duplicated }` — pass21 `assetUrl` (`asset://…`) straight into `generate_video`.22- **`list_portrait_library`** — search / browse. Optional `query` (name text),23 `kind` (`all`/`image_people`/`image_environment`/`video`/`audio`),24 `group`, `page`, `pageSize`, `includeHidden`. Returns items with25 `assetId`, display name, kind, custom `group`, and `asset://assetId`. This26 is how you FIND material and look up assetIds before editing/downloading.27- **`edit_portrait_library`** — organize via `action`:28 `rename` (`assetId` + `name`), `move_group` (`assetIds` + `group`; omit29 `group` to ungroup), `hide` / `unhide` (`assetIds`; hide = soft-delete,30 recoverable), `new_group` / `delete_group` (`group`). Edits appear live on31 the user's 人像库 page.32- **`download_portrait_asset`** — save an asset locally; pass the `sourceUrl`33 from `list_portrait_library`. Returns the saved local path.3435## Proactive workflows36371. **User mentions video generation with material** → `add_to_portrait_library`38 each provided image/video/audio FIRST, then reference the returned39 `asset://assetId` in `generate_video`. (Images passed directly to40 `generate_video` are auto-imported; videos/audio and any "save for later"41 material are on you.)422. **Reuse a character/scene** ("还是上次那个人 / 同一个角色 / 同一个场景") →43 `list_portrait_library` to find the matching `asset://assetId`, then44 reference it — this is what keeps identity consistent.453. **User likes a generated image and may reuse it** → proactively46 `add_to_portrait_library` it (`imageCategory: image_people` for people).474. **Tidy up** → give new assets clear names (`rename`) and group related48 material (`new_group` + `move_group`) when it helps the user find things.495. **Save/export** → `list_portrait_library` to get the `sourceUrl`, then50 `download_portrait_asset`.5152## Notes5354- The library can be LARGE. `list_portrait_library` is paginated — narrow first55 with `query`/`kind`/`group`, read the returned `page`/`totalPages`/`hasMore`,56 and when `hasMore` is true page through with `page:N+1`. Do NOT crank up57 `pageSize` to dump everything (large results get truncated and waste context).58- Always `list_portrait_library` to obtain `assetId` / `sourceUrl` before any59 `edit_portrait_library` or `download_portrait_asset` call — do not guess ids.60- All four tools need the Seedance **API Key AND API Secret** configured61 (Settings → Seedance; the library interface is HMAC-signed). If missing, the62 tool tells you to ask the user to set them — relay that and stop.63- Renaming / grouping / hiding is a local organizing layer shared with the UI;64 it never deletes upstream data (hide is reversible via `unhide`).