---
title: "List the characters in your asset library"
method: GET
path: "/api/v1/assets/entities"
tags: ["Assets"]
---

# List the characters in your asset library

`GET /api/v1/assets/entities`

## Request

- Base URL: `https://api.popnow.ai`
- URL: `https://api.popnow.ai/api/v1/assets/entities`
- Auth: HTTP bearer

A character is a named set of images saved in the same library, kept in
the order arranged in the console. It references those assets instead of
copying them: deleting a character never deletes its images, and deleting
an image removes it from every character. Characters are created and
edited in the console; this API only reads them.

The key decides the library exactly as for `GET /api/v1/assets`. Each
image is an asset with its stable `uri` (`popnow://a/<id>`), usable in
generation requests made with keys of the same workspace, and a private
`previewUrl` signed for at most 20 minutes. `cover` is the cover image
(null while the character has no images).

Newest first, one page at a time: pass the previous page's `nextCursor`
as `cursor`. Pass `assetId` to list only the characters that contain that
asset. Responses are `private, no-store`; reading characters shares the
limit of 60 requests per minute per account with reading assets.

## Query parameters

- `kind` 'character'
- `assetId` string
- `cursor` string
- `limit` integer

## Response `200`

One page of characters.

- AssetEntityListEnvelope
  - `code` 200, required
  - `msg` 'success', required
  - `request_id` string, required: Correlation identifier. Include it in support requests.
  - `data` object, required
    - `items` AssetEntity[], required
      - `id` string, required
      - `kind` 'character', required
      - `name` string, required: Unique within the library and kind (case-insensitive).
      - `note` string, required
      - `coverAssetId` string, required: Empty while the character has no images.
      - `cover` Asset, required
        - `id` string, required
        - `uri` string, required: Stable reference. Works only in generation requests made with keys of the same workspace; it is never a downloadable link.
        - `name` string, required
        - `kind` 'image' | 'video' | 'audio', required
        - `contentType` string, required
        - `bytes` integer, required
        - `width` integer
        - `height` integer
        - `durationSeconds` number
        - `source` 'task_output' | 'upload' | 'url', required
        - `sourceId` string, required: Your task or upload id; for url, an opaque digest of the address (the address itself is not stored).
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `previewUrl` string, required: Private preview signed for you for at most 20 minutes; empty when signing fails. Do not store or share it — persist uri instead.
        - `previewUrlExpiresAt` string, date-time
        - `favorite` boolean, required: Favorite mark of the library (shared by everyone in a team).
        - `model` string, required: Public name of the model that generated the asset, for example bytedance/seedream-5.0-pro/text-to-image; empty for uploads and links.
        - `modelName` string, required: Display name of that model; empty when the asset was not generated or the name is unknown.
      - `assets` Asset[], required: The character's images in order.
        - `id` string, required
        - `uri` string, required: Stable reference. Works only in generation requests made with keys of the same workspace; it is never a downloadable link.
        - `name` string, required
        - `kind` 'image' | 'video' | 'audio', required
        - `contentType` string, required
        - `bytes` integer, required
        - `width` integer
        - `height` integer
        - `durationSeconds` number
        - `source` 'task_output' | 'upload' | 'url', required
        - `sourceId` string, required: Your task or upload id; for url, an opaque digest of the address (the address itself is not stored).
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `previewUrl` string, required: Private preview signed for you for at most 20 minutes; empty when signing fails. Do not store or share it — persist uri instead.
        - `previewUrlExpiresAt` string, date-time
        - `favorite` boolean, required: Favorite mark of the library (shared by everyone in a team).
        - `model` string, required: Public name of the model that generated the asset, for example bytedance/seedream-5.0-pro/text-to-image; empty for uploads and links.
        - `modelName` string, required: Display name of that model; empty when the asset was not generated or the name is unknown.
      - `count` integer, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `nextCursor` string: Absent on the last page.

## Other responses

- `400`: Invalid JSON, query, callback URL, model input, or media declaration. Invalid callBackUrl values return code 400 and msg "Invalid callback URL" with request_id. Submitted hosts, IP addresses, and DNS diagnostics are not echoed.
- `401`: Missing, malformed, expired, revoked, or otherwise invalid API key.
- `403`: Account, model, API-key, IP, or region authorization failed.
- `429`: Account-level request limit exceeded.
- `500`: Internal failure. Details are not exposed; report `request_id` to support.

## Changes

- **2026-10-20** `fede911a6e9b`: 60 warning
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `400`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `401`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `403`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `429`
  - …56 more

[Operation history](https://skmtc.dev/popnow/apis/popnow-api/changes/api/v1/assets/entities/get.md)

---

[API](https://skmtc.dev/popnow/apis/popnow-api.md) · [All operations](https://skmtc.dev/popnow/apis/popnow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/popnow/apis/popnow-api/revisions/fede911a6e9b?raw)