> ## Documentation Index
> Fetch the complete documentation index at: https://developers.apob.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Library and element tools

> Browse personal models and media, create character models, and manage reusable elements through MCP.

All calls use the authenticated OAuth account. Listing returns metadata;
listing a model or media item does not prove it is ready for generation.

## Personal library

### list\_personal\_models

All inputs are optional:

| Input | Contract |
| - | - |
| `usages` | Nonempty array of supported model usages; defaults to `["portraitSim"]`. |
| `pageNumber` | Integer `1–1000`; default `1`. |
| `pageSize` | Integer `1–50`; default `20`. |

`pageNumber × pageSize` must not exceed `1000`. Results are newest first and
contain `items`, `hasMore`, `pageNumber`, `pageSize`. Each item includes
`modelId`, nullable `name`, `usage`, `isPublic`, and nullable `createdTime`
(ISO 8601). The tool returns no model files or URLs.

Supported usages are `chat`, `tweet`, `portrait`, `portraitSim`, `textSpeech`,
`imageVideoHigh`, `imageVideoBest`, `imageVideoUltra`, `talkingAvatarUltra`,
`reStyle`, `promptCameraMovement`, `reEverything`, `reShot`.

### list\_personal\_medias

All inputs are optional:

| Input | Contract |
| - | - |
| `modelId` | Nonblank model filter. |
| `mediaTypes` | Array of supported media categories. Omission uses personal-history defaults; `[]` matches nothing. |
| `fileTypes` | Array of `text`, `image`, `audio`, `video`; `[]` matches nothing. |
| `previousId` | Positive signed 64-bit media ID string from the previous `nextCursorId`; omit on the first page. |
| `pageSize` | Integer `1–50`; default `20`. |

Results are newest first and contain `items`, `hasMore`, nullable `nextCursorId`,
and `pageSize`. Continue with `previousId: nextCursorId` while keeping filters
unchanged. An `INVALID_CURSOR` error requires restarting from the first page.

