{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/videogen-io/json-schema/videogen-io-list-entities-response-schema.json",
  "title": "ListEntitiesResponse",
  "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/ListEntitiesResponse",
  "type": "object",
  "required": [
    "entities",
    "hasMore",
    "nextCursor"
  ],
  "properties": {
    "entities": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Entity"
      }
    },
    "hasMore": {
      "type": "boolean",
      "description": "When true, there are more entities available. Pass `nextCursor` as the `cursor` query param to fetch the next page."
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Opaque cursor to fetch the next page. `null` when `hasMore` is false."
    }
  },
  "$defs": {
    "Entity": {
      "type": "object",
      "description": "A reusable actor, product, visual style, or slideshow theme. Attach its reference images to workflows for consistent characters, looks, and slide designs.",
      "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."
        }
      }
    },
    "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)."
        }
      }
    }
  }
}