Falai/assets

@webframp/falai/assetsv2026.09.10.4· 1d agoMODELS

01README

fal.ai Assets — media library, characters, collections, tags, uploads, favorites

02Release Notes

2026.09.10.4

Fixed:

Resource instance names for get/update methods with two or more path parameters (e.g. get_app_queue_info(owner, name), get_workflow(username, workflow_name)) were built by joining raw values with "_". Two distinct owner/name pairs that split differently around an underscore (e.g. "john"/"doe_app" and "john_doe"/"app") produced the identical instance name and collided. Multi-param instance names are now derived from a hash of the JSON-encoded parameter tuple, which delimits each part unambiguously.

Upgrade note: No schema changes. All fixes are internal to method execution; existing stored resources are unaffected.

03Models1

@webframp/falai/assetsv2026.09.10.4falai/assets.ts

Global Arguments

Argument	Type	Required	Description
apiToken?	string	no	fal.ai API key; overrides the FAL_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn list_assets(limit?: number, cursor?: string, q?: string, search_image_url?: string, search_video_url?: string, media_type?: array, source?: array, section?: enum, collection_id?: string, character_identifier?: array, tag_id?: array, tag_mode?: enum)

Browse assets

Argument	Type	Required	Description
limit?	number	no	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
cursor?	string	no	Pagination cursor from previous response. Encodes the page number.
q?	string	no	Text query for hybrid semantic search
search_image_url?	string	no	fal-hosted image URL to use for semantic image search
search_video_url?	string	no	fal-hosted video URL to use for semantic video search
media_type?	array	no	Filter by one or more media types
source?	array	no	Filter by one or more indexed sources
section?	enum	no	Asset library section to browse
collection_id?	string	no	Collection scope to browse
character_identifier?	array	no	Character identifiers to use as @mention semantic filters
tag_id?	array	no	Tag IDs to filter by
tag_mode?	enum	no	Whether tag filters match any tag or all tags

fn list_asset_collections(limit?: number, offset?: number)

List asset collections

Argument	Type	Required	Description
limit?	number	no	Maximum number of collections to return
offset?	number	no	Number of collections to skip

fn create_asset_collection(name: string, description?: string, icon?: string, color?: string, cover_image_url?: string, parent_collection_id?: string, filters?: unknown)

Create asset collection

Argument	Type	Required	Description
name	string	yes	Collection display name
description?	string	no	Optional collection description
icon?	string	no	Optional collection icon
color?	string	no	Optional collection color
cover_image_url?	string	no	Optional fal-hosted cover image URL for the collection
parent_collection_id?	string	no
filters?	unknown	no	Assets filter DSL

fn get_asset_collection(collection_id: string)

Get asset collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID

fn update_asset_collection(collection_id: string, name?: string, description?: string, icon?: string, color?: string, cover_image_url?: string, filters?: unknown)

Update asset collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID
name?	string	no	Collection display name
description?	string	no	Optional collection description
icon?	string	no	Optional collection icon
color?	string	no	Optional collection color
cover_image_url?	string	no	Optional fal-hosted cover image URL for the collection
filters?	unknown	no	Assets filter DSL

fn delete_asset_collection(collection_id: string)

Delete asset collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID

fn get_asset_collection_hierarchy(collection_id: string)

Get asset collection hierarchy

Argument	Type	Required	Description
collection_id	string	yes	Collection ID

fn favorite_asset_collection(collection_id: string)

Favorite asset collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID

fn unfavorite_asset_collection(collection_id: string)

Unfavorite asset collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID

fn move_asset_collection(collection_id: string, parent_collection_id?: string)

Move asset collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID
parent_collection_id?	string	no	Parent collection ID to move this collection under, or null to move it to the...

fn list_asset_collection_assets(collection_id: string, limit?: number, cursor?: string, q?: string, search_image_url?: string, search_video_url?: string, media_type?: array, source?: array, section?: enum, character_identifier?: array, tag_id?: array, tag_mode?: enum)

