FAfal
Assets

Update asset entity

Changed on

Update a saved entity without recreating it. Omitted fields stay unchanged; reference_images replaces the defining reference set. Entity types cannot be changed. Character handles cannot be changed and character descriptions cannot be cleared. Other entity handles must remain unique within the account.

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

patch/assets/entities/{entity_id}

Request

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

Path parameters

entity_idstring required

Smart entity ID

Headers

Idempotency-Keystring

Optional idempotency key for safe request retries

Example:550e8400-e29b-41d4-a716-446655440000

Request body

namestring

Entity display name

handlestring

Replacement @mention handle. Character handles cannot be changed.

descriptionstring nullable

Replacement visual description; null clears it for non-character entities.

reference_imagesstring[]

Replace the defining references with these saved asset IDs, request IDs, vector IDs, or fal-hosted image URLs.

cover_image_urlstring uri nullable

Replacement cover image URL from the entity's reference images; null clears the explicit cover.

Response

Entity updated

Example response

{
  "entity": {
    "type": "character"
  }
}

Changes