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

# Get entity

GET https://api.videogen.io/v1/entities/{entityId}

Retrieve a single entity by its id, including its reference images. Built-in catalog entities are included.

Reference: https://docs.videogen.io/rest-api-reference/entities/get-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

### Path parameters

- `entityId` (string, required) — The entity id (e.g. `vg_enti_...`).

## Response

### 200

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

**Response**

```json
{
  "entityId": "vg_enti_a1b2c3d4e5f6",
  "entityType": "ACTOR",
  "name": "Maya the host",
  "description": "Friendly on-camera host for product explainers.",
  "references": [
    {
      "fileId": "vg_file_obLD1OX2eJCrEs0071Z4kA",
      "description": "Front-facing headshot, neutral background.",
      "isDefault": true
    }
  ],
  "createdAt": 1779537600,
  "updatedAt": 1779537870,
  "actorConfig": {
    "hasVoice": true,
    "hasAvatarPresenter": true,
    "voiceDisplayName": "Matilda"
  },
  "isBuiltIn": false
}
```

**SDK Code**

```python
import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```