Skip to main content
POST
https://api.pictory.ai
/
pictoryapis
/
v1
/
music
/
search
Search Music Tracks
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v1/music/search \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "page": 123,
  "pageSize": 123,
  "sort": "<string>",
  "query": "<string>",
  "genreGroup": {},
  "notGenreGroup": {},
  "genre": {},
  "notGenre": {},
  "mood": {},
  "notMood": {},
  "instrument": {},
  "notInstrument": {},
  "purpose": {},
  "notPurpose": {},
  "minDuration": 123,
  "maxDuration": 123
}
'
{
  "items": [
    {
      "id": 279,
      "title": "Bio Journey",
      "audioUrl": "https://tracks.melod.ie/track_versions/570/MEL142_06_1_Bio_Journey_%28Full%29_David_Godfrey_stream.mp3?1736295063",
      "duration": 161,
      "genres": ["Downtempo"],
      "instruments": [
        "Bass - Electric",
        "Bass - Synth",
        "Guitar - Electric",
        "Keyboard",
        "Percussion",
        "Synth"
      ],
      "moods": [
        "Calm / Serene",
        "Ethereal / Airy",
        "Feel Good",
        "Gentle / Soft",
        "Happy / Bright",
        "Hopeful / Optimistic",
        "Quirky / Kitsch",
        "Smooth / Flowing",
        "Sweet / Warm",
        "Upbeat / Cheerful"
      ],
      "purposes": [
        "Atmospheric",
        "Corporate / Business",
        "Mystery / Tension",
        "Real Estate",
        "Simple / Minimal",
        "Technology",
        "Time Lapse"
      ]
    },
    {
      "id": 165,
      "title": "Dusty Road Trip",
      "audioUrl": "https://tracks.melod.ie/track_versions/316/MEL119_01_1_Dusty_Road_Trip_%28Full%29_Marcos_H_Bolanos_stream.mp3?1725242063",
      "duration": 147,
      "genres": ["Country Rock", "Electric Blues"],
      "instruments": [
        "Bass - Electric",
        "Drum Kit",
        "Guitar - Acoustic",
        "Guitar - Electric",
        "Harmonica",
        "Shaker"
      ],
      "moods": [
        "Celebration",
        "Confident",
        "Energetic / Lively",
        "Exciting / Rousing",
        "Feel Good",
        "Fun",
        "Grooving",
        "Happy / Bright",
        "Hopeful / Optimistic",
        "Joyful",
        "Playful / Whimsical",
        "Punchy",
        "Rowdy / Boisterous",
        "Sweet / Warm",
        "Upbeat / Cheerful"
      ],
      "purposes": [
        "Adventure",
        "Nature / Beauty",
        "Road Trip",
        "Western / Cowboy"
      ]
    }
  ],
  "totalItems": 1541,
  "totalPages": 78,
  "currentPage": 1
}

Overview

Search through Pictory’s music library to find tracks that match your specific criteria. Filter by multiple attributes including genre groups, genres, moods, instruments, purposes, duration, and search queries. Results include streaming URLs, metadata, and comprehensive categorization data.
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

POST https://api.pictory.ai/pictoryapis/v1/music/search

Request Parameters

Headers

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

Body Parameters

page
integer
default:"1"
Page number for pagination (must be ≥ 1)
pageSize
integer
default:"100"
Number of results per page (must be between 20 and 100)
sort
string
default:"latest"
Sort order for resultsOptions:
  • latest - Sort by most recently added tracks
  • shuffle - Randomize the order of results
  • featured - Sort by featured/curated tracks
