The logo detection feature allows you to identify the presence of brand logos within your videos.

Note the following about detecting logos:

By default, logo detection is disabled. You can enable this feature when creating a new index.
The API service allows you to detect logos in a specific video or a set of search results.
When logo detection is enabled, the API service identifies when either the logo or the company name appears in a video. For example, when performing a search and setting the value of the query parameter to "Twelve Labs", the API service detects both the logo and the text itself using OCR.
Once logo detection has been enabled for an index, you cannot disable it. To stop using it, you must delete the index.

The steps for detecting logos are as follows:

Enable logo detection for a new index.
Upload videos to the index you've created in the previous step.
(Optional) To detect logos in a specific video, you must retrieve the unique identifier of that video. Otherwise, you can skip this step.
Depending on your use case, detect logos in a specific video or search results.

Note that, although the example code in this guide is written in Python and Node.js, the API is compatible with most programming languages, and you can also use Postman or other REST clients to send requests and view responses.

Prerequisites

You’re familiar with the concepts that are described on the Understand page.
You have a valid Twelve Labs account. For details about creating an account and retrieving your API key, see the Authentication page.
You must use at least the 1.1 version of the API.
Ensure that the videos you upload meet the following requirements:
- Video resolution: must be greater or equal than 360p and less than 1080p (FHD)
- Duration: must be between 10 seconds and 2 hours (7,200s)
  If you require different options, send us an email at support[at]twelvelabs.io.

Procedure

Follow the steps in the sections below to detect logos.

1. Enable the logo detection feature

By default, the logo detection feature is disabled. You can enable it on a per-index basis when creating a new index. To do so, call the POST method of the /indexes endpoint, ensuring that the addons array contains the logo value, and the index_options array contains the text_in_video value.

In the example code below, replace the placeholder surrounded by <> with the name you want to give to your index.

INDEXES_URL = f"{API_URL}/indexes"

INDEX_NAME = "<YOUR_INDEX_NAME>" # Use a descriptive name for your index 

headers = {
    "x-api-key": API_KEY
}

data = {
  "engine_id": "marengo2",
  "index_options": ["text_in_video"],
    "addons": ["logo"],
  "index_name": INDEX_NAME
}

response = requests.post(INDEXES_URL, headers=headers, json=data)
INDEX_ID = response.json().get('_id')
print (f'Status code: {response.status_code}')
pprint (response.json())

INDEXES_URL = f"{API_URL}/indexes"

INDEX_NAME = "<YOUR_INDEX_NAME>" # Use a descriptive name for your index 

headers = {
    "x-api-key": API_KEY
}

data = {
  "engine_id": "marengo2",
  "index_options": ["text_in_video"],
  "addons": ["logo"],
  "index_name": INDEX_NAME
}

response = requests.post(INDEXES_URL, headers=headers, json=data)
INDEX_ID = response.json().get('_id')
print (f'Status code: {response.status_code}')
pprint (response.json())

The output should look similar to the following one:

Status code: 201
{ _id: '63ea7ea81b8502baddec7336' }

2. Upload a video

Once you've created an index and enabled logo detection, you can upload videos to it.

The following example code shows how you can upload a video. Make sure to replace the placeholders surrounded by <> with your values.

TASKS_URL = f"{API_URL}/tasks"
file_name = "<FILE_NAME>" # Example: "test.mp4"
file_path = "<FILE_PATH>" # Example: "/Downloads/test.mp4"
file_stream = open(file_path,"rb")
data = {
    "index_id": INDEX_ID, 
    "language": "en"
}
file_param=[
    ("video_file", (file_name, file_stream, "application/octet-stream")),]
response = requests.post(TASKS_URL, headers=headers, data=data, files=file_param)
TASK_ID = response.json().get("_id")

const TASKS_URL = `${API_URL}/tasks`
const file_path = '<FILE_PATH>' // Example: "/Downloads/test.mp4"
const file_stream = fs.createReadStream(file_path)
let formData = new FormData()
formData.append('INDEX_ID', INDEX_ID)
formData.append('language', 'en')
formData.append('video_file', file_stream)
config = {
      method: 'post',
      url: TASKS_URL,
      headers: headers,
      data : formData
};
resp = await axios(config)
response = await resp.data
const TASK_ID = response._id
console.log(`Status code: ${resp.status}`)
console.log(response)

The output should look similar to the following one:

Status code: 200
{
  "_id": "639760f4117eacc7c7398a69"
}

3. (Optional) Retrieve the unique identifier of your video

You can skip the steps in this section if you want to detect logos in a set of search results.

The API service must have finished indexing your video before you can retrieve its unique identifier. Use the GET method of the /tasks/{_id} endpoint to monitor the indexing process.

Construct the URL for retrieving the status of your video indexing task based on the TASK_ID variable you’ve declared in the previous section, and wait until the status shows as ready:

