Skip to main content
GET
https://api.pictory.ai
/
pictoryapis
/
v1
/
music
/
moods
Get Music Moods
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/music/moods \
  --header 'Authorization: <authorization>'
[
  "Passionate",
  "Funny / Silly",
  "Gentle / Soft",
  "Raw / Gritty",
  "Intense / Hard",
  "Hopeful / Optimistic",
  "Uplifting / Inspiring",
  "Sensual / Intimate",
  "Ominous / Looming",
  "Sad / Melancholic",
  "Sweet / Warm",
  "Patriotic",
  "Beautiful",
  "Dramatic",
  "Epic",
  "Exotic",
  "Romantic",
  "Abstract",
  "Bittersweet",
  "Bouncy",
  "Cheesy",
  "Emotional",
  "Fun",
  "Funky",
  "Haunting",
  "Joyful",
  "Moody",
  "Pulsing",
  "Punchy",
  "Swaggering",
  "Feel Good",
  "Majestic",
  "Grooving",
  "Playful / Whimsical",
  "Smooth / Flowing",
  "Cool",
  "Mysterious",
  "Sneaky",
  "Jazzy",
  "Driving",
  "Anthemic",
  "Neutral",
  "Aggressive",
  "Ethereal / Airy",
  "Happy / Bright",
  "Suspense / Tense",
  "Powerful / Strong",
  "Rowdy / Boisterous",
  "Dark / Brooding",
  "Building / Escalating",
  "Calm / Serene",
  "Quirky / Kitsch",
  "Celebration",
  "Upbeat / Cheerful",
  "Laid-back",
  "Confident",
  "Shimmering",
  "Sophisticated",
  "Energetic / Lively",
  "Exciting / Rousing",
  "Nostalgic / Reflective",
  "Strange / Weird",
  "Anxious / Fear"
]

​
Overview

Retrieve a comprehensive list of available music moods for filtering and searching music tracks. Use these mood values to find music that precisely matches the emotional tone and atmosphere 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/moods

​
Request Parameters

​
Headers

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

​
Response

​
moods
array of strings
Array of available music mood names. Each mood represents a distinct emotional or tonal quality for filtering music tracks in search queries.

​
Response Examples

[
  "Passionate",
  "Funny / Silly",
  "Gentle / Soft",
  "Raw / Gritty",
  "Intense / Hard",
  "Hopeful / Optimistic",
  "Uplifting / Inspiring",
  "Sensual / Intimate",
  "Ominous / Looming",
  "Sad / Melancholic",
  "Sweet / Warm",
  "Patriotic",
  "Beautiful",
  "Dramatic",
  "Epic",
  "Exotic",
  "Romantic",
  "Abstract",
  "Bittersweet",
  "Bouncy",
  "Cheesy",
  "Emotional",
  "Fun",
  "Funky",
  "Haunting",
  "Joyful",
  "Moody",
  "Pulsing",
  "Punchy",
  "Swaggering",
  "Feel Good",
  "Majestic",
  "Grooving",
  "Playful / Whimsical",
  "Smooth / Flowing",
  "Cool",
  "Mysterious",
  "Sneaky",
  "Jazzy",
  "Driving",
  "Anthemic",
  "Neutral",
  "Aggressive",
  "Ethereal / Airy",
  "Happy / Bright",
  "Suspense / Tense",
  "Powerful / Strong",
  "Rowdy / Boisterous",
  "Dark / Brooding",
  "Building / Escalating",
  "Calm / Serene",
  "Quirky / Kitsch",
  "Celebration",
  "Upbeat / Cheerful",
  "Laid-back",
  "Confident",
  "Shimmering",
  "Sophisticated",
  "Energetic / Lively",
  "Exciting / Rousing",
  "Nostalgic / Reflective",
  "Strange / Weird",
  "Anxious / Fear"
]

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

​
Usage Notes

Use these exact mood values when searching for music to ensure valid selection from available categories. Mood values are case-sensitive and must match exactly as returned by this endpoint.
Mood Categories: The API provides over 60 distinct mood options spanning a comprehensive range of emotional tones—from “Calm / Serene” to “Intense / Hard”—enabling precise alignment of music with your video’s emotional narrative.

​
Common Use Cases

​
1. Populate a Mood Selector

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

# Use moods to populate UI dropdown
mood_options = [{"label": mood, "value": mood} for mood in moods]

​
2. Categorize Moods by Emotion

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

// Filter moods by type
const happyMoods = moods.filter(m =>
  m.includes('Happy') || m.includes('Joyful') || m.includes('Cheerful')
);
const calmMoods = moods.filter(m =>
  m.includes('Calm') || m.includes('Serene') || m.includes('Gentle')
);

​
3. Validate User Input

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

user_mood = "Uplifting / Inspiring"
if user_mood in valid_moods:
    # Proceed with music search using this mood
    print(f"Searching for {user_mood} music...")
else:
    print("Invalid mood selected")