query
string
Search query to filter tracks by keywords in title or description
genreGroup
array of strings
Filter by genre groups (e.g., [“Rock”, “Electronic”]). Use the Get Music Genre Groups endpoint to retrieve valid values.
notGenreGroup
array of strings
Exclude specific genre groups from results
genre
array of strings
Filter by specific genres (e.g., [“Indie Rock”, “Techno”]). Use the Get Music Genres endpoint to retrieve valid values.
notGenre
array of strings
Exclude specific genres from results
mood
array of strings
Filter by moods (e.g., [“Happy / Bright”, “Energetic / Lively”]). Use the Get Music Moods endpoint to retrieve valid values.
notMood
array of strings
Exclude specific moods from results
instrument
array of strings
Filter by instruments (e.g., [“Piano”, “Guitar - Acoustic”]). Use the Get Music Instruments endpoint to retrieve valid values.
notInstrument
array of strings
Exclude specific instruments from results
purpose
array of strings
Filter by purposes (e.g., [“Corporate / Business”, “Wedding”]). Use the Get Music Purposes endpoint to retrieve valid values.
notPurpose
array of strings
Exclude specific purposes from results
minDuration
integer
Minimum track duration in seconds
maxDuration
integer
Maximum track duration in seconds

Response

items
array of objects
Array of music track objects matching the search criteria
totalItems
integer
Total number of tracks matching the search criteria across all pages
totalPages
integer
Total number of pages available for the search results
currentPage
integer
Current page number in the result set

Response Examples

{
  "items": [
    {
      "id": 279,
      "title": "Bio Journey",
      "audioUrl": "https://tracks.melod.ie/track_versions/570/MEL142_06_1_Bio_Journey_%28Full%29_David_Godfrey_stream.mp3?1736295063",
      "duration": 161,
      "genres": ["Downtempo"],
      "instruments": [
        "Bass - Electric",
        "Bass - Synth",
        "Guitar - Electric",
        "Keyboard",
        "Percussion",
        "Synth"
      ],
      "moods": [
        "Calm / Serene",
        "Ethereal / Airy",
        "Feel Good",
        "Gentle / Soft",
        "Happy / Bright",
        "Hopeful / Optimistic",
        "Quirky / Kitsch",
        "Smooth / Flowing",
        "Sweet / Warm",
        "Upbeat / Cheerful"
      ],
      "purposes": [
        "Atmospheric",
        "Corporate / Business",
        "Mystery / Tension",
        "Real Estate",
        "Simple / Minimal",
        "Technology",
        "Time Lapse"
      ]
    },
    {
      "id": 165,
      "title": "Dusty Road Trip",
      "audioUrl": "https://tracks.melod.ie/track_versions/316/MEL119_01_1_Dusty_Road_Trip_%28Full%29_Marcos_H_Bolanos_stream.mp3?1725242063",
      "duration": 147,
      "genres": ["Country Rock", "Electric Blues"],
      "instruments": [
        "Bass - Electric",
        "Drum Kit",
        "Guitar - Acoustic",
        "Guitar - Electric",
        "Harmonica",
        "Shaker"
      ],
      "moods": [
        "Celebration",
        "Confident",
        "Energetic / Lively",
        "Exciting / Rousing",
        "Feel Good",
        "Fun",
        "Grooving",
        "Happy / Bright",
        "Hopeful / Optimistic",
        "Joyful",
        "Playful / Whimsical",
        "Punchy",
        "Rowdy / Boisterous",
        "Sweet / Warm",
        "Upbeat / Cheerful"
      ],
      "purposes": [
        "Adventure",
        "Nature / Beauty",
        "Road Trip",
        "Western / Cowboy"
      ]
    }
  ],
  "totalItems": 1541,
  "totalPages": 78,
  "currentPage": 1
}

Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v1/music/search \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'accept: application/json' \
  --data '{
    "page": 1,
    "pageSize": 20,
    "query": "upbeat",
    "mood": ["Happy / Bright", "Energetic / Lively"],
    "purpose": ["Corporate / Business"]
  }' | python -m json.tool

Usage Notes

Use the negation filters (notGenre, notMood, notInstrument, notPurpose) to exclude specific attributes and refine your search results. This is particularly useful for finding tracks that match a mood but exclude certain instruments or genres.
Pagination Requirements: The pageSize parameter must be between 20 and 100. If you need fewer results, simply use the first N items from the response array.
Filter Validation: All filter values (genres, moods, instruments, purposes) are case-sensitive and must match exactly as returned by their respective list endpoints. Use the dedicated GET endpoints to retrieve valid filter values before searching.

