VideoGen API

curl -X POST https://api.videogen.io/v1/entities/vg_enti_a1b2c3d4e5f6/references \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "fileId": "vg_file_mot8bV5POiscDeHyo7TF1g",
  "description": "Side profile, studio lighting.",
  "isDefault": false
}'

{
  "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
    },
    {
      "fileId": "vg_file_mot8bV5POiscDeHyo7TF1g",
      "description": "Side profile, studio lighting.",
      "isDefault": false
    }
  ],
  "createdAt": 1779537600,
  "updatedAt": 1779546120,
  "actorConfig": {
    "hasVoice": true,
    "hasAvatarPresenter": true,
    "voiceDisplayName": "Matilda"
  },
  "isBuiltIn": false
}

Attach an image file as a reference for the entity. Upload the image first via POST /v1/files/upload. Returns the updated entity. Built-in entities (isBuiltIn: true) cannot have references added.

Authentication

AuthorizationBearer

API key from app.videogen.io/api. The full key is only shown once when you create it.

Path parameters

entityIdstringRequired

The entity id (e.g. vg_enti_...).

Request

This endpoint expects an object.

fileIdstringRequired

The file id (e.g. vg_file_...) of an image to attach as a reference.

descriptionstringOptional

Optional description of the reference.

roleenumOptionalDefaults to REFERENCE

What the file is used for. BRAND_LOGO and BRAND_STYLE_GUIDE are only allowed on BRAND entities, and attaching one replaces the brand’s previous logo or style guide. BRAND_LOGO is applied as the video logo overlay and is never used as a generation reference.

Allowed values:

isDefaultbooleanOptionalDefaults to false

When true, make this the entity’s primary reference (used for its thumbnail).

Response

The updated entity

entityIdstring

The entity id (e.g. vg_enti_...).

entityTypeenum

ACTOR features a consistent character; PRODUCT features a consistent product you sell or promote; 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; BRAND holds a logo, a style guide image, and a writing style; LOCATION features a consistent place or set; PROP features a consistent background object that is not a product.

namestring

Display name.

descriptionstring

Optional description. Empty string when not set.

referenceslist of objects

Reference images attached to the entity.

createdAtinteger

Seconds since epoch (Unix timestamp) when the entity was created.

updatedAtinteger

Seconds since epoch (Unix timestamp) when the entity was last updated.

actorConfigobject or nullOptional

Voice and presenter summary for ACTOR entities. Null for non-ACTOR entities.

brandConfigobject or nullOptional

Brand guidance for BRAND entities. Null for other entity types.

isBuiltInbooleanOptional

When true, this is a VideoGen catalog entity. Built-in entities cannot be updated, archived, or have references added or removed.