Falai/assets

@webframp/falai/assetsv2026.10.21.1· Apache-2.0· 5d agoBEHAVIORS

01README

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

02Release Notes

2026.10.21.1

Changed: The README, the apiToken description and the missing-key error now direct you to store the fal.ai API key in a vault (swamp vault put falai API_KEY) and wire it with --global-arg 'apiToken=${{ vault.get("falai", "API_KEY") }}'. The README previously showed --global-arg apiToken=FAL_API_KEY, which invited passing the key as a literal. The FAL_KEY environment variable is still read as a fallback, but it is not redacted and is not recommended.

No method behavior changed. Stored resources need no migration.

03Behaviors1

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

Global Arguments

Argument	Type	Required	Description
apiToken?	string	no	fal.ai API key. Wire it with ${{ vault.get("falai", "API_KEY") }}; never pass the literal value. The FAL_KEY environment variable is read as a fallback, but it is not redacted and is not recommended.

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_entities(limit?: number, offset?: number, types?: array)

List asset entities

Argument	Type	Required	Description
limit?	number	no	Maximum number of entities to return
offset?	number	no	Number of entities to skip
types?	array	no	Entity types to include, comma-separated. Omit to list all types.

fn create_asset_entity(type: enum, name: string, handle?: string, description?: string, reference_images: array, cover_image_url?: string)

Create asset entity

Argument	Type	Required	Description
type	enum	yes	Smart entity type
name	string	yes	Entity display name
handle?	string	no	Optional @mention handle. Defaults from the name; must be unique across all e...
description?	string	no	Visual description. Required and non-empty for characters; optional for other...
reference_images	array	yes	Defining reference images. Use saved asset IDs, request IDs, vector IDs, or f...
cover_image_url?	string	no	Cover image URL. Must be one of the entity's reference images.

fn get_asset_entity(entity_id: string)

Get asset entity

Argument	Type	Required	Description
entity_id	string	yes	Smart entity ID

fn update_asset_entity(entity_id: string, name?: string, handle?: string, description?: string, reference_images?: array, cover_image_url?: string)

Update asset entity

Argument	Type	Required	Description
entity_id	string	yes	Smart entity ID
name?	string	no	Entity display name
handle?	string	no	Replacement @mention handle. Character handles cannot be changed.
description?	string	no	Replacement visual description; null clears it for non-character entities.
reference_images?	array	no	Replace the defining references with these saved asset IDs, request IDs, vect...
cover_image_url?	string	no	Replacement cover image URL from the entity's reference images; null clears t...

fn delete_asset_entity(entity_id: string)

Delete asset entity

Argument	Type	Required	Description
entity_id	string	yes	Smart entity 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_entities(infinite)— List asset entities

asset_entity(infinite)— Create asset entity

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

04Previous Versions6

2026.10.14.2Apache-2.0Oct 14, 2026

2026.10.14.2

Fixed: favorite_asset_collection and unfavorite_asset_collection now write one resource per collection_id, and favorite_asset_character and unfavorite_asset_character one per character_id, instead of overwriting a single -current instance.

Upgrade note: No methods or arguments changed. Data previously stored under the old -current instance names is not moved; re-run the action to write the new instance.

2026.10.14.1Apache-2.0(was none)Oct 14, 2026

2026.10.14.1

Fixed: Methods that write a singleton resource failed on current swamp with Data name 'latest' is reserved for internal use.

Changed: Singleton get and action methods now write their data under favorite_asset_character-current, favorite_asset_collection-current, unfavorite_asset_character-current, unfavorite_asset_collection-current instead of latest. Anything that read data.latest("<model>", "latest") or queried name == "latest" must use the new name.

Upgrade note: Data previously stored under latest is not migrated; re-run the method to populate the new name. No attribute schemas changed.

Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.

2026.09.18.1Sep 20, 2026

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.17.2Sep 17, 2026

2026.09.17.2

Add smart entity CRUD methods (list/create/get/update/delete_asset_entity) reflecting fal.ai's new /assets/entities endpoints. Also: response schema fields are now generated as optional/nullable-optional regardless of the spec's required list, so reading a resource stored under an older model version no longer throws when the live API has since added required fields; list methods with a documented default page size now use it to detect truncation when the caller omits limit.

Modified 1 behaviors

2026.09.15.1Sep 15, 2026

2026.09.15.1

Changed: Bump zod 4.4.3 → 4.6.5

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.

2026.09.10.4Sep 10, 2026

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.

05Stats

100 / 100

Downloads

Archive size

26.6 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
License2/2earned
Verified public repository2/2earned

Repository

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

06Platforms

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

07Labels

#falai #assets #media