Browse assets in a collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID
limit?	number	no	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
cursor?	string	no	Pagination cursor from previous response. Encodes the page number.
q?	string	no	Text query for hybrid semantic search
search_image_url?	string	no	fal-hosted image URL to use for semantic image search
search_video_url?	string	no	fal-hosted video URL to use for semantic video search
media_type?	array	no	Filter by one or more media types
source?	array	no	Filter by one or more indexed sources
section?	enum	no	Asset library section to browse
character_identifier?	array	no	Character identifiers to use as @mention semantic filters
tag_id?	array	no	Tag IDs to filter by
tag_mode?	enum	no	Whether tag filters match any tag or all tags

fn add_asset_to_collection(collection_id: string, asset_id?: string, request_id?: string, vector_id?: string)

Add asset to collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID
asset_id?	string	no	Asset ID (canonical catalog identity)
request_id?	string	no	Request ID to save as an asset before mutating
vector_id?	string	no	Vector ID to save as an asset before mutating. Prefer asset_id

fn remove_asset_from_collection(collection_id: string, asset_id?: string, request_id?: string, vector_id?: string)

Remove asset from collection

Argument	Type	Required	Description
collection_id	string	yes	Collection ID
asset_id?	string	no	Asset ID (canonical catalog identity)
request_id?	string	no	Request ID to save as an asset before mutating
vector_id?	string	no	Vector ID to save as an asset before mutating. Prefer asset_id

fn list_asset_characters(limit?: number, offset?: number)

List asset characters

Argument	Type	Required	Description
limit?	number	no	Maximum number of collections to return
offset?	number	no	Number of collections to skip

fn create_asset_character(name: string, identifier?: string, description: string, reference_images: array, cover_image_url?: string)

Create asset character

Argument	Type	Required	Description
name	string	yes	Character display name
identifier?	string	no	Optional @mention identifier for the character
description	string	yes	Text description used for character semantic matching
reference_images	array	yes	Reference images for the character. Prefer vector IDs or request IDs for exis...
cover_image_url?	string	no	Optional fal-hosted cover image URL for the character

fn get_asset_character(character_id: string)

Get asset character

Argument	Type	Required	Description
character_id	string	yes	Character collection ID

fn update_asset_character(character_id: string, name?: string, description?: string, reference_images?: array, cover_image_url?: string)

Update asset character

Argument	Type	Required	Description
character_id	string	yes	Character collection ID
name?	string	no	Character display name
description?	string	no	Text description used for character semantic matching
reference_images?	array	no	Reference images for the character. Prefer vector IDs or request IDs for exis...
cover_image_url?	string	no	Optional fal-hosted cover image URL for the character

fn delete_asset_character(character_id: string)

Delete asset character

Argument	Type	Required	Description
character_id	string	yes	Character collection ID

fn favorite_asset_character(character_id: string)

Favorite asset character

Argument	Type	Required	Description
character_id	string	yes	Character collection ID

fn unfavorite_asset_character(character_id: string)

Unfavorite asset character

Argument	Type	Required	Description
character_id	string	yes	Character collection ID

fn list_asset_tags()

List asset tags

fn create_asset_tag(name: string)

Create asset tag

Argument	Type	Required	Description
name	string	yes	Tag name

fn set_asset_tags_for_asset(asset_id?: string, request_id?: string, vector_id?: string, tag_ids: array)

Set tags for an asset

Argument	Type	Required	Description
asset_id?	string	no	Asset ID (canonical catalog identity)
request_id?	string	no	Request ID to save as an asset before mutating
vector_id?	string	no	Vector ID to save as an asset before mutating. Prefer asset_id
tag_ids	array	yes	Full replacement set of tag IDs

fn update_asset_tag(tag_id: string, name?: string)

Update asset tag

Argument	Type	Required	Description
tag_id	string	yes	Tag ID
name?	string	no	Tag name

fn delete_asset_tag(tag_id: string)

Delete asset tag

Argument	Type	Required	Description
tag_id	string	yes	Tag ID