Each item contains `mediaId`, nullable `modelId`, `contentId`, `title`, `quality`,
`createdTime` (ISO 8601), plus `mediaType` and `fileType`. The tool returns no media
URLs; retrieve completed generation outputs with
[`get_generation_result`](/mcp/generation#results-and-errors).

<Accordion title="Supported mediaTypes">
  `none`, `chat`, `tweet`, `image`, `upscale`, `faceSwap`, `song`, `imageVideo`,
  `videoVideo`, `portraitMaster`, `businessImage`, `textSpeech`, `vton`,
  `simVtonPoor`, `simProduct`, `ideaText`, `textOptimization`, `mixVideo`,
  `textVideo`, `imageRemoveBackground`, `imageEnlarge`, `audioVideo`,
  `videoLipSync`, `videoTalkingAvatar`, `clothingPreprocess`, `voiceDesign`,
  `imageEdit`, `cloneImage`, `cloneVideo`, `cameraMovement`, `mixVideoV2`,
  `videoUpscale`, `mixVideoV2ScriptOptimize`, `mixVideoV3Storyboard`, `mixVideoV3`,
  `followMovement`, `subtitleVideoRender`, `bgmVideo`, `revideoReferenceImage`,
  `extendVideo`, `productPreprocess`, `reStyle`, `reEverything`, `reProduct`,
  `reBackground`, `reShot`, `reMotion`, `textMusic`.
</Accordion>

## Character models

### create\_model

Creates one portrait SIM model from exactly one owned image `sourceMediaId` or
canonical `uploadedImage: { "url": "..." }` from
[media preparation](/mcp/uploads-and-live).

| Input | Required | Contract |
| - | - | - |
| `name` | Yes | Nonblank, at most 100 characters. |
| `sourceMediaId` or `uploadedImage` | Exactly one | Your owned image source. |
| `description` | No | String up to 512 characters; empty is allowed. |
| `isPublic` | No | Boolean; defaults to `true`. Explicit `false` requires account eligibility. |

Account model limits and preprocessing still apply. The receipt contains
`modelId`, `taskId`, `status`, and `terminal`.

<Warning>
  Model creation defaults to public visibility and is non-idempotent. Choose
  visibility intentionally. Do not automatically retry an uncertain creation;
  check personal models first.
</Warning>

### get\_model\_status

Required: nonblank `modelId`, at most 200 characters. Reads your own active
portrait SIM model and its root model task. Returns `modelId`, `taskId`,
`status`, `terminal`, `ready`, and nullable `error`. `ready` requires successful
completion. Terminal failures expose sanitized `MODEL_FAILED` details.

Retrying this read does not create another model. `get_generation_result`
reads content tasks; use `get_model_status` for model readiness.

Model errors include `MODEL_NOT_FOUND` (unavailable or not owned),
`MODEL_POLICY_REJECTED` (privacy/model-limit policy), `MODEL_READ_FAILED`
(retry the same read), and `MODEL_SUBMISSION_UNCONFIRMED` (reconcile before any
new submission).

## Elements

Elements can be discovered from your library or the community, created from
uploads or existing media/models, and bound in generation through `elementIds`.
The categories are `Character`, `Product`, `Background`, `Style`, `Others`.
IDs are positive signed 64-bit decimal strings.

### list\_elements

Optional inputs: `scope` (`personal`, default; or `community`), `category`,
`fileType` (`image`, `audio`, `video`), `pageNumber` (positive signed 32-bit integer,
default `1`), `pageSize` (`1–50`, default `20`).

Returns `items`, `hasMore`, `pageNumber`, `pageSize`. Summaries contain
`elementId`, `isDerived`, `ownedByCaller`, `canManage`, `name`, nullable
`category`, `description`, `previewUrl`, plus `isPublic`, `fileType`, and
optional `width`/`height`. Preview URLs are temporary.

Lists contain ordinary elements. Derived media/model elements are excluded
from list results; their returned IDs can still be read and referenced.

### get\_element

Required: `elementId`. Reads an owned or public accessible element, including
derived elements. Returns the summary plus `resources`. Each resource contains
`fileType`, temporary `url`, and optional `previewUrl`, `width`, `height`,
`durationMs`.

### create\_element

Required: nonblank `name` and **exactly one** source:
`mediaId`, `modelId`, `images`, `audios`, or `videos`.

Optional: `category` (default `Others`), string `description`, `isPublic`
(uploaded ordinary elements only; default `false`). Upload arrays must be
nonempty and contain objects with only the canonical `url` from your own
`import_file` or `complete_file_upload`. The server resolves media metadata.

Media/model-derived elements inherit source ownership and visibility, may
reuse an existing derived element, and reject an `isPublic` override. Derived
elements can be read and used in generation, but cannot be edited, published,
hidden, or deleted with MCP management tools.

Returns a write receipt: `elementId`, `isDerived`, `ownedByCaller`, `canManage`,
`name`, `category`, nullable `description`, `isPublic`. Use `get_element` for
fresh resource URLs. Moderation/processing can continue after creation, so a
receipt does not guarantee ready generation references.

### update\_element

Required: `elementId` and at least one updated field. Optional update fields:
nonblank `name`, `category`, string `description`, and at most one nonempty
uploaded `images`, `audios`, or `videos` array in the same shape as creation.

Only owned ordinary elements are manageable. An empty description clears it.
A resource array replaces the **complete** resource set. Null/no-op updates
are rejected. Returns the same public write-receipt fields as creation.

### set\_element\_visibility

Required: `elementId`, boolean `isPublic`. Only owned ordinary elements can be
changed; private visibility requires account eligibility. Returns `elementId`,
`isDerived`, `ownedByCaller`, `canManage`, `isPublic`.

### delete\_element

Required: `elementId`. Deletes an owned ordinary element. Returns `elementId`,
`isDerived`, `ownedByCaller`, `canManage: false`, `deleted: true`.

<Warning>
  Element writes can have uncertain outcomes after an interruption. On
  `ELEMENT_MUTATION_UNCONFIRMED`, check the element or list before retrying.
  Do not treat a failed response as proof that the write did not happen.
</Warning>

Element failures include `INVALID_ARGUMENTS`, `ELEMENT_NOT_ACCESSIBLE`,
`ELEMENT_NOT_MANAGEABLE`, `ELEMENT_VISIBILITY_REJECTED`, and
`ELEMENT_READ_FAILED`. Reads can be retried; retries of mutations need
reconciliation first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.