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

# Get Music Moods

> Retrieve a list of available music moods for filtering and searching music tracks

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

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/music/moods
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## Response

<ResponseField name="moods" type="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.
</ResponseField>

***

## Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    "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"
  ]
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.pictory.ai/pictoryapis/v1/music/moods"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "accept": "application/json"
  }

  response = requests.get(url, headers=headers)
  moods = response.json()

  # Print all available moods
  for mood in moods:
      print(mood)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/moods',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'accept': 'application/json'
      }
    }
  );

  const moods = await response.json();
  console.log('Available moods:', moods);
  ```
</CodeGroup>

## Usage Notes

<Tip>
  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.
</Tip>

<Note>
  **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.
</Note>

## Common Use Cases

### 1. Populate a Mood Selector

Fetch all available moods to populate a dropdown or selection interface in your application:

```python theme={null}
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:

```javascript theme={null}
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:

```python theme={null}
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")
```