fn upload_asset(url: string, type: enum, prompt?: string, collection_id?: string, favorite?: boolean, tag_ids?: array)

Upload asset

Argument	Type	Required	Description
url	string	yes	fal-hosted media URL to ingest into the asset library
type	enum	yes	Media type for the uploaded asset
prompt?	string	no	Optional caller-provided caption or description to index with the uploaded asset
collection_id?	string	no	Optional manual collection ID to add the uploaded asset to
favorite?	boolean	no	Whether to favorite the uploaded asset immediately
tag_ids?	array	no	Tag IDs to assign to the uploaded asset

fn get_asset(asset_id: string)

Get asset

Argument	Type	Required	Description
asset_id	string	yes	Asset ID. A vector ID is also accepted

fn get_asset_lineage(asset_id: string, depth?: number)

Get asset lineage

Argument	Type	Required	Description
asset_id	string	yes	Asset ID
depth?	number	no	Maximum traversal depth (levels of derivation edges)

fn favorite_asset(asset_id?: string, request_id?: string, vector_id?: string)

Favorite asset

Argument	Type	Required	Description
asset_id?	string	no	Asset ID (canonical catalog identity)
request_id?	string	no	Request ID to save as an asset before mutating
vector_id?	string	no	Vector ID to save as an asset before mutating. Prefer asset_id

fn unfavorite_asset(asset_id?: string, request_id?: string, vector_id?: string)

Unfavorite asset

Argument	Type	Required	Description
asset_id?	string	no	Asset ID (canonical catalog identity)
request_id?	string	no	Request ID to save as an asset before mutating
vector_id?	string	no	Vector ID to save as an asset before mutating. Prefer asset_id

fn list_asset_tags_for_asset(asset_id: string)

List tags for an asset

Argument	Type	Required	Description
asset_id	string	yes	Asset ID. A vector ID is also accepted

fn assign_asset_tag(tag_id: string, asset_id?: string, request_id?: string, vector_id?: string)

Assign tag to asset

Argument	Type	Required	Description
tag_id	string	yes	Tag ID
asset_id?	string	no	Asset ID (canonical catalog identity)
request_id?	string	no	Request ID to save as an asset before mutating
vector_id?	string	no	Vector ID to save as an asset before mutating. Prefer asset_id

fn unassign_asset_tag(tag_id: string, asset_id?: string, request_id?: string, vector_id?: string)

Unassign tag from asset

Argument	Type	Required	Description
tag_id	string	yes	Tag ID
asset_id?	string	no	Asset ID (canonical catalog identity)
request_id?	string	no	Request ID to save as an asset before mutating
vector_id?	string	no	Vector ID to save as an asset before mutating. Prefer asset_id

Resources

assets(infinite)— Browse assets

asset_collections(infinite)— List asset collections

asset_collection(infinite)— Create asset collection

get_asset_collection_hierarchy(infinite)— Get asset collection hierarchy

favorite_asset_collection(infinite)— Favorite asset collection

unfavorite_asset_collection(infinite)— Unfavorite asset collection

move_asset_collection(infinite)— Move asset collection

asset_collection_assets(infinite)— Browse assets in a collection

add_asset_to_collection(infinite)— Add asset to collection

asset_characters(infinite)— List asset characters

asset_character(infinite)— Create asset character

favorite_asset_character(infinite)— Favorite asset character

unfavorite_asset_character(infinite)— Unfavorite asset character

asset_tags(infinite)— List asset tags

asset_tag(infinite)— Create asset tag

set_asset_tags_for_asset(infinite)— Set tags for an asset

upload_asset(infinite)— Upload asset

asset(infinite)— Get asset

asset_lineage(infinite)— Get asset lineage

favorite_asset(infinite)— Favorite asset

unfavorite_asset(infinite)— Unfavorite asset

asset_tags_for_asset(infinite)— List tags for an asset

assign_asset_tag(infinite)— Assign tag to asset

04Stats

100 / 100

Downloads

Archive size

27.9 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/webframp/swamp-extensions

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

06Labels

#falai #assets #media