This section shows how to classify the content of a single video by calling the POST method of the /classify endpoint.

Prerequisites

The examples in this guide assume the following:

You’re familiar with the concepts that are described on the Platform overview page.
You've uploaded a video, and the platform has finished indexing it. The unique identifier of your video is stored in a variable named VIDEO_ID. For details, see the Upload videos page.

Examples

For a description of each field in the request and response, see the API Reference > Classify a video page.

Classifying a video based on visual cues

The following example code uses the options parameter to specify that the platform should classify your video based on visual cues:

CLASSIFY_URL = f"{API_URL}/classify"
headers = {
    "x-api-key": API_KEY
}
data =  {
  "options": ["visual"],
  "video_id": VIDEO_ID,
  "classes": [
      {
      "name": "DanceTok",
      "prompts": [
        "Dance tutorial",
        "Dance group",
        "Dance competition"
      ]
    }
  ]
}
response = requests.post(CLASSIFY_URL, headers=headers, json=data)
print (f'Status code: {response.status_code}')
pprint(response.json())

const CLASSIFY_URL = `${API_URL}/classify`
const data =  {
  'options': ['visual'],
  'video_id': VIDEO_ID,
  'classes': [
      {
      'name': 'DanceTok',
      'prompts': [
        'Dance tutorial',
        'Dance group',
        'Dance competition'
      ]
    }
  ]
}
const resp = await axios.post(
  CLASSIFY_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 output should look similar to the following one

Status code: 200
{
  "video_id": "6435651a9ab33c7198615a80",
  "classes": [
    {
      "name": "DanceTok",
      "score": 96.77333333333335,
      "duration_ratio": 1
    }
  ]

Retrieving information about each matching video segment

The following example code sets the include_clips parameter to true to specify that the platform should retrieve detailed information about each matching video segment:

CLASSIFY_URL = f"{API_URL}/classify"

data =  {
  "options": ["visual"],
  "video_id": VIDEO_ID,
  "include_clips": True,
  "classes": [
      {
      "name": "DanceTok",
      "prompts": [
        "Dance tutorial",
        "Dance group",
        "Dance competition"
      ]
    }
  ]
}

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

const CLASSIFY_URL = `${API_URL}/classify`
const data =  {
  'options': ['visual'],
  'video_id': VIDEO_ID,
  'include_clips': true,
  'classes': [
      {
      'name': 'DanceTok',
      'prompts': [
        'Dance tutorial',
        'Dance group',
        'Dance competition'
      ]
    }
  ]
}
const resp = await axios.post(
  CLASSIFY_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
{
  "video_id": "6435651a9ab33c7198615a80",
  "classes": [
    {
      "name": "DanceTok",
      "score": 96.77333333333335,
      "duration_ratio": 1,
      "clips": [
        {
          "start": 917.625,
          "end": 973.84375,
          "score": 86.01,
          "option": "visual",
          "prompt": "Dance competition",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/6435651a9ab33c7198615a80/918.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230412%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230412T105108Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=dc6342f823029b3ce1314ad5219745ec448bb165c6484cbab1073e5e32ccb505"
        },
        {
          "start": 395.30625000000003,
          "end": 399.15625,
          "score": 46.32,
          "option": "visual",
          "prompt": "Dance group",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/6435651a9ab33c7198615a80/396.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230412%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230412T105108Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=ba9f1a6770c44c1a5cb53b46cb38f089aaa221e20954a879b981b2d0b1be745c"
        }
      ]
    }
  ]
}

In the example output above, note that each element in the clips array contains detailed information about a single matching video segment.

Classifying a video based on multiple classes

The following example code classifies the content of a video based on two classes - DanceTok and CookTok:

CLASSIFY_URL = f"{API_URL}/classify"

data =  {
  "options": ["visual"],
  "video_id": VIDEO_ID,
  "classes": [
      {
      "name": "DanceTok",
      "prompts": [
        "Dance tutorial",
        "Dance group",
        "Dance competition"
      ]
    },
    {
      "name": "CookTok",
      "prompts": [
        "Cooking tutorial",
        "Cooking ustensils review"
      ]
    }
  ]
}
response = requests.post(CLASSIFY_URL, headers=headers, json=data)
print (f'Status code: {response.status_code}')
pprint(response.json())

const CLASSIFY_URL = `${API_URL}/classify`
const  data =  {
  'options': ['visual'],
  'video_id': VIDEO_ID,
  'classes': [
      {
      'name': 'DanceTok',
      'prompts': [
        'Dance tutorial',
        'Dance group',
        'Dance competition'
      ]
    },
    {
      'name': 'CookTok',
      'prompts': [
        'Cooking tutorial',
        'Cooking ustensils review'
      ]
    }
  ]
}
const resp = await axios.post(
  CLASSIFY_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 output should look similar to the following one:

Status code: 200
{
  "video_id": "6435651a9ab33c7198615a80",
  "classes": [
    {
      "name": "DanceTok",
      "score": 96.77333333333335,
      "duration_ratio": 1
    }
  ]
}

Retrieving a detailed score for each class

The following example code sets the show_detailed_score parameter to true to specify that the platform should retrieve the maximum score, average score, duration weighted score, and normalized score for each class:

CLASSIFY_URL = f"{API_URL}/classify"

data =  {
  "options": ["visual"],
  "video_id": VIDEO_ID,
  "show_detailed_score": True,
  "classes": [
      {
      "name": "DanceTok",
      "prompts": [
        "Dance tutorial",
        "Dance group",
        "Dance competition"
      ]
    }
  ]
}

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

const CLASSIFY_URL = `${API_URL}/classify`
const data =  {
  'options': ['visual'],
  'video_id': VIDEO_ID,
  'show_detailed_score': true,
  'classes': [
      {
      'name': 'DanceTok',
      'prompts': [
        'Dance tutorial',
        'Dance group',
        'Dance competition'
      ]
    }
  ]
}
const resp = await axios.post(
  CLASSIFY_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 output should look similar to the following one:

Status code: 200
{
  "video_id": "6435651a9ab33c7198615a80",
  "classes": [
    {
      "name": "DanceTok",
      "score": 96.77333333333335,
      "duration_ratio": 1,
      "detailed_scores": {
        "max_score": 86.37,
        "avg_score": 71.61778350515468,
        "duration_weighted_score": 96.77333333333335,
        "normalized_score": 100
      }
    }
  ]
}

Filtering

This endpoint supports filtering. For details, see the Filtering > Content Classification page.