Manage entities
The SDK offers methods for managing entities related to video search. It operates with three types of resources:
- Assets: Reference images of the persons you wish to identify.
- Entity collections: Logical groupings of related entities, such as players on a team.
- Entities: Specific persons you want to locate in videos, associated with their reference images.
Note
- To use the Entity Search feature, the Marengo 3.0 video understanding model must be enabled in your index.
- The platform automatically creates a sample entity collection when you create your account. Users on the Free plan can have a total of one entity collection with up to fifteen entities. The default collection is included in this limit. To create more entity collections, upgrade to the Developer plan. For instructions, see the Upgrade your plan section.
Assets
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
Entity collections organize related entities into logical groups.
List entity collections
Description: This method returns a list of the entity collections in your account.
Function signature and example:
Parameters
The EntityCollectionsListRequest interface defines the parameters for listing entity collections:
Return value
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:
API Reference
Create an entity collection
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:
Parameters
The EntityCollectionsCreateRequest interface defines the parameters for creating an entity collection:
Return value
Returns an HttpResponsePromise<TwelvelabsApi.EntityCollection> that resolves to an EntityCollection object representing the newly created entity collection. The EntityCollection interface contains the following properties:
API Reference
Retrieve an entity collection
Description: This method retrieves details about the specified entity collection.
Function signature and example:
Parameters
Return value
Returns an HttpResponsePromise<TwelvelabsApi.EntityCollection> that resolves to an EntityCollection object representing the specified entity collection. The EntityCollection interface contains the following properties:
API Reference
Update an entity collection
Description: This method updates the specified entity collection.
Function signature and example:
Parameters
The EntityCollectionsUpdateRequest interface defines the parameters for updating an entity collection:
Return value
Returns an HttpResponsePromise that resolves to an EntityCollection object representing the updated entity collection. The EntityCollection interface contains the following properties:
API Reference
Delete an entity collection
Description: This method deletes the specified entity collection. This action cannot be undone.
Function signature and example:
Parameters
Return value
Returns an HttpResponsePromise that resolves when the entity collection has been successfully deleted.
API Reference
Entities
Entities represent logical groupings of related entities.
List entities in an entity collection
Description: This method returns a list of the entities in the specified entity collection.
Function signature and example:
Parameters
The EntitiesListRequest interface defines the parameters for listing entities in an entity collection:
Return value
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:
API Reference
List entities in an entity collection
Create an entity
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:
Parameters
The EntitiesCreateRequest interface defines the parameters for creating an entity:
Return value
Returns an HttpResponsePromise that resolves to an Entity object representing the newly created entity. The Entity interface contains the following properties:
API Reference
Create multiple entities in bulk
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:
Parameters
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:
Return value
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:
API Reference
Create multiple entities in bulk
Retrieve an entity
Description: This method retrieves details about the specified entity.
Function signature and example:
Parameters
Return value
Returns an HttpResponsePromise that resolves to an Entity object representing the specified entity. The Entity interface contains the following properties:
API Reference
Update an entity
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:
Parameters
The EntitiesUpdateRequest interface defines the parameters for updating an entity:
Return value
Returns an HttpResponsePromise that resolves to an Entity object representing the updated entity. The Entity interface contains the following properties:
API Reference
Delete an entity
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:
Parameters
Return value
Returns an HttpResponsePromise that resolves when the entity has been successfully deleted.
PI Reference
Add assets to an entity
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:
Parameters
The EntitiesCreateAssetsRequest interface contains an array of strings representing the asset IDs to be added to the entity.
Return value
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:
API Reference
Remove assets from an entity
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.”
Notes
- This operation only removes the association between the entity and the specified assets; it does not delete the assets themselves.
- An entity must always have at least one asset associated with it. You can’t remove the last asset from an entity.
Function signature and example:
Parameters
The EntitiesDeleteAssetsRequest interface contains an array of strings representing the asset IDs to be removed from the entity.
Return value
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:
