Skip to main content
GET
/
pictoryapis
/
v1
/
music
/
purposes
Get Music Purposes
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/music/purposes \
  --header 'Authorization: <authorization>'
[
  "TV Theme",
  "Heroic",
  "Nature / Beauty",
  "Action",
  "Adventure",
  "Comedy",
  "Drama",
  "Fantasy",
  "Horror",
  "Shopping",
  "Sports",
  "Thriller",
  "Wedding",
  "80s",
  "Educational",
  "News / Current Affairs",
  "On-Hold",
  "Road Trip",
  "Sci-Fi",
  "Time Lapse",
  "Aerobics / Fitness",
  "Atmospheric",
  "Branding / Identity",
  "Corporate / Business",
  "Children / Preschool",
  "Crime",
  "Landscape / Panorama",
  "Mystery / Tension",
  "Nightclub",
  "Technology",
  "Slow-Mo",
  "War / Military",
  "Western / Cowboy",
  "Bollywood",
  "Historical / Period",
  "Real Estate",
  "Christmas",
  "Surfing",
  "Detective / Spy",
  "Dramedy",
  "Game Show",
  "50s",
  "60s",
  "70s",
  "Chase Sequence",
  "Elevator Music",
  "Exotic",
  "Failure / Defeat",
  "Fairytale",
  "Fanfare",
  "Frantic / Busy",
  "Futuristic",
  "Lullaby",
  "Luxury",
  "Retro",
  "Romantic Comedy",
  "Sex / Erotic",
  "Lazy / Plodding",
  "Space / Cosmos",
  "Success / Victory",
  "Superhero",
  "Swampy / Outback",
  "Tribal",
  "Magical / Supernatural",
  "Simple / Minimal",
  "Adrenaline",
  "Evil / Villainous",
  "Religious / Church",
  "Theatre / Showtunes",
  "Regal / Royal",
  "Circus / Carnival",
  "Tropical",
  "Fashion / Beauty",
  "Animation / Explainer",
  "Trailer / Promo",
  "Yoga / Relaxation",
  "Meditation"
]

Documentation Index

Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Retrieve a comprehensive list of available music purposes for filtering and searching music tracks. Use these purpose values to find music that matches the specific use case, context, or application of your video content.
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.

​
API Endpoint

GET https://api.pictory.ai/pictoryapis/v1/music/purposes

​
Request Parameters

​
Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY

​
Response

​
purposes
array of strings
Array of available music purpose names. Each purpose represents a distinct use case, context, or application scenario for filtering music tracks in search queries.

​
Response Examples

[
  "TV Theme",
  "Heroic",
  "Nature / Beauty",
  "Action",
  "Adventure",
  "Comedy",
  "Drama",
  "Fantasy",
  "Horror",
  "Shopping",
  "Sports",
  "Thriller",
  "Wedding",
  "80s",
  "Educational",
  "News / Current Affairs",
  "On-Hold",
  "Road Trip",
  "Sci-Fi",
  "Time Lapse",
  "Aerobics / Fitness",
  "Atmospheric",
  "Branding / Identity",
  "Corporate / Business",
  "Children / Preschool",
  "Crime",
  "Landscape / Panorama",
  "Mystery / Tension",
  "Nightclub",
  "Technology",
  "Slow-Mo",
  "War / Military",
  "Western / Cowboy",
  "Bollywood",
  "Historical / Period",
  "Real Estate",
  "Christmas",
  "Surfing",
  "Detective / Spy",
  "Dramedy",
  "Game Show",
  "50s",
  "60s",
  "70s",
  "Chase Sequence",
  "Elevator Music",
  "Exotic",
  "Failure / Defeat",
  "Fairytale",
  "Fanfare",
  "Frantic / Busy",
  "Futuristic",
  "Lullaby",
  "Luxury",
  "Retro",
  "Romantic Comedy",
  "Sex / Erotic",
  "Lazy / Plodding",
  "Space / Cosmos",
  "Success / Victory",
  "Superhero",
  "Swampy / Outback",
  "Tribal",
  "Magical / Supernatural",
  "Simple / Minimal",
  "Adrenaline",
  "Evil / Villainous",
  "Religious / Church",
  "Theatre / Showtunes",
  "Regal / Royal",
  "Circus / Carnival",
  "Tropical",
  "Fashion / Beauty",
  "Animation / Explainer",
  "Trailer / Promo",
  "Yoga / Relaxation",
  "Meditation"
]

