Entity

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/videogen-io/json-schema/videogen-io-entity-schema.json",
  "title": "Entity",
  "description": "A reusable actor, product, visual style, or slideshow theme. Attach its reference images to workflows for consistent characters, looks, and slide designs.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/videogen-io-entities-api-openapi.yml#/components/schemas/Entity",
  "type": "object",
  "required": [
    "entityId",
    "entityType",
    "name",
    "description",
    "references",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "entityId": {
      "type": "string",
      "description": "The entity id (e.g. `vg_enti_...`)."
    },
    "entityType": {
      "type": "string",
      "enum": [
        "ACTOR",
        "PRODUCT",
        "VISUAL_STYLE",
        "SLIDESHOW_THEME"
      ],
      "description": "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."
    },
    "name": {
      "type": "string",
      "description": "Display name."
    },
    "description": {
      "type": "string",
      "description": "Optional description. Empty string when not set."
    },
    "actorConfig": {
      "anyOf": [
        {
          "$ref": "#/$defs/EntityActorConfig"
        },
        {
          "type": "null"
        }
      ],
      "description": "Voice and presenter summary for ACTOR entities. Null for non-ACTOR entities."
    },
    "references": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EntityReference"
      },
      "description": "Reference images attached to the entity."
    },
    "createdAt": {
      "type": "integer",
      "description": "Seconds since epoch (Unix timestamp) when the entity was created."
    },
    "updatedAt": {
      "type": "integer",
      "description": "Seconds since epoch (Unix timestamp) when the entity was last updated."
    },
    "isBuiltIn": {
      "type": "boolean",
      "description": "When true, this is a VideoGen catalog entity. Built-in entities cannot be updated, archived, or have references added or removed."
    }
  },
  "$defs": {
    "EntityActorConfig": {
      "type": "object",
      "description": "Read-only voice and avatar summary for an ACTOR entity. Always null for non-ACTOR entities.",
      "required": [
        "hasVoice",
        "hasAvatarPresenter"
      ],
      "properties": {
        "voiceDisplayName": {
          "type": [
            "string",
            "null"
          ],
          "description": "Display name of the actor's voice when one is configured. Null otherwise."
        },
        "hasVoice": {
          "type": "boolean",
          "description": "True when the actor has a configured voice."
        },
        "hasAvatarPresenter": {
          "type": "boolean",
          "description": "True when the actor has a built-in presenter or image reference that can be used with `actorEntityId` for avatar generation."
        }
      }
    },
    "EntityReference": {
      "type": "object",
      "description": "A file attached to an entity as a reference image.",
      "required": [
        "fileId",
        "description",
        "isDefault"
      ],
      "properties": {
        "fileId": {
          "type": "string",
          "description": "The reference image file id (e.g. `vg_file_...`). Hydrate it via `GET /v1/files/{fileId}` to fetch a viewable URL."
        },
        "description": {
          "type": "string",
          "description": "Optional description of the reference. Empty string when not set."
        },
        "isDefault": {
          "type": "boolean",
          "description": "When true, this is the entity's primary reference (used for its thumbnail)."
        }
      }
    }
  }
}