ark_asset_list
List private assets by group, type, status or name, or read up to 20 by asset_ids.
Returns each asset’s asset:// URI and status; only Active assets can be used in generation. preview_url is a temporary (~12 h) viewing link; pass asset_uri to Seedance. Assets authorized from another account are not listed but usable by ID. Requires AK/SK.
| Requirement | Value |
|---|---|
| Registration | Requires BYTEPLUS_MODELARK_ACCESS_KEY and BYTEPLUS_MODELARK_SECRET_KEY. |
| Execution | Foreground only |
| Required permission | assets:read |
This site lists the full configured capability surface, not the tools enabled on your particular server. Use model discovery and job discovery to check your connection. Credentials are server configuration, never tool arguments.
Ask your connected AI client to use ark_asset_list for the operation you want.
The client constructs the arguments and handles tool calls. Review its proposed
operation before approving anything billable. For a non-billable introduction,
start with discovery without generation.
Call this tool directly. It is not a background-job target.
Match the input fields below and the full JSON Schema. See the worked examples for this capability and Background Execution for job/result handling.
Inputs
Section titled “Inputs”The MCP arguments object wraps these fields as {"input": {...}}.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
asset_ids |
array of string or null | No | Read these assets (1-20 IDs or asset:// references) instead of listing. Exclusive with the filters.; Default: null |
group_ids |
array of string or null | No | Only assets in these groups.; Default: null |
group_type |
“AIGC”, “LivenessFace” | No | Only assets in groups of this type. Ignored with asset_ids.; Default: “AIGC” |
max_results |
integer | No | Page size (1-100). Ignored with asset_ids.; minimum: 1; maximum: 100; Default: 20 |
name |
string or null | No | Fuzzy asset-name filter.; Default: null |
next_token |
string or null | No | next_token from the previous page.; Default: null |
project_name |
string or null | No | ModelArk project name; defaults to BYTEPLUS_MODELARK_PROJECT_NAME. Assets only work within one project, so keep it consistent.; Default: null |
sort_order |
“Asc”, “Desc” or null | No | Creation-time order; provider default when omitted.; Default: null |
statuses |
array of “Processing”, “Active”, “Failed” or null | No | Only assets with these statuses.; Default: null |
Outputs
Section titled “Outputs”| Field | Type | Required | Description and constraints |
|---|---|---|---|
assets |
array of Asset | Yes | Assets on this page. |
errors |
array of AssetLookupError | No | asset_ids that could not be read. |
next_token |
string or null | No | Pass as next_token for the next page; null on the last page.; Default: null |
Nested Types
Section titled “Nested Types”Field types named above refer to these shared definitions. Optional/null fields, enum choices and bounds are retained in the complete schemas below. Schema validation is followed by runtime capability and security checks.
AssetListInput
| Field | Type | Required | Description and constraints |
|---|---|---|---|
asset_ids |
array of string or null | No | Read these assets (1-20 IDs or asset:// references) instead of listing. Exclusive with the filters.; Default: null |
group_ids |
array of string or null | No | Only assets in these groups.; Default: null |
group_type |
“AIGC”, “LivenessFace” | No | Only assets in groups of this type. Ignored with asset_ids.; Default: “AIGC” |
max_results |
integer | No | Page size (1-100). Ignored with asset_ids.; minimum: 1; maximum: 100; Default: 20 |
name |
string or null | No | Fuzzy asset-name filter.; Default: null |
next_token |
string or null | No | next_token from the previous page.; Default: null |
project_name |
string or null | No | ModelArk project name; defaults to BYTEPLUS_MODELARK_PROJECT_NAME. Assets only work within one project, so keep it consistent.; Default: null |
sort_order |
“Asc”, “Desc” or null | No | Creation-time order; provider default when omitted.; Default: null |
statuses |
array of “Processing”, “Active”, “Failed” or null | No | Only assets with these statuses.; Default: null |
Complete JSON Schemas
Section titled “Complete JSON Schemas”Input schema, including the MCP wrapper
{ "$defs": { "AssetListInput": { "description": "Input for ``ark_asset_list``.", "properties": { "asset_ids": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, { "type": "null" } ], "default": null, "description": "Read these assets (1-20 IDs or asset:// references) instead of listing. Exclusive with the filters." }, "group_ids": { "anyOf": [ { "items": { "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$", "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "description": "Only assets in these groups." }, "group_type": { "default": "AIGC", "description": "Only assets in groups of this type. Ignored with asset_ids.", "enum": [ "AIGC", "LivenessFace" ], "type": "string" }, "max_results": { "default": 20, "description": "Page size (1-100). Ignored with asset_ids.", "maximum": 100, "minimum": 1, "type": "integer" }, "name": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "description": "Fuzzy asset-name filter." }, "next_token": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "default": null, "description": "next_token from the previous page." }, "project_name": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "ModelArk project name; defaults to BYTEPLUS_MODELARK_PROJECT_NAME. Assets only work within one project, so keep it consistent." }, "sort_order": { "anyOf": [ { "enum": [ "Asc", "Desc" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Creation-time order; provider default when omitted." }, "statuses": { "anyOf": [ { "items": { "enum": [ "Processing", "Active", "Failed" ], "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Only assets with these statuses." } }, "type": "object" } }, "additionalProperties": false, "properties": { "input": { "$ref": "#/$defs/AssetListInput" } }, "required": [ "input" ], "type": "object"}Output schema, including nested definitions
{ "$defs": { "Asset": { "description": "One trusted media file in the private asset library.", "properties": { "asset_id": { "description": "Asset ID (e.g. 'asset-20260318035710-kctzf').", "title": "Asset Id", "type": "string" }, "asset_type": { "default": "", "description": "Asset type: 'Image', 'Video', or 'Audio'.", "title": "Asset Type", "type": "string" }, "asset_uri": { "description": "Durable reference for generation requests: 'asset://<asset_id>'. Use it as an image/video/audio URL in Seedance tools. In prompts refer to it by position ('Image 1', 'Video 1'), never by ID.", "title": "Asset Uri", "type": "string" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Creation time (ISO-8601, provider value).", "title": "Created At" }, "group_id": { "default": "", "description": "Asset group the asset belongs to.", "title": "Group Id", "type": "string" }, "last_inference_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "When the asset was last used to submit a generation task. Absent means no recorded use since 2026-07-24, not necessarily never used.", "title": "Last Inference Time" }, "moderation_strategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Content pre-filter strategy: 'Default' or 'Skip'.", "title": "Moderation Strategy" }, "name": { "default": "", "description": "Asset name (search only; not seen by the model).", "title": "Name", "type": "string" }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Temporary presigned download URL for the stored file (expires after about 12 hours). For viewing only; always use asset_uri in generation requests.", "title": "Preview Url" }, "project_name": { "default": "", "description": "ModelArk project that owns the asset.", "title": "Project Name", "type": "string" }, "status": { "default": "", "description": "Processing status: 'Processing' (queued/preprocessing, not usable yet), 'Active' (usable in generation), or 'Failed' (preprocessing or review failed).", "title": "Status", "type": "string" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Last update time (ISO-8601, provider value).", "title": "Updated At" } }, "required": [ "asset_id", "asset_uri" ], "title": "Asset", "type": "object" }, "AssetLookupError": { "description": "An asset or group ID that could not be read.", "properties": { "code": { "description": "Provider error code (e.g. NotFound.Asset).", "title": "Code", "type": "string" }, "id": { "description": "The asset or group ID that failed.", "title": "Id", "type": "string" }, "message": { "description": "Human-readable reason.", "title": "Message", "type": "string" } }, "required": [ "id", "code", "message" ], "title": "AssetLookupError", "type": "object" } }, "description": "Output for ``ark_asset_list``.", "properties": { "assets": { "description": "Assets on this page.", "items": { "$ref": "#/$defs/Asset" }, "title": "Assets", "type": "array" }, "errors": { "description": "asset_ids that could not be read.", "items": { "$ref": "#/$defs/AssetLookupError" }, "title": "Errors", "type": "array" }, "next_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pass as next_token for the next page; null on the last page.", "title": "Next Token" } }, "required": [ "assets" ], "title": "AssetPage", "type": "object"}Troubleshooting
Section titled “Troubleshooting”- Missing tool: check provider credentials and feature flags, then restart the connection.
- Invalid arguments: keep the correct wrapper and follow current model limits from discovery. A valid schema alone does not prove the chosen model supports the combination.
- A job completes with an error: inspect the original tool result, not only the outer job status. Never automatically resubmit potentially billable work.
- Local output writes from jobs require server-configured
OUTPUT_ROOTS; HTTP cannot write to a client’s local disk.
See configuration, background execution, and artifact delivery.