​
Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/music/purposes \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

​
Usage Notes

Use these exact purpose values when searching for music to ensure valid selection from available categories. Purpose values are case-sensitive and must match exactly as returned by this endpoint.
Purpose Diversity: The API provides 74 distinct purpose options spanning various contexts—from media types (TV Theme, Animation/Explainer, Trailer/Promo) to genres (Action, Comedy, Horror) to specific applications (Corporate/Business, Wedding, Real Estate)—enabling precise matching of music to your video’s intended use and context.

​
Common Use Cases

​
1. Populate a Purpose Selector

Fetch all available purposes to populate a dropdown or selection interface in your application: 
purposes = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/purposes",
    headers={"Authorization": "YOUR_API_KEY"}
).json()

# Use purposes to populate UI dropdown
purpose_options = [{"label": purpose, "value": purpose} for purpose in purposes]

​
2. Categorize Purposes by Context

Organize purposes into logical categories for simplified user selection: 
const response = await fetch('https://api.pictory.ai/pictoryapis/v1/music/purposes', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
});
const purposes = await response.json();

// Categorize by type
const mediaGenres = purposes.filter(p =>
  ['Action', 'Adventure', 'Comedy', 'Drama', 'Fantasy', 'Horror', 'Thriller', 'Sci-Fi'].includes(p)
);

const businessPurposes = purposes.filter(p =>
  p.includes('Corporate') || p.includes('Business') || p.includes('Branding') ||
  p.includes('Real Estate') || p.includes('Technology')
);

const timePerods = purposes.filter(p =>
  ['50s', '60s', '70s', '80s', 'Retro', 'Futuristic', 'Historical / Period'].includes(p)
);

const videoPurposes = purposes.filter(p =>
  p.includes('Animation') || p.includes('Trailer') || p.includes('Time Lapse') ||
  p.includes('Slow-Mo') || p.includes('Explainer')
);

const eventPurposes = purposes.filter(p =>
  ['Wedding', 'Christmas', 'Circus / Carnival', 'Game Show'].includes(p)
);

const wellnessPurposes = purposes.filter(p =>
  p.includes('Yoga') || p.includes('Meditation') || p.includes('Relaxation') ||
  p.includes('Aerobics') || p.includes('Fitness')
);

​
3. Validate User Input

Ensure user-selected purposes are valid before using them in music search requests: 
valid_purposes = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/purposes",
    headers={"Authorization": "YOUR_API_KEY"}
).json()

user_purpose = "Corporate / Business"
if user_purpose in valid_purposes:
    # Proceed with music search using this purpose
    print(f"Searching for {user_purpose} music...")
else:
    print("Invalid purpose selected")

​
4. Build Multi-Category Purpose Filter

Create a categorized purpose filter for intuitive music discovery: 
import requests

purposes = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/purposes",
    headers={"Authorization": "YOUR_API_KEY"}
).json()

