The /classify and /classify/bulk endpoints support filtering, but the implementation is slightly different depending on the endpoint that you're calling. For details, proceed to one of the following sections.

Prerequisites

You’re familiar with the concepts that are described on the Platform overview page.
You've already created an index, and the Marengo video understanding engine is enabled for this index.
You've already uploaded a video, and the platform has finished indexing it.

Examples

Classify a set of videos

When classifying a set of videos by calling the classify endpoint, you can use the threshold field to filter the results based on the following criteria:

threshold.min_video_score: Filters based on the confidence level that a video matches the specified class. The minimum value is 0 and the maximum value is 100. If this field is not set, it takes the default value of 75.
threshold.min_video_score: Filters based on the confidence level that a clip matches the specified class. The minimum value is 0 and the maximum value is 100. If this field is not set, it takes the default value of 65.
min_duration_ratio: Filters based on the duration ratio, which is the sum of the lengths of the matching video clips inside a video divided by the total length of the video. The minimum value is 0.01 and the maximum value is 1. If this field is not set, it takes the default value of 0.5.

For more details about each field in the request and response, see the API Reference > Classify a set of videos page.

The following example code sets the value of the threshold.min_video_score to 80 and the value of the threshold.min_clip_score to 75:

CLASSIFY_URL = f"{API_URL}/classify"
data =  {
  "options": ["visual"],
  "video_ids": [VIDEO_ID],
  "threshold": {
  	"min_video_score": 80,
    "min_clip_score": 75
  },
  "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_ids': [VIDEO_ID],
  'threshold': {
  	'min_video_score': 80,
    'min_clip_score': 75
  },
  '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:

{
  "data": [
    {
      "video_id": "646b1bbfe6a77b9f1294e182",
      "classes": [
        {
          "name": "DanceTok",
          "score": 95.02,
          "duration_ratio": 0.99
        }
      ]
    }
  ],
  "page_info": {
    "limit_per_page": 1,
    "total_results": 1,
    "page_expired_at": "2023-05-22T07:57:02Z",
    "next_page_token": "",
    "prev_page_token": ""
  }
}

Classify all the videos within an index

When classifying all the videos within an index, you can use the threshold parameter to filter the results based on the level of confidence that the results match the prompts you've specified in the request. The minimum value is 0 and the maximum value is 100. If the parameter is not set, it takes the default value of 75. This allows you to narrow down a response obtained from the platform by retrieving only the most relevant results.

For more details about each field in the request and response, see the API Reference > Classify a set of videos page.

The following example code sets the value of the threshold parameter to 80:

CLASSIFY_URL = f"{API_URL}/classify"
data =  {
  "options": ["visual"],
  "video_ids": [VIDEO_ID],
  "threshold": 80,
  "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_ids': [VIDEO_ID],
  'threshold': 80,
  '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
      }
    }
  ]
}