Common Use Cases

1. Search by Keyword

Find tracks matching a specific search term:
import requests

url = "https://api.pictory.ai/pictoryapis/v1/music/search"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Search for "corporate" themed music
payload = {
    "page": 1,
    "pageSize": 20,
    "query": "corporate"
}

response = requests.post(url, json=payload, headers=headers)
tracks = response.json()

print(f"Found {tracks['totalItems']} corporate tracks")

2. Filter by Multiple Criteria

Combine multiple filters for precise results:
const searchTracks = async (filters) => {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        page: 1,
        pageSize: 20,
        genre: ['Indie Rock', 'Pop Rock'],
        mood: ['Energetic / Lively', 'Happy / Bright'],
        instrument: ['Guitar - Electric', 'Drum Kit'],
        purpose: ['Corporate / Business', 'Branding / Identity'],
        minDuration: 60,
        maxDuration: 180
      })
    }
  );

  const data = await response.json();
  return data.items;
};

// Get energetic rock tracks suitable for corporate use
const tracks = await searchTracks();
console.log(`Found ${tracks.length} matching tracks`);

3. Exclude Unwanted Attributes

Use negation filters to refine results:
# Find upbeat music WITHOUT specific moods or instruments
payload = {
    "page": 1,
    "pageSize": 20,
    "mood": ["Upbeat / Cheerful", "Energetic / Lively"],
    "notMood": ["Dark / Brooding", "Sad / Melancholic"],
    "notInstrument": ["Violin / Viola", "Cello"],
    "purpose": ["Corporate / Business"]
}

response = requests.post(
    "https://api.pictory.ai/pictoryapis/v1/music/search",
    json=payload,
    headers={"Authorization": "YOUR_API_KEY", "Content-Type": "application/json"}
)

tracks = response.json()
print(f"Found {tracks['totalItems']} upbeat corporate tracks without strings")
Find tracks within a specific duration range:
def find_tracks_by_duration(min_sec, max_sec, purpose=None):
    """
    Find music tracks within a specific duration range
    """
    payload = {
        "page": 1,
        "pageSize": 50,
        "minDuration": min_sec,
        "maxDuration": max_sec
    }

    if purpose:
        payload["purpose"] = [purpose]

    response = requests.post(
        "https://api.pictory.ai/pictoryapis/v1/music/search",
        json=payload,
        headers={
            "Authorization": "YOUR_API_KEY",
            "Content-Type": "application/json"
        }
    )

    return response.json()

# Find short corporate tracks (30-60 seconds)
short_tracks = find_tracks_by_duration(30, 60, "Corporate / Business")
print(f"Found {short_tracks['totalItems']} tracks between 30-60 seconds")

# Find longer background tracks (3-5 minutes)
long_tracks = find_tracks_by_duration(180, 300)
print(f"Found {long_tracks['totalItems']} tracks between 3-5 minutes")

5. Paginate Through Results

Retrieve all pages of search results:
async function getAllTracks(searchCriteria) {
  let allTracks = [];
  let currentPage = 1;
  let totalPages = 1;

  while (currentPage <= totalPages) {
    const response = await fetch(
      'https://api.pictory.ai/pictoryapis/v1/music/search',
      {
        method: 'POST',
        headers: {
          'Authorization': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          ...searchCriteria,
          page: currentPage,
          pageSize: 100 // Maximum page size
        })
      }
    );

    const data = await response.json();
    allTracks = allTracks.concat(data.items);
    totalPages = data.totalPages;
    currentPage++;

    console.log(`Retrieved page ${currentPage - 1} of ${totalPages}`);
  }

  return allTracks;
}

// Get all piano tracks
const allPianoTracks = await getAllTracks({
  instrument: ['Piano']
});
console.log(`Total piano tracks: ${allPianoTracks.length}`);