TASK_STATUS_URL = f"{API_URL}/tasks/{TASK_ID}"
while True:
    response = requests.get(TASK_STATUS_URL, headers=headers)
    STATUS = response.json().get("status")
    if STATUS == "ready":
        break
    time.sleep(10)

const TASK_STATUS_URL = `${API_URL}/tasks/${TASK_ID}`
const uploadResp = await new Promise((res) => {
const interval = setInterval(async () => {
      const { data: response } = await axios.get(
            TASK_STATUS_URL,
            {
                headers: {
                    "x-api-key": API_KEY
                }
            }
        );
        if (response.status == "ready") {
          clearInterval(interval);
            res(response);
        }
    }, 1000);
});

Store the unique identifier of your video in a variable named VIDEO_ID and print it:
```
VIDEO_ID = response.json().get('video_id')
print(f"VIDEO ID: {VIDEO_ID}")
```
```
const VIDEO_ID = uploadResp.video_id
```
The output should look similar to the following one:
```
VIDEO ID: 6391c8a669ff3402ec515aba
```

4. Detect logos

You can either detect logos in a specific video or a set of search results. Depending on your use case, proceed to one of the following sections.

Detect logos in a video

Call the GET method of the /indexes/{index-id}/videos/{video_id}/text-in-video endpoint, specifying the following parameters in the URL:

The unique identifier of your index
The unique identifier of your video

Note that the response will also contain all the text recognized in the specified video (OCR).

headers = {
  "x-api-key": API_KEY
}

INDEXES_VIDEOS = f"{API_URL}/indexes/{INDEX_ID}/videos/{VIDEO_ID}/text-in-video"

response = requests.get(INDEXES_VIDEOS, headers=headers)
print(f"Status code: {response.status_code}")
pprint(response.json())

const INDEXES_VIDEOS = `${API_URL}/indexes/${INDEX_ID}/videos/${VIDEO_ID}/text-in-video`

const resp = await axios.get(
    SEARCH_URL,
    data,
    {
        "headers": {
            "x-api-key": API_KEY
        }
    }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The following example output has been truncated for brevity:

Status code: 200
{
  "id": "63eb68e09678ed7709731d64",
  "index_id": "63eb49211b8502baddec7391",
  "data": [
    {
      "end": 168,
      "start": 167,
      "value": "Hyundai Motor Company"
    },
    {
      "end": 226,
      "start": 224,
      "value": "HYUNDAI MOTORSPORT"
    },
  ]
}

In this example output, both the Hyundai logo and the word Hyundai appear in the specified video, as shown below:

The logo appears at 167 seconds from the start of the video:
The word Hyundai is detected using OCR at 224 seconds from the start of the video:

Detect logos in search results

Call the POST method of the /search endpoint with the following parameters:

query: The name of the company
search_options: The source of information the API service uses (text_in_video)
index_id: The unique identifier of the index you've previously created

Note that the response will also contain all the appearances (OCR) of the text specified in the query parameter.

The example code below finds when either the Starbucks company logo or the company name appears in your videos:

headers = {
  "x-api-key": API_KEY
}

SEARCH_URL = f"{API_URL}/search"

data = {
  "query": "Starbucks",
  "index_id": INDEX_ID,
  "search_options": ["text_in_video"],
}

response = requests.post(SEARCH_URL, headers=headers, json=data)
print(f"Status code: {response.status_code}")
pprint(response.json())

const SEARCH_URL = `${API_URL}/search`

const data = {
    "query": "Starbucks",
    "index_id": INDEX_ID,
    "search_options": ["text_in_video"],
}

const resp = await axios.post(
    SEARCH_URL,
    data,
    {
        "headers": {
            "x-api-key": API_KEY
        }
    }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The following example output was truncated for brevity:

Status code: 200
{
  "search_pool": {
    "total_count": 4,
    "total_duration": 1634,
    "index_id": "63eb49211b8502baddec7391"
  },
  "data": [
    {
      "score": 92.28,
      "start": 104,
      "end": 106,
      "metadata": [
        {
          "type": "text_in_video",
          "text": "Starbucks"
        }
      ],
      "video_id": "63eb67e49678ed7709731d63",
      "confidence": "high"
    },
    {
      "score": 92.28,
      "start": 167,
      "end": 170,
      "metadata": [
        {
          "type": "text_in_video",
          "text": "Starbucks"
        }
      ],
      "video_id": "63eb67e49678ed7709731d63",
      "confidence": "high"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "total_results": 5,
    "page_expired_at": "2023-02-17T06:18:47Z"
  }
}

In this example output, the Starbucks logo appears once, and the word Starbucks is also recognized using OCR, as shown below:

The logo appears at 104 seconds from the start of the video:
The word Starbucks is recognized using OCR at 224 seconds from the start of the video: