The TwelveLabs Python 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.

Assets

Assets are reference images that help identify people in videos. Upload multiple images per person to improve identification accuracy.

List assets

Description: This method returns a list of assets in your account. The platform returns your assets sorted by creation date, with the newest at the top of the list.

Function signature and example:

1
def list(
2
    self,
3
    *,
4
    page: typing.Optional[int] = None,
5
    page_limit: typing.Optional[int] = None,
6
    asset_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
7
    request_options: typing.Optional[RequestOptions] = None,
8
) -> SyncPager[Asset]

Parameters:

Return value: Returns a SyncPager[Asset] object containing a paginated list of Asset objects, representing the assets that match the specified criteria.

The SyncPager[T] class contains the following properties and methods:

The Asset class contains the following properties:

API Reference: List assets

Create an asset

Description: This method creates an asset by uploading an image file or providing a publicly accessible URL.

Note the following about creating assets:

• The platform will automatically delete assets not associated with any entity 72 hours after creation.
• You can associate a single asset with multiple entities.

Your image files must meet the format requirements.

Ensure URLs point directly to the raw image file without requiring user interaction.

Upload options:

• Local file: Set the method parameter to direct and use the file parameter to specify the image file.
• Publicly accessible URL: Set the method parameter to url and use the url parameter to specify the URL of your image file.

Function signature and example:

1
def create(
2
    self,
3
    *,
4
    method: AssetsCreateRequestMethod,
5
    file: typing.Optional[core.File] = OMIT,
6
    url: typing.Optional[str] = OMIT,
7
    request_options: typing.Optional[RequestOptions] = None,
8
) -> Asset

Parameters:

Return value: Returns an object of type Asset representing the newly created asset. The Asset class contains the following properties:

API Reference: Create an asset

Retrieve an asset

Description: This method retrieves details about the specified asset.

Function signature and example:

