The SDK offers methods for managing entities related to video search. It operates with three types of resources:
Assets are reference images that help identify people in videos. Upload multiple images per person to improve identification accuracy.
For a complete reference on how to create assets, see the Direct uploads section.
Entity collections organize related entities into logical groups.
Description: This method returns a list of the entity collections in your account.
Function signature and example:
The EntityCollectionsListRequest interface defines the parameters for listing entity collections:
Returns a Promise that resolves to a core.Page<TwelvelabsApi.EntityCollection> instance, representing the entity collections that match the specified criteria.
The Page class contains the following properties and methods:
The EntityCollection interface contains the following properties:
Description**: This method creates an entity collection.
Free plan users can create one entity collection with up to 15 entities. If your needs exceed the Free plan, consider upgrading to the Developer plan.
Function signature and example:
The EntityCollectionsCreateRequest interface defines the parameters for creating an entity collection:
Returns an HttpResponsePromise<TwelvelabsApi.EntityCollection> that resolves to an EntityCollection object representing the newly created entity collection. The EntityCollection interface contains the following properties:
Description: This method retrieves details about the specified entity collection.
Function signature and example:
Returns an HttpResponsePromise<TwelvelabsApi.EntityCollection> that resolves to an EntityCollection object representing the specified entity collection. The EntityCollection interface contains the following properties:
Description: This method updates the specified entity collection.
Function signature and example:
The EntityCollectionsUpdateRequest interface defines the parameters for updating an entity collection:
Returns an HttpResponsePromise that resolves to an EntityCollection object representing the updated entity collection. The EntityCollection interface contains the following properties:
Description: This method deletes the specified entity collection. This action cannot be undone.
Function signature and example:
Returns an HttpResponsePromise that resolves when the entity collection has been successfully deleted.
Entities represent logical groupings of related entities.
Description: This method returns a list of entities whose assetIds array contains the specified asset.
Function signature and example:
The EntitiesListByAssetRequest interface has the following properties:
Returns a Promise that resolves to a core.Page<TwelvelabsApi.Entity> instance, representing the entities that reference the specified asset.
The Page class contains the following properties and methods:
The Entity interface contains the following properties:
Description: This method returns a list of the entities in the specified entity collection.
Function signature and example:
The EntitiesListRequest interface defines the parameters for listing entities in an entity collection:
Returns a Promise that resolves to a core.Page<TwelvelabsApi.Entity> instance, representing the entities that match the specified criteria.
The Page class contains the following properties and methods:
The Entity interface contains the following properties:
List entities in an entity collection
Description: This method creates an entity within a specified entity collection. Each entity must be associated with at least one asset.
Function signature and example:
The EntitiesCreateRequest interface defines the parameters for creating an entity:
Returns an HttpResponsePromise that resolves to an Entity object representing the newly created entity. The Entity interface contains the following properties:
Description: This method creates multiple entities within a specified entity collection in a single request. Each entity must be associated with at least one asset. This method is useful for efficiently adding multiple entities, such as a roster of players or a group of characters.
Function signature and example:
The EntitiesCreateBulkRequest interface defines the parameters for creating multiple entities in bulk. It’s an array of TwelvelabsApi.entityCollections.EntitiesCreateBulkRequestEntitiesItem objects, each representing an entity to be created.
The EntitiesCreateBulkRequestEntitiesItem interface defines the parameters for each entity to be created:
Returns an HttpResponsePromise that resolves to a BulkCreateEntityResponse object. The BulkCreateEntityResponse interface contains the following properties:
The BulkCreateEntityResponseEntitiesItem interface contains the following properties:
The BulkCreateEntityResponseErrorsItem interface contains the following properties:
Create multiple entities in bulk
Description: This method retrieves details about the specified entity.
Function signature and example:
Returns an HttpResponsePromise that resolves to an Entity object representing the specified entity. The Entity interface contains the following properties:
Description: This method updates the specified entity within an entity collection. This operation allows modification of the entity’s name, description, or metadata. Note that this method does not affect the assets associated with the entity.
Function signature and example:
The EntitiesUpdateRequest interface defines the parameters for updating an entity:
Returns an HttpResponsePromise that resolves to an Entity object representing the updated entity. The Entity interface contains the following properties:
Description: This method deletes a specific entity from an entity collection. It permanently removes the entity and its associated data, but does not affect the assets associated with this entity.
Function signature and example:
Returns an HttpResponsePromise that resolves when the entity has been successfully deleted.
Description: This method adds assets to the specified entity within an entity collection. Assets are used to identify the entity in media content, and adding multiple assets can improve the accuracy of entity recognition in searches. When assets are added, the entity may temporarily enter the “processing” state while the platform updates the necessary data. Once processing is complete, the entity status will return to “ready.”
Function signature and example:
The EntitiesCreateAssetsRequest interface contains an array of strings representing the asset IDs to be added to the entity.
Returns an HttpResponsePromise that resolves to an Entity object representing the updated entity with the newly added assets. The Entity interface contains the following properties:
Description: This method removes from the specified entity. Assets are used to identify the entity in media content, and removing assets may impact the accuracy of entity recognition in searches if too few assets remain.
When assets are removed, the entity may temporarily enter a “processing” state while the system updates the necessary data. Once processing is complete, the entity status will return to “ready.”
Function signature and example:
The EntitiesDeleteAssetsRequest interface contains an array of strings representing the asset IDs to be removed from the entity.
Returns an HttpResponsePromise that resolves to an Entity object representing the updated entity with the specified assets removed. The Entity interface contains the following properties: