Search ready assets
Call GET /api/v1/assets?query=ranger&kind=image or search_assets. Results are limited to ready, untrashed assets owned by the authenticated account. Optional project, kind and cursor filters help narrow a large library. Use nextCursor to read another page.
Reuse an image
Copy assetId from an upload confirmation, search result or completed task. For animation, direction generation and extraction, put it in inputAssetId. For props or NPCs use styleReferenceAssetId; character, map and tileset style objects use referenceAssetIds.
For an existing character, call list_characters and use currentDesignFileId as the input or download file ID. currentDesignAssetId is a separate character asset binding used by characterTarget.designAssetId; it cannot be downloaded as a file. A null currentDesignFileId means the current design has no ready, untrashed file available. Inspect the image before reuse: a design sheet may contain multiple poses rather than one full-body character.
The server validates ownership, readiness and PNG/JPEG/WebP format and reads dimensions from the stored file metadata or image. A URL alone is not proof of ownership. Temporary download URLs, provider IDs and local file paths are not valid asset IDs.
Example workflow
Create a character → wait for its ready full-body image → animate that image → download the animation. For an environment, create a map → reuse the image in Scene asset extraction → inspect and download individual objects.
When reuse fails
Confirm incomplete uploads first. Restore a trashed asset through the workspace if appropriate. Choose an individual supported image instead of a ZIP, audio file or video. If a task reports completion without the expected kind of file, inspect its available assets rather than passing an unrelated ID.