1
def retrieve(self, asset_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> Asset

Parameters:

Return value: Returns an object of type Asset representing the specified asset. The Asset class contains the following properties:

API Reference: Retrieve an asset

Delete an asset

Description: This method deletes the specified asset. This action cannot be undone.

Function signature and example:

1
def delete(self, asset_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None

Parameters:

Return value: None. This method doesn’t return any data upon successful completion.

API Reference: Delete an asset

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:

1
def list(
2
    self,
3
    *,
4
    page: typing.Optional[int] = None,
5
    page_limit: typing.Optional[int] = None,
6
    name: typing.Optional[str] = None,
7
    sort_by: typing.Optional[EntityCollectionsListRequestSortBy] = None,
8
    sort_option: typing.Optional[str] = None,
9
    request_options: typing.Optional[RequestOptions] = None,
10
) -> SyncPager[EntityCollection]

Parameters:

Return value: Returns a SyncPager[EntityCollection] object containing a paginated list of EntityCollection objects, representing the entity collections that match the specified criteria.

The SyncPager[T] class contains the following properties and methods:

The EntityCollection class contains the following properties:

API Reference: List entity collections

Create an entity collection

Description: This method creates an entity collection.

Function signature and example:

1
def create(
2
    self,
3
    *,
4
    name: str,
5
    description: typing.Optional[str] = OMIT,
6
    request_options: typing.Optional[RequestOptions] = None,
7
) -> EntityCollection

Parameters:

Return value: Returns an object of type EntityCollection representing the newly created entity collection. The EntityCollection class contains the following properties:

API Reference: Create an entity collection

Retrieve an entity collection

Description: This method retrieves details about the specified entity collection.

Function signature and example:

1
def retrieve(
2
    self, entity_collection_id: str, *, request_options: typing.Optional[RequestOptions] = None
3
) -> EntityCollection

Parameters:

Return value: Returns an object of type EntityCollection representing the specified entity collection. The EntityCollection class contains the following properties:

API Reference: Retrieve an entity collection

Update an entity collection

Description: This method updates the specified entity collection.

Function signature and example:

1
def update(
2
    self,
3
    entity_collection_id: str,
4
    *,
5
    name: typing.Optional[str] = OMIT,
6
    description: typing.Optional[str] = OMIT,
7
    request_options: typing.Optional[RequestOptions] = None,
8
) -> EntityCollection

Parameters:

Return value: Returns an object of type EntityCollection representing the updated entity collection. The EntityCollection class contains the following properties:

API Reference: Update an entity collection

Delete an entity collection

Description: This method deletes the specified entity collection. This action cannot be undone.

Function signature and example:

1
def delete(self, entity_collection_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None

Parameters:

Return value: None. This method doesn’t return any data upon successful completion.

API Reference: Delete an entity collection

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:

1
def list(
2
    self,
3
    entity_collection_id: str,
4
    *,
5
    page: typing.Optional[int] = None,
6
    page_limit: typing.Optional[int] = None,
7
    name: typing.Optional[str] = None,
8
    status: typing.Optional[EntitiesListRequestStatus] = None,
9
    sort_by: typing.Optional[EntitiesListRequestSortBy] = None,
10
    sort_option: typing.Optional[str] = None,
11
    request_options: typing.Optional[RequestOptions] = None,
12
) -> SyncPager[Entity]

Parameters:

Return value: Returns a SyncPager[Entity] object containing a paginated list of Entity objects, representing the entities that match the specified criteria.

The SyncPager[T] class contains the following properties and methods:

The Entity class 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:

1
def create(
2
    self,
3
    entity_collection_id: str,
4
    *,
5
    name: str,
6
    asset_ids: typing.Sequence[str],
7
    description: typing.Optional[str] = OMIT,
8
    metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = OMIT,
9
    request_options: typing.Optional[RequestOptions] = None,
10
) -> Entity

Parameters:

Return value: Returns an object of type Entity representing the newly created entity. The Entity class contains the following properties:

API Reference: Create an entity

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:

1
def create_bulk(
2
    self,
3
    entity_collection_id: str,
4
    *,
5
    entities: typing.Sequence[EntitiesCreateBulkRequestEntitiesItem],
6
    request_options: typing.Optional[RequestOptions] = None,
7
) -> BulkCreateEntityResponse

Parameters:

The EntitiesCreateBulkRequestEntitiesItem class contains the following properties:

Return value: Returns an object of type BulkCreateEntityResponse representing the result of the bulk entity creation operation. The BulkCreateEntityResponse class contains the following properties:

The BulkCreateEntityResponseEntitiesItem class contains the following properties:

The BulkCreateEntityResponseErrorsItem class 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:

1
def retrieve(
2
        self, entity_collection_id: str, entity_id: str, *, request_options: typing.Optional[RequestOptions] = None
3
    ) -> Entity

Parameters:

Return value: Returns an object of type Entity representing the specified entity. The Entity class contains the following properties:

API Reference: Retrieve an entity

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:

1
def update(
2
    self,
3
    entity_collection_id: str,
4
    entity_id: str,
5
    *,
6
    name: typing.Optional[str] = OMIT,
7
    description: typing.Optional[str] = OMIT,
8
    metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = OMIT,
9
    request_options: typing.Optional[RequestOptions] = None,
10
) -> Entity

Parameters:

Return value: Returns an object of type Entity representing the updated entity. The Entity class contains the following properties:

API Reference: Update an entity

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:

1
def delete(
2
        self, entity_collection_id: str, entity_id: str, *, request_options: typing.Optional[RequestOptions] = None
3
    ) -> None

Parameters:

Return value: None. This method doesn’t return any data upon successful completion.

API Reference: Delete an entity

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:

1
def create_assets(
2
    self,
3
    entity_collection_id: str,
4
    entity_id: str,
5
    *,
6
    asset_ids: typing.Sequence[str],
7
    request_options: typing.Optional[RequestOptions] = None,
8
) -> Entity

Parameters:

Return value: Returns an object of type Entity representing the updated entity with the newly added assets. The Entity class contains the following properties:

API Reference: Add assets to an entity

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.”

Function signature and example:

1
def delete_assets(
2
    self,
3
    entity_collection_id: str,
4
    entity_id: str,
5
    *,
6
    asset_ids: typing.Sequence[str],
7
    request_options: typing.Optional[RequestOptions] = None,
8
) -> Entity

Parameters:

Return value: Returns an object of type Entity representing the updated entity after the specified assets have been removed. The Entity class contains the following properties:

API Reference: Remove assets from an entity