List assets

Availability

This page documents the Modelflare asset-management route. Calls require a valid media API key, an available media channel, and the required permission.

Note

The gateway records provider asset IDs, status, and user ownership. The Castaly local library remains separate from the provider asset namespace.

Endpoint

POST https://modelflare.dev/volc/asset/ListAssets

Authentication

Use a Modelflare API key:

bash

-H "Authorization: Bearer YOUR_MODELFLARE_API_KEY"

Send Idempotency-Key with create, update, and delete requests. Retrying the same key for the same user replays the saved response without repeating the mutation.

Request

List assets with optional name, group, and group-type filters. Wait for Status: Active before using an ID in a Seedance request.

Field	Type	Required	Description	Example
model	string	Yes	Billing model. Defaults to volc-asset.	volc-asset
Filter.Name	string	No	Fuzzy asset-name filter.	character
Filter.GroupIds	string[]	No	Filter by group IDs.	["group-20260320141746-zsf6b"]
Filter.GroupType	AIGC	LivenessFace	No	Filter by group type.
PageNumber	integer	No	Page number. Defaults to 1.	1
PageSize	integer	No	Items per page. Defaults to 10.	10

JSON example:

JSON

{
  "model": "volc-asset",
  "Filter": {
    "Name": "character",
    "GroupIds": [
      "group-20260320141746-zsf6b"
    ],
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10
}

cURL example:

bash

curl --request POST https://modelflare.dev/volc/asset/ListAssets \
  --header "Authorization: Bearer YOUR_MODELFLARE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "volc-asset",
  "Filter": {
    "Name": "character",
    "GroupIds": [
      "group-20260320141746-zsf6b"
    ],
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10
}'

Response

The request succeeded.

Field	Type	Required	Description	Example
Items[]	object[]	No	Asset objects with identity, type, group, status, project, and timestamps.	{ Id, Name, AssetType, GroupId, Status, ... }
Items[].Id / Name	string	No	Asset identity and display name.	asset-20260528140922-d9646 / character-reference
Items[].AssetType / GroupId	string	No	Asset type and owning group.	Image / group-20260320141746-zsf6b
Items[].Status / ProjectName	string	No	Processing state and project name.	Active / default
Items[].CreateTime / UpdateTime	string	No	ISO 8601 creation and update timestamps.	2026-03-20T14:25:01Z
Items[].URL	string	No	Temporary file URL. The documented lifetime is 12 hours; use asset://<ID> for generation requests.	https://example.com/temporary-asset
Items[].Error	object	No	Processing error with Code and Message when Status is Failed.	{ Code, Message }
PageNumber	integer	No	Returned page number.	1
PageSize	integer	No	Returned page size.	10
TotalCount	integer	No	Total matching assets.	2

Response example:

JSON

{
  "Items": [
    {
      "Id": "asset-20260528140922-d9646",
      "Name": "character-reference",
      "AssetType": "Image",
      "GroupId": "group-20260320141746-zsf6b",
      "Status": "Active",
      "ProjectName": "default"
    }
  ],
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 1
}

Errors

Status	Meaning
400	The request is invalid.
401	The API key is missing or unauthorized.

Error body example (when returned):

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed."
  }
}

Image, video, and audio creation are asynchronous. After receiving an asset ID, call GetAsset and use the asset://<ID> reference only when the status is Active.