Your taxonomy categories directly affect how reliably Narrative Metadata can classify your videos. Unclear or overlapping categories lead to inconsistent results, while distinct, well-documented categories improve accuracy.
This tutorial covers how to design a taxonomy and upload it programmatically using Python.
Each taxonomy category requires three components:
Organize your categories in a CSV file with columns for metadata_type, name, description, and examples. The metadata_type must be one of: format, genre, mood, or subject.
Overlapping or vague categories cause inconsistent results. Keep categories distinct—if content could fit two categories, consider merging them.
Here’s a sample taxonomy for classifying TV and entertainment content. This CSV defines categories across all four dimensions—format, genre, mood, and subject:
Save your taxonomy as a CSV file (e.g., taxonomy.csv) before running the upload script.
The following Python script reads your taxonomy CSV and uploads each category to the Narrative Metadata API. This automates what would otherwise be repetitive manual API calls.
Before running the script, you’ll need:
requests library (pip install requests)upload_taxonomy_category(): Makes a POST request to /api/v0/video-narrative-metadata/metadata with the category details.load_and_upload_taxonomy(): Reads the CSV file row by row, parses the JSON-formatted examples column, and calls the upload function for each category.Expected output:
Avoid categories that could reasonably describe the same content. If you’re unsure whether two categories overlap, try listing five examples for each—if any example fits both categories, consider merging them.
The description field helps the model understand what to look for. Include:
Choose examples that clearly belong to the category and are recognizable. Specific, concrete descriptions work better than abstract or vague terms.
Begin with 5–10 categories per dimension. You can always add more later, but starting with too many granular categories often leads to inconsistent classification.
After uploading your taxonomy, you’re ready to classify videos:
See the Narrative Metadata guide for the complete classification workflow.