FAfal
Assets

Browse assets

Changed on

Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.

Required permissions: assets:read. Key presets that include them: API, SERVERLESS, READONLY, FULL. See key permissions.

get/assets

Request

  • Base URL
    https://api.fal.ai/v1
  • URL
    https://api.fal.ai/v1/assets
  • Auth
    API key in header Authorization

Query parameters

limitinteger

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Example:50
cursorstring

Pagination cursor from previous response. Encodes the page number.

Example:Mg==
qstring

Text query for hybrid semantic search

Example:cinematic portrait
search_image_urlstring uri

fal-hosted image URL to use for semantic image search

Example:https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png
search_video_urlstring uri

fal-hosted video URL to use for semantic video search

Example:https://fal.media/files/example.mp4
media_typestring[] nullable

Filter by one or more media types

[
  "image",
  "video"
]
sourcestring[] nullable

Filter by one or more indexed sources

[
  "upload",
  "response"
]
section'all-media' | 'uploads' | 'favorites' | 'generated'

Asset library section to browse

Example:all-media
collection_idstring

Collection scope to browse

Example:d8b6elcregj72v34jr8g
character_identifierstring[] nullable

Character identifiers to use as @mention semantic filters

[
  "alice"
]
tag_idstring[] nullable

Tag IDs to filter by

[
  "d9k7q2m4n6p8r1s3t5uv"
]
tag_mode'any' | 'all'

Whether tag filters match any tag or all tags

Example:any

Response

Successfully browsed assets

next_cursorstring nullable required

Cursor for the next page

has_moreboolean required

Whether more results are available

total_countnumber nullable required

Exact total when available; null when unavailable

scope_truncatedboolean required

True when the requested scope (favorites, tags, or collection membership) exceeded the maximum number of assets a single search can cover, so results were drawn from a partial slice of it and some matches are missing. Narrow the scope for complete results. total_count remains accurate for the results that were returned.

Example response

{
  "assets": [
    {
      "asset_id": "d8b6elcregj72v34jr8g",
      "vector_id": "b1a2b4a5-cb89-51dc-a108-6dbfd8e742fc",
      "request_id": "019e6d0a-e5be-7b82-b329-35ae64296902",
      "url": "https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png",
      "title": "Portrait",
      "endpoint": "fal-ai/flux/dev",
      "created_at": "2026-05-23T20:00:00.000Z",
      "source": "upload",
      "prompt": "cinematic portrait",
      "width": 1024,
      "height": 1024,
      "content_type": "image/png",
      "collection_ids": [
        "d8b6elcregj72v34jr8g"
      ],
      "tags": [
        {
          "id": "d9k7q2m4n6p8r1s3t5uv",
          "name": "moodboard",
          "created_at": "2026-05-23T20:00:00.000Z"
        }
      ],
      "similarity": 0.92
    }
  ]
}

Changes

  • 479db2f9dcd6Revision changes
    • info

      the endpoint scheme security readonlyApiKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API