> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# Create entity

POST https://api.videogen.io/v1/entities
Content-Type: application/json

Create a new actor or visual style. Attach reference images with `POST /v1/entities/{entityId}/references`.

Reference: https://docs.videogen.io/rest-api-reference/entities/create-entity

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Body (application/json)

This endpoint expects a CreateEntityRequest.

- `entityType` (enum, required) — ACTOR features a consistent character; PRODUCT features a consistent product or object; VISUAL_STYLE guides the look of generated images; SLIDESHOW_THEME is a shared slide design system (fonts, colors, layout) applied to every slide of a slideshow-to-video deck.
  - Allowed values: `ACTOR`, `PRODUCT`, `VISUAL_STYLE`, `SLIDESHOW_THEME`
- `name` (string, required) — Display name.
- `description` (string, optional) — Optional description.

## Response

### 200

The created entity

- `entityId` (string, required) — The entity id (e.g. `vg_enti_...`).
- `entityType` (enum, required) — ACTOR features a consistent character; PRODUCT features a consistent product or object; VISUAL_STYLE guides the look of generated images; SLIDESHOW_THEME is a shared slide design system (fonts, colors, layout) applied to every slide of a slideshow-to-video deck.
  - Allowed values: `ACTOR`, `PRODUCT`, `VISUAL_STYLE`, `SLIDESHOW_THEME`
- `name` (string, required) — Display name.
- `description` (string, required) — Optional description. Empty string when not set.
- `references` (list of EntityReference, required) — Reference images attached to the entity.
- `createdAt` (integer, required) — Seconds since epoch (Unix timestamp) when the entity was created.
- `updatedAt` (integer, required) — Seconds since epoch (Unix timestamp) when the entity was last updated.
- `actorConfig` (EntityActorConfig, optional, nullable) — Voice and presenter summary for ACTOR entities. Null for non-ACTOR entities.
- `isBuiltIn` (boolean, optional) — When true, this is a VideoGen catalog entity. Built-in entities cannot be updated, archived, or have references added or removed.

## Types

### EntityReference

A file attached to an entity as a reference image.

- `fileId` (string, required) — The reference image file id (e.g. `vg_file_...`). Hydrate it via `GET /v1/files/{fileId}` to fetch a viewable URL.
- `description` (string, required) — Optional description of the reference. Empty string when not set.
- `isDefault` (boolean, required) — When true, this is the entity's primary reference (used for its thumbnail).

### EntityActorConfig

Read-only voice and avatar summary for an ACTOR entity. Always null for non-ACTOR entities.

- `hasVoice` (boolean, required) — True when the actor has a configured voice.
- `hasAvatarPresenter` (boolean, required) — True when the actor has a built-in presenter or image reference that can be used with `actorEntityId` for avatar generation.
- `voiceDisplayName` (string, optional, nullable) — Display name of the actor's voice when one is configured. Null otherwise.

## Examples

**Request**

```json
{
  "entityType": "VISUAL_STYLE",
  "name": "Pastel watercolor",
  "description": "Soft pastel watercolor look for lifestyle clips."
}
```

**Response**

```json
{
  "entityId": "vg_enti_f6e5d4c3b2a1",
  "entityType": "VISUAL_STYLE",
  "name": "Pastel watercolor",
  "description": "Soft pastel watercolor look for lifestyle clips.",
  "references": [],
  "createdAt": 1779268500,
  "updatedAt": 1779268500,
  "actorConfig": null,
  "isBuiltIn": false
}
```

**SDK Code**

```python
import requests

url = "https://api.videogen.io/v1/entities"

payload = {
    "entityType": "VISUAL_STYLE",
    "name": "Pastel watercolor",
    "description": "Soft pastel watercolor look for lifestyle clips."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```