For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sample appsIntegrationsDiscordPlaygroundDevEx repo
GuidesSDK ReferenceAPI Reference
GuidesSDK ReferenceAPI Reference
  • TwelveLabs API
    • Introduction
    • Authentication
  • API Reference
    • Manage indexes
    • Upload content
    • Index content
    • Manage videos
    • Manage entities
    • Any-to-video search
    • Create embeddings v2
    • Create embeddings v1
    • Analyze and segment videos
    • Error codes
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
On this page
  • Call an endpoint
  • Responses
  • HTTP status codes
  • Errors
TwelveLabs API

Introduction

Was this page helpful?

Authentication

Next
Built with

Use the TwelveLabs Video Understanding API to extract information from your videos and make it available to your applications. The API is organized around REST and returns responses in JSON format. It is compatible with most programming languages, and you can use one of the available SDKs, Postman, or other REST clients to interact with the API.

Call an endpoint

To call an endpoint, you must construct a URL similar to the following one:

{Method} {BaseURL}/{version}/{resource}/{path_parameters}?{query_parameters}

The list below describes each component of a request:

  • Method: The API supports the following methods:
    • GET: Reads data.
    • POST: Creates a new object or performs an action.
    • PUT: Updates an object.
    • DELETE: Deletes an object.
      Note that the POST and PUT methods require you to pass a request body containing additional parameters.
  • Base URL: The base URL of the API is https://api.twelvelabs.io.
  • Version: To use this version of the API, it must be set to v1.3.
  • Resource: The name of the resource you want to interact with.
  • Path Parameters: Allow you to indicate a specific object. For example, you can retrieve details about a model or index.
  • Query Parameters: Any parameters that an endpoint accepts. For example, you can filter or sort a response using query parameters.

Note that the API requires you to pass a header parameter containing your API key to authenticate each request. For details, see the Authentication page.

Responses

TwelveLabs Video Understanding API follows the RFC 9110 standard to indicate the success or failure of a request. Each response contains a field named X-Api-Version that indicates the version of the API against which the operation was performed.

HTTP status codes

The following list is a summary of the HTTP status codes returned by the platform:

  • 200: The request was successful.
  • 201: The request was successful and a new resource was created.
  • 400: The API service cannot process the request. See the code and message fields in the response for more details about the error.
  • 401: The API key you provided is not valid.
  • 404: The requested resource was not found.
  • 429: Indicates that a rate limit has been reached.

Errors

HTTP status codes in the 4xx range indicate an error caused by the parameters you provided in the request. For each error, the API service returns the following fields in the body of the response:

  • 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 more details, see the Error codes page.