Versioning

The sections below list all new features, enhancements, and changes to the API service, in chronological order.

Version 1.1

The introduction of new features and improvements in the v1.1 version of the Twelve Labs Video Understanding API has required changes to some endpoints. If you have used version v1.0 of the API, please refer to the following sections for important information regarding the changes.

New features

Version 1.1 of the Twelve Labs Video Understanding API introduces the following new features:

  • Classification of content: You can now define a list of labels that you want to classify your videos into, and the new classification API endpoint will return the duration for which the specified labels have appeared in your videos and the confidence that each of the matches represents the label you've specified. For more details, see the Classifying content page.
  • Combined Queries: The 1.1 version of the API introduces a new format of search queries named combined queries. Note that the combined queries feature is in beta release and is subject to change. A combined query includes any number of subqueries linked with any number of logical operators. Combined queries are executed in one API request.
    Combined queries support the following additional features:
    • Negating a condition: In addition to the existing AND operator, the API service now allows you to use the NOT operator to negate a condition. For example, this allows you to write a query that retrieves all the video fragments in which someone is cooking but neither spaghetti nor lasagna is mentioned in the conversation.
    • The SEQUENT operator: The API service now supports the SEQUENT operator that allows you to specify that the API service must return only the results for which the order of the matching video fragments is the same as the order of your queries.
    • Time-proximity search: The Twelve Labs Video Understanding API now allows you to use the proximity parameter to extend the lower and upper boundaries of each subquery. For example, this allows you to write a query that finds all car accidents that happened within a specific interval of time before someone wins a race.
      For details, see the Using combined queries page.

Differences

This section lists the differences between version 1 and version 1.1 of the Twelve Labs Video Understanding API.

  • When you make an API call, make sure that you specify the 1.1 version in the URL.
    The URL should look similar to the following one: https://https://api.twelvelabs.io./v1.1/{resource}/{path_parameters}?{query_parameters}. For more details, see the Call an endpoint section.

  • The following methods now return a 200 OK status code when the response is empty:

    • [GET] /indexes
    • [GET] /tasks
    • [GET] /indexes/{index_id}/videos
  • The /tasks endpoint is now a separate endpoint and is no longer part of the /indexes endpoint. The table below shows the changes made to each method of the /tasks endpoint:

    1.01.1
    GET /indexes/tasksGET /tasks
    POST /indexes/tasksPOST /tasks
    GET /indexes/tasks/{task_id}GET /tasks/{task_id}
    DELETE /indexes/tasks/{task_id}DELETE /tasks/{task_id}
    POST /indexes/tasks/transfersPOST /tasks/transfers
    GET /indexes/tasks/statusGET /tasks/status
  • The /indexes/tasks/{task_id}/video_id endpoint has been deprecated. You can now retrieve the unique identifier of a video by invoking the GET method of the /tasks/{task_id} endpoint. The response will contain a field named video_id. For details, see steps six and seven on the Upload from the local file system page.

  • When an error occurs, the API service now follows the recommendations of the RFC 9110 standard. Instead of numeric codes, the API service now returns string values containing human-readable descriptions of the errors. The format of the error messages is as follows:

    • code: A string representing the error code.
    • message: A human-readable string describing the error, intended to be suitable for display in a user interface.
    • (Optional) docs_url: The URL of the relevant documentation page.
      For example, if you tried to list all the videos in an index and the unique identifier of the index you specified didn't exist, the 1.0 version of the API returned an error similar to the following one:
    {
      "error_code": 201,
      "message": "ID 234234 does not exist"
    }
    

    Now, when using the 1.1 version of the API, the error should look similar to the following one:

    {
      "code": "parameter_not_provided",
      "message": "The index_id parameter is required but was not provided."
    }
    

    For a list of error messages, see the API Reference > Error codes page.

  • The next_page_id and prev_page_id fields of the page_info object have been renamed to next_page_token and prev_page_id.

  • The type field has been removed from all the responses.

  • When performing searches specifying multiple search options, the API service returns an object containing the confidence level that a specific video fragment matched your search terms for each type of search. In version v1.0, this field was a dictionary named module_confidence. In version v1.1, this field is now named module and is of type array. For details, see the Using multiple sources of information section.

  • The POST method of the /search/{page-token} endpoint has been deprecated. To retrieve the subsequent pages, you must now call the GET method of the /search/{page-token} endpoint, passing it the unique identifier of the page you want to retrieve. For details, see the Pagination > Search results page.