manage_avatar
Manage the user's saved AI avatars, voices, and avatar-video batches. Load the digital-human Skill first; resolve only fields needed for the current intent. Saved avatar reads, rename, delete and default-voice binding work at account scope without a project. Project media and video operations require a targeted project. Reuse a ready saved avatar when the user names its exact ID, attached reference or unique saved name. Ask only when selection is unresolved or ambiguous: use the Widget Forms Skill visual-choice surface with ready saved avatars that have a preview, never text-only choices, and never silently choose among duplicate names. In embedded ChatCut, use ; the host prefers video and falls back to its image. Reuse an available saved defaultVoice unless the user asks for another voice; defaultVoice reports its current name and availability. Pass defaultVoiceRef to submit contracts. An exact user-chosen voice needs no picker. When voice choice is ambiguous or the user wants auditions, call manage_voice action=list use=avatar and use playable choices with a non-empty previewUrl plus a localized clone_voice action. If no saved avatar is suitable, offer create. Photo creation/revision requires an imported project JPEG/PNG and explicit likeness consent; an upload alone is not consent. Never pass an external source URL. Delete only after explicit confirmation. Voice results expose opaque voiceRef values. Never request, infer, or reveal provider, model, engine, or provider-specific identifiers. In published plugins, never emit raw ChatCut tags. In Codex, map the saved identity id to id, name to label, previewVideoUrl to previewVideo, and previewImageUrl to preview as poster/fallback. Voice choices map voiceRef to the host option id and previewUrl to its audio URL. Embedded voice selection uses one with playable cards and a final card.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"action": "<action>"
},
"name": "manage_avatar"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Required for create. | |
| name | No | Required for create and rename. | |
| text | No | Optional replacement text for regenerate-segment when keeping the existing voice. | |
| limit | No | Total playable voice result limit, from 1 to 100. Defaults to 5. Use exactly 5 when recommending voices; request more only when the user explicitly asks to browse more. | |
| token | No | Opaque continuation token for voices. | |
| action | Yes | ||
| prompt | No | Synthetic-avatar description for prompt creation or revision. | |
| speech | No | Optional replacement speech source object for regenerate-segment. Pass an object, never a quoted or JSON-stringified value. | |
| taskId | No | Required for get-task, accept-task, and retry-task. Accepts a unique id prefix. | |
| batchId | No | Required for get-batch, regenerate-segment, remove-segment, and reorder-segments. Accepts a unique id prefix. | |
| refresh | No | For get: refresh non-terminal identity revisions first. | |
| language | No | Optional language filter for voices. | |
| voiceRef | No | Required for set-default-voice: opaque voiceRef (from manage_voice action=list use=avatar) to save as the avatar's default voice for future generations. | |
| projectId | No | Project for this call (full ID or unambiguous prefix). Explicit-timeline calls never change the target of later calls; legacy project selection applies otherwise. | |
| segmentId | No | Required for regenerate-segment and remove-segment. Accepts a unique id prefix. | |
| identityId | No | Required for get, rename, set-default-voice, create-revision, and delete. Accepts a unique id prefix or an exact, unique saved avatar name. | |
| segmentIds | No | For reorder-segments, every active segment exactly once in the intended order. | |
| timelineId | No | ||
| sourceAssetId | No | Imported ChatCut JPEG/PNG asset for photo create/create-revision. A video must be converted to a representative still first. | |
| confirmedDelete | No | Required and true for delete after the user explicitly confirmed permanent deletion. | |
| confirmedConsent | No | Required and true when create/create-revision uses a real-person image. The user explicitly confirmed ownership or permission. |