# Organize by category
categories = {
    "Film & TV": [p for p in purposes if any(x in p for x in ['TV Theme', 'Action', 'Adventure', 'Comedy', 'Drama', 'Fantasy', 'Horror', 'Thriller', 'Sci-Fi', 'Western', 'Detective', 'Spy'])],

    "Business & Corporate": [p for p in purposes if any(x in p for x in ['Corporate', 'Business', 'Branding', 'Identity', 'Technology', 'Real Estate', 'Educational', 'News'])],

    "Video Production": [p for p in purposes if any(x in p for x in ['Animation', 'Explainer', 'Trailer', 'Promo', 'Time Lapse', 'Slow-Mo'])],

    "Events & Occasions": [p for p in purposes if any(x in p for x in ['Wedding', 'Christmas', 'Circus', 'Carnival', 'Game Show', 'Shopping'])],

    "Time Periods": [p for p in purposes if p in ['50s', '60s', '70s', '80s', 'Retro', 'Historical / Period', 'Futuristic']],

    "Wellness & Lifestyle": [p for p in purposes if any(x in p for x in ['Yoga', 'Meditation', 'Relaxation', 'Aerobics', 'Fitness', 'Fashion', 'Beauty', 'Luxury'])],

    "Moods & Emotions": [p for p in purposes if any(x in p for x in ['Heroic', 'Success', 'Victory', 'Failure', 'Defeat', 'Adrenaline', 'Romantic', 'Lullaby'])],

    "Nature & Places": [p for p in purposes if any(x in p for x in ['Nature', 'Beauty', 'Landscape', 'Panorama', 'Space', 'Cosmos', 'Tropical', 'Swampy', 'Outback'])],

    "Cultural & Regional": [p for p in purposes if any(x in p for x in ['Bollywood', 'Western', 'Cowboy', 'Religious', 'Church', 'Tribal', 'Exotic'])],

    "Special Applications": [p for p in purposes if any(x in p for x in ['On-Hold', 'Elevator', 'Nightclub', 'Road Trip', 'Surfing', 'Chase Sequence'])]
}

for category, purpose_list in categories.items():
    print(f"\n{category}:")
    for purpose in sorted(purpose_list):
        print(f"  - {purpose}")

​
5. Smart Purpose Recommendation

Suggest relevant purposes based on video content analysis: 
async function recommendPurposes(videoKeywords) {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/purposes',
    { headers: { 'Authorization': 'YOUR_API_KEY' } }
  );
  const allPurposes = await response.json();

  // Map keywords to relevant purposes
  const keywordMappings = {
    'office': ['Corporate / Business', 'Technology', 'Educational'],
    'wedding': ['Wedding', 'Romantic Comedy', 'Fashion / Beauty'],
    'product': ['Branding / Identity', 'Corporate / Business', 'Shopping'],
    'fitness': ['Aerobics / Fitness', 'Sports', 'Yoga / Relaxation'],
    'travel': ['Road Trip', 'Adventure', 'Landscape / Panorama'],
    'children': ['Children / Preschool', 'Fairytale', 'Animation / Explainer'],
    'tech': ['Technology', 'Futuristic', 'Corporate / Business'],
    'luxury': ['Luxury', 'Fashion / Beauty', 'Regal / Royal'],
    'nature': ['Nature / Beauty', 'Landscape / Panorama', 'Time Lapse']
  };

  const recommendations = new Set();

  videoKeywords.forEach(keyword => {
    const mapped = keywordMappings[keyword.toLowerCase()];
    if (mapped) {
      mapped.forEach(purpose => {
        if (allPurposes.includes(purpose)) {
          recommendations.add(purpose);
        }
      });
    }
  });

  return Array.from(recommendations);
}

// Example usage
const suggestions = await recommendPurposes(['office', 'tech', 'product']);
console.log('Recommended purposes:', suggestions);
// Output: ['Corporate / Business', 'Technology', 'Branding / Identity', ...]

​
6. Filter by Time Period

Create a dedicated filter for era-specific music: 
def get_time_period_purposes(api_key):
    """
    Extract time period-specific purposes for historical or retro content
    """
    headers = {"Authorization": api_key}

    all_purposes = requests.get(
        "https://api.pictory.ai/pictoryapis/v1/music/purposes",
        headers=headers
    ).json()

    time_periods = {
        "Classic Eras": ['50s', '60s', '70s', '80s'],
        "Historical": ['Historical / Period', 'Western / Cowboy'],
        "Retro & Vintage": ['Retro', 'Bollywood'],
        "Future": ['Futuristic', 'Sci-Fi', 'Space / Cosmos']
    }

    filtered_periods = {}
    for category, keywords in time_periods.items():
        filtered_periods[category] = [
            p for p in all_purposes
            if p in keywords
        ]

    return filtered_periods

# Example usage
periods = get_time_period_purposes("YOUR_API_KEY")
for category, purposes in periods.items():
    print(f"{category}: {', '.join(purposes)}")