Skip to main content
GET
/
pictoryapis
/
v1
/
music
/
genres
/
groups
Get Music Genre Groups
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/music/genres/groups \
  --header 'Authorization: <authorization>'
[
  "Cinematic",
  "Hip Hop",
  "Electronic",
  "Blues & Jazz",
  "Folk",
  "Rock",
  "Country",
  "Dance",
  "World",
  "Orchestral",
  "R&B & Soul",
  "Pop"
]

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 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

​
1. Create Hierarchical Genre Navigation

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
}

​
2. Populate Multi-Level Dropdown

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