Skip to main content
The Assets endpoints are part of the fal Platform API, at https://api.fal.ai/v1/assets.

​
Before you start

Enable Assets for the account you want to use and create an API key. Set FAL_KEY in your environment and send it as Authorization: Key .... Keep the key on your server, not in browser code. Library access and which generation sources enter the library are separate concerns. If API generations are missing, check the account configuration. See Access and availability.
Omit q for ordinary browsing. For example search, send search_image_url or search_video_url with a fal-hosted media URL. Use one search input at a time. You can also filter by section, source, collection_id, tag_id, tag_mode, and character_identifier. Character-handle filtering is based on associations with that character. It is not automatic visual recognition. The response contains assets, next_cursor, has_more, total_count, and scope_truncated. To continue, send next_cursor as cursor with the same query and filters. Treat cursors as opaque. A null total means a total is unavailable. If scope_truncated is true, narrow the scope rather than treating the response as a complete set. See Browse assets for parameters and response fields.

​
Register an upload

First upload your file to fal storage. Then register the returned URL with Assets. Replace the example URL below with your own fal-hosted URL:
This endpoint registers a file already hosted on fal. It does not accept multipart file data or arbitrary external URLs. Supported types are image, video, audio, and 3d. You can provide a manual collection_id and tag_ids during registration. See Upload asset.

​
Organize an asset

Create a manual collection:
Use the returned collection ID and a vector_id returned by browse or upload. Set COLLECTION_ID and VECTOR_ID to those values:
The collection API supports listing, editing, moving, reading hierarchy, adding and removing members, and deletion. Smart collections use a filters object at creation and follow the smart-collection rules. Use the tag endpoints and favorite endpoint for labels and favorite state. Setting an asset’s full tag set replaces that set. Assigning one tag adds only that association.

​
Characters

The public character endpoints support creating, reading, updating, favoriting, and deleting characters. A character needs a description and one to twenty reference images. See Create asset character for the reference format. The browser supports all five smart entity types. The public Assets API currently exposes character CRUD, not equivalent CRUD endpoints for props, environments, styles, and scenes.

​
Generation ancestry

Set ASSET_ID to the catalog asset_id returned by Assets to retrieve recorded ancestry. This is separate from the vector_id used in the collection example:
The response describes recorded inputs, generation requests, and referenced entities. Deleted or expired ancestors can remain as unavailable references in the history. Their presence does not make their media downloadable.

​
API boundaries

The public Assets endpoints do not expose collection-share management or the browser’s asset-delete operation. To delete a completed generation’s request payloads and CDN output files, use Delete request payloads. See Retention and deletion for the difference.