6. Sort and Filter Combined

Use sorting with filters for optimal results:
# Get latest upbeat corporate tracks
payload = {
    "page": 1,
    "pageSize": 20,
    "sort": "latest",
    "mood": ["Upbeat / Cheerful", "Energetic / Lively"],
    "purpose": ["Corporate / Business", "Branding / Identity"]
}

response = requests.post(
    "https://api.pictory.ai/pictoryapis/v1/music/search",
    json=payload,
    headers={
        "Authorization": "YOUR_API_KEY",
        "Content-Type": "application/json"
    }
)

latest_tracks = response.json()

# Get featured tracks for variety
payload["sort"] = "featured"
response = requests.post(
    "https://api.pictory.ai/pictoryapis/v1/music/search",
    json=payload,
    headers={
        "Authorization": "YOUR_API_KEY",
        "Content-Type": "application/json"
    }
)

featured_tracks = response.json()

7. Build a Smart Music Recommender

Create recommendations based on video content:
def recommend_music_for_video(video_keywords, video_duration, video_type):
    """
    Recommend music based on video characteristics
    """
    # Map video type to purpose
    purpose_mapping = {
        "corporate": ["Corporate / Business", "Branding / Identity"],
        "wedding": ["Wedding", "Romantic Comedy"],
        "travel": ["Adventure", "Road Trip", "Nature / Beauty"],
        "tech": ["Technology", "Futuristic"],
        "kids": ["Children / Preschool", "Educational"]
    }

    # Determine mood from keywords
    mood_mapping = {
        "happy": ["Happy / Bright", "Joyful", "Upbeat / Cheerful"],
        "calm": ["Calm / Serene", "Gentle / Soft"],
        "energetic": ["Energetic / Lively", "Exciting / Rousing"],
        "dramatic": ["Dramatic", "Intense / Hard"]
    }

    purposes = purpose_mapping.get(video_type, [])
    moods = []
    for keyword in video_keywords:
        if keyword in mood_mapping:
            moods.extend(mood_mapping[keyword])

    # Search with calculated criteria
    payload = {
        "page": 1,
        "pageSize": 20,
        "sort": "featured",
        "purpose": purposes,
        "mood": moods,
        "minDuration": int(video_duration * 0.8),  # At least 80% of video duration
        "maxDuration": int(video_duration * 1.2)   # At most 120% of video duration
    }

    response = requests.post(
        "https://api.pictory.ai/pictoryapis/v1/music/search",
        json=payload,
        headers={
            "Authorization": "YOUR_API_KEY",
            "Content-Type": "application/json"
        }
    )

    return response.json()

# Example: Find music for 90-second corporate video with happy theme
recommendations = recommend_music_for_video(
    video_keywords=["happy", "energetic"],
    video_duration=90,
    video_type="corporate"
)

print(f"Recommended {len(recommendations['items'])} tracks")
for track in recommendations['items'][:5]:
    print(f"- {track['title']} ({track['duration']}s)")

8. Genre Group Exploration

Search by high-level genre groups and drill down:
async function exploreGenreGroup(genreGroup) {
  // First, search by genre group
  const groupResponse = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        page: 1,
        pageSize: 20,
        genreGroup: [genreGroup],
        sort: 'featured'
      })
    }
  );

  const groupTracks = await groupResponse.json();

  // Analyze genres within this group
  const genresFound = new Set();
  groupTracks.items.forEach(track => {
    track.genres.forEach(genre => genresFound.add(genre));
  });

  console.log(`Genre Group: ${genreGroup}`);
  console.log(`Total tracks: ${groupTracks.totalItems}`);
  console.log(`Specific genres found: ${Array.from(genresFound).join(', ')}`);

  return {
    totalTracks: groupTracks.totalItems,
    genres: Array.from(genresFound),
    sampleTracks: groupTracks.items
  };
}

// Explore Electronic music
const electronicMusic = await exploreGenreGroup('Electronic');