---
title: "Create asset entity"
method: POST
path: "/assets/entities"
tags: ["Assets"]
---

# Create asset entity

`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`

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](https://fal.ai/docs/documentation/model-apis/authentication/key-based#permissions).

## Headers

- `Idempotency-Key` string: Optional idempotency key for safe request retries

## Request body

- object
  - `type` 'character' | 'prop' | 'environment' | 'style' | 'scene', required: Smart entity type
  - `name` string, required: Entity display name
  - `handle` string: Optional @mention handle. Defaults from the name; must be unique across all entity types in the account.
  - `description` string, nullable: Visual description. Required and non-empty for characters; optional for other types.
  - `reference_images` string[], required: Defining reference images. Use saved asset IDs, request IDs, vector IDs, or fal-hosted image URLs.
  - `cover_image_url` string, uri, nullable: Cover image URL. Must be one of the entity's reference images.

## Response `201`

Entity created

- object
  - `entity` object, required: Saved smart entity
    - `id` string, required: Smart entity ID
    - `type` 'character' | 'prop' | 'environment' | 'style' | 'scene', required: Smart entity type
    - `name` string, required: Entity display name
    - `handle` string, required: Resolved @mention handle, without the leading @
    - `description` string, nullable, required: Entity visual description
    - `cover_image_url` string, nullable, required: Entity cover image URL
    - `reference_images` string[], required: Defining reference image URLs
    - `is_favorited` boolean, required: Whether the entity is favorited
    - `created_at` string, date-time, required: Creation time in UTC
    - `updated_at` string, date-time, required: Last update time in UTC

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `409`: Invalid request parameters
- `422`: Invalid request parameters
- `429`: Rate limit exceeded
- `500`: Internal server error
- `502`: Upstream asset service error

## Changes

- **2026-09-13** `51d8e07444e1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fal/apis/platform-apis/changes/assets/entities/post.md)

---

[API](https://skmtc.dev/fal/apis/platform-apis.md) - [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/fal/apis/platform-apis/revisions/3b3b61bedf06?raw)