FAfal
Assets

Create asset entity

Changed on

Create a reusable character, prop, environment, style, or scene in fal Assets. The entity is available to @mention in the UI and agent. The handle defaults from the name and must be unique across all entity types in the account. Characters require a description. Reference images accept saved asset IDs, request IDs, vector IDs, or fal-hosted image URLs. Existing character endpoints remain supported.

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

post/assets/entities

Request

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

Headers

Idempotency-Keystring

Optional idempotency key for safe request retries

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

Request body

type'character' | 'prop' | 'environment' | 'style' | 'scene' required

Smart entity type

namestring required

Entity display name

handlestring

Optional @mention handle. Defaults from the name; must be unique across all entity types in the account.

descriptionstring nullable

Visual description. Required and non-empty for characters; optional for other types.

reference_imagesstring[] required

Defining reference images. Use saved asset IDs, request IDs, vector IDs, or fal-hosted image URLs.

cover_image_urlstring uri nullable

Cover image URL. Must be one of the entity's reference images.

Example request

{
  "type": "character"
}

Response

Entity created

Example response

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

Changes