Get Music Genre Groups

Overview

Retrieve a list of high-level music genre groups that categorize the more specific genres into broader musical families. Use these genre groups to provide simplified filtering options or to organize genres hierarchically in your application.

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/genres/groups

Request Parameters

Headers

Authorization

string

required

API key for authentication (starts with pictai_)

Authorization: YOUR_API_KEY

Response

genreGroups

array of strings

Array of high-level music genre group names. Each group represents a broad musical category that encompasses multiple specific genres.

Response Examples

[
  "Cinematic",
  "Hip Hop",
  "Electronic",
  "Blues & Jazz",
  "Folk",
  "Rock",
  "Country",
  "Dance",
  "World",
  "Orchestral",
  "R&B & Soul",
  "Pop"
]

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/genres/groups \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

Usage Notes

Genre groups provide a simplified way to categorize music by broad styles. Use them to create top-level navigation or filtering, then combine with the specific genres endpoint for detailed selection.

Hierarchical Organization: These 12 genre groups encompass the 100+ specific genres available through the /music/genres endpoint, providing a logical hierarchy for music organization.

Common Use Cases

Build a two-level genre selection interface with groups and specific genres:

import requests

headers = {"Authorization": "YOUR_API_KEY"}

# Get genre groups
groups = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/genres/groups",
    headers=headers
).json()

# Get all specific genres
all_genres = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/genres",
    headers=headers
).json()

# Create hierarchical structure
genre_hierarchy = {
    "Rock": [g for g in all_genres if 'Rock' in g and 'Folk' not in g],
    "Electronic": [g for g in all_genres if any(x in g for x in ['Electronic', 'House', 'Techno', 'Trance'])],
    "Blues & Jazz": [g for g in all_genres if 'Jazz' in g or 'Blues' in g],
    # ... continue for other groups
}

Create a grouped dropdown selector for better user experience:

const response = await fetch(
  'https://api.pictory.ai/pictoryapis/v1/music/genres/groups',
  { headers: { 'Authorization': 'YOUR_API_KEY' } }
);
const genreGroups = await response.json();

// Create optgroup structure for HTML select
const genreGroupOptions = genreGroups.map(group => ({
  label: group,
  value: group,
  type: 'group'
}));

// Use in HTML
/*
<select>
  <optgroup label="Cinematic">
    <option>Film Score (Orchestral)</option>
    <option>Film Score (Electronic)</option>
    <option>Horror</option>
  </optgroup>
  <optgroup label="Rock">
    <option>Classic Rock</option>
    <option>Indie Rock</option>
    ...
  </optgroup>
</select>
*/

3. Filter Music by Broad Category

Allow users to quickly filter music by general style before refining:

def get_music_by_genre_group(group_name, api_key):
    """
    Get all specific genres within a genre group
    """
    headers = {"Authorization": api_key}

    # Get all genres
    all_genres = requests.get(
        "https://api.pictory.ai/pictoryapis/v1/music/genres",
        headers=headers
    ).json()

    # Map groups to their genres
    group_mapping = {
        "Rock": lambda g: 'Rock' in g and 'Folk' not in g,
        "Electronic": lambda g: any(x in g for x in ['Electronic', 'House', 'Techno', 'Trance', 'Dubstep']),
        "Blues & Jazz": lambda g: 'Jazz' in g or 'Blues' in g,
        "Hip Hop": lambda g: 'Hip Hop' in g or g in ['Trap', 'Gangsta', 'Drill'],
        "World": lambda g: any(x in g for x in ['African', 'Asian', 'Brazilian', 'Cuban', 'Indian']),
        # ... other mappings
    }

    if group_name in group_mapping:
        return [g for g in all_genres if group_mapping[group_name](g)]
    return []

# Example usage
rock_genres = get_music_by_genre_group("Rock", "YOUR_API_KEY")
print(f"Rock genres: {rock_genres}")

4. Build Genre Explorer UI

Create an interactive genre exploration interface:

async function buildGenreExplorer() {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/genres/groups',
    { headers: { 'Authorization': 'YOUR_API_KEY' } }
  );
  const groups = await response.json();

  // Create tabs for each genre group
  const genreExplorer = groups.map(group => ({
    groupName: group,
    displayName: group,
    icon: getIconForGroup(group), // Custom function to assign icons
    color: getColorForGroup(group) // Custom function for color coding
  }));

  return genreExplorer;
}

function getIconForGroup(group) {
  const icons = {
    'Cinematic': '🎬',
    'Hip Hop': '🎤',
    'Electronic': '🎹',
    'Blues & Jazz': '🎷',
    'Rock': '🎸',
    'Orchestral': '🎻',
    'Pop': '🎵',
    'World': '🌍'
  };
  return icons[group] || '🎶';
}

5. Validate and Map User Selections

Ensure user selections map correctly to genre groups:

import requests

def validate_genre_group(user_selection, api_key):
    """
    Validate if a user's selection is a valid genre group
    """
    headers = {"Authorization": api_key}

    valid_groups = requests.get(
        "https://api.pictory.ai/pictoryapis/v1/music/genres/groups",
        headers=headers
    ).json()

    if user_selection in valid_groups:
        return True, f"Valid group: {user_selection}"
    else:
        return False, f"Invalid group. Choose from: {', '.join(valid_groups)}"

# Example
is_valid, message = validate_genre_group("Rock", "YOUR_API_KEY")
print(message)

Genre Group Descriptions

Here’s what each genre group typically encompasses:

Cinematic: Film scores, dramatic compositions, and soundtrack-style music
Hip Hop: Rap, trap, gangsta, and hip hop variations
Electronic: House, techno, trance, dubstep, and electronic dance music
Blues & Jazz: All jazz styles, blues variations, and related genres
Folk: Folk music, singer-songwriter, and acoustic styles
Rock: All rock subgenres from classic to alternative
Country: Country music, bluegrass, and Americana
Dance: Upbeat dance music, disco, and club-oriented tracks
World: International and ethnic music from various cultures
Orchestral: Classical, symphonic, and orchestral compositions
R&B & Soul: Rhythm and blues, soul, and related urban music
Pop: Popular music, contemporary hits, and pop variations

Documentation Index

​Overview

​API Endpoint

​Request Parameters

​Headers

​Response

​Response Examples

​Code Examples

​Usage Notes

​Common Use Cases

​1. Create Hierarchical Genre Navigation

​2. Populate Multi-Level Dropdown

​3. Filter Music by Broad Category

​4. Build Genre Explorer UI

​5. Validate and Map User Selections

​Genre Group Descriptions

Overview

API Endpoint

Request Parameters

Headers

Response

Response Examples

Code Examples

Usage Notes

Common Use Cases

1. Create Hierarchical Genre Navigation

2. Populate Multi-Level Dropdown

3. Filter Music by Broad Category

4. Build Genre Explorer UI

5. Validate and Map User Selections

Genre Group Descriptions