Skip to main content
GET
/
pictoryapis
/
v1
/
music
/
instruments
Get Music Instruments
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/music/instruments \
  --header 'Authorization: <authorization>'
import requests

url = "https://api.pictory.ai/pictoryapis/v1/music/instruments"

headers = {"Authorization": "<authorization>"}

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

print(response.text)
const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pictory.ai/pictoryapis/v1/music/instruments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v1/music/instruments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pictory.ai/pictoryapis/v1/music/instruments"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.pictory.ai/pictoryapis/v1/music/instruments")
  .header("Authorization", "<authorization>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.pictory.ai/pictoryapis/v1/music/instruments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body
[
  "Vocal - Sounds / FX",
  "Banjo",
  "Bass - Electric",
  "Bassoon",
  "Brass",
  "Celeste",
  "Cello",
  "Clarinet",
  "Dobro",
  "Dulcimer",
  "Ethnic",
  "Finger Snaps",
  "Flugelhorn",
  "Gamelan",
  "Glockenspiel",
  "Harmonica",
  "Harp",
  "Harpsichord",
  "Jaw Harp",
  "Kalimba",
  "Kazoo",
  "Keyboard",
  "Lute",
  "Mandolin",
  "Marimba",
  "Orchestra",
  "Organ",
  "Piano",
  "Recorder",
  "Rhodes",
  "Saxophone",
  "Scratching",
  "Sitar",
  "Steel Drums",
  "Strings",
  "Theremin",
  "Trombone",
  "Tuba",
  "Ukulele",
  "Vibraphone",
  "Vocoder",
  "Whistling",
  "Woodwind",
  "Xylophone",
  "Guitar - Acoustic",
  "Bagpipes / Celtic Pipes",
  "Bells / Tubular Bells",
  "Bass - Double",
  "Guitar - Electric",
  "French Horn",
  "Hammond Organ",
  "Oboe / Cor Anglais",
  "Orchestral Noise",
  "Pan Pipes",
  "Sleigh Bells",
  "Synth",
  "Tambourine",
  "Vocal - Choir",
  "Duduk",
  "Congas",
  "Tabla",
  "Melodica",
  "Saz",
  "Clavinet",
  "Pizzicato",
  "Guitar - Slide",
  "Guitar - Spanish",
  "Stompbox",
  "Castanets",
  "Music Box",
  "Bass - Synth",
  "Shaker",
  "Guitar - Lap & Pedal",
  "Koto",
  "Cowbell",
  "Electronic Drums",
  "Shakuhachi",
  "Shamisen",
  "Vinyl Crackle",
  "Hand Claps",
  "Flute / Piccolo",
  "Trumpet / Cornet",
  "Violin / Viola",
  "Whistles / Tin / Penny",
  "Erhu",
  "FX (Heartbeat)",
  "FX (Clock)",
  "FX (Reverse)",
  "Accordion / Bandoneon",
  "Cuatro",
  "Hand Drum",
  "Vocal - Lyrics",
  "Percussion",
  "Drum Kit",
  "Drum Kit - Brushes",
  "Didgeridoo"
]

{
  "message": "Unauthorized"
}

​
Overview

Retrieve a comprehensive list of available music instruments for filtering and searching music tracks. Use these instrument values to find music featuring specific instrumental sounds that complement 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/instruments

​
Request Parameters

​
Headers

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

​
Response

​
instruments
array of strings
Array of available music instrument names. Each instrument represents a distinct sound or instrumental category for filtering music tracks in search queries.

​
Response Examples

[
  "Vocal - Sounds / FX",
  "Banjo",
  "Bass - Electric",
  "Bassoon",
  "Brass",
  "Celeste",
  "Cello",
  "Clarinet",
  "Dobro",
  "Dulcimer",
  "Ethnic",
  "Finger Snaps",
  "Flugelhorn",
  "Gamelan",
  "Glockenspiel",
  "Harmonica",
  "Harp",
  "Harpsichord",
  "Jaw Harp",
  "Kalimba",
  "Kazoo",
  "Keyboard",
  "Lute",
  "Mandolin",
  "Marimba",
  "Orchestra",
  "Organ",
  "Piano",
  "Recorder",
  "Rhodes",
  "Saxophone",
  "Scratching",
  "Sitar",
  "Steel Drums",
  "Strings",
  "Theremin",
  "Trombone",
  "Tuba",
  "Ukulele",
  "Vibraphone",
  "Vocoder",
  "Whistling",
  "Woodwind",
  "Xylophone",
  "Guitar - Acoustic",
  "Bagpipes / Celtic Pipes",
  "Bells / Tubular Bells",
  "Bass - Double",
  "Guitar - Electric",
  "French Horn",
  "Hammond Organ",
  "Oboe / Cor Anglais",
  "Orchestral Noise",
  "Pan Pipes",
  "Sleigh Bells",
  "Synth",
  "Tambourine",
  "Vocal - Choir",
  "Duduk",
  "Congas",
  "Tabla",
  "Melodica",
  "Saz",
  "Clavinet",
  "Pizzicato",
  "Guitar - Slide",
  "Guitar - Spanish",
  "Stompbox",
  "Castanets",
  "Music Box",
  "Bass - Synth",
  "Shaker",
  "Guitar - Lap & Pedal",
  "Koto",
  "Cowbell",
  "Electronic Drums",
  "Shakuhachi",
  "Shamisen",
  "Vinyl Crackle",
  "Hand Claps",
  "Flute / Piccolo",
  "Trumpet / Cornet",
  "Violin / Viola",
  "Whistles / Tin / Penny",
  "Erhu",
  "FX (Heartbeat)",
  "FX (Clock)",
  "FX (Reverse)",
  "Accordion / Bandoneon",
  "Cuatro",
  "Hand Drum",
  "Vocal - Lyrics",
  "Percussion",
  "Drum Kit",
  "Drum Kit - Brushes",
  "Didgeridoo"
]

{
  "message": "Unauthorized"
}

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

import requests

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

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

# Print all available instruments
for instrument in instruments:
    print(instrument)

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

const instruments = await response.json();
console.log('Available instruments:', instruments);

​
Usage Notes

Use these exact instrument values when searching for music to ensure valid selection from available categories. Instrument values are case-sensitive and must match exactly as returned by this endpoint.
Instrument Diversity: The API provides 95 distinct instrument options spanning traditional acoustic instruments (Piano, Guitar, Violin), electronic sounds (Synth, Vocoder, Electronic Drums), world instruments (Sitar, Koto, Didgeridoo), and special effects (FX Heartbeat, Vinyl Crackle, Hand Claps), enabling precise matching of instrumental sound to your video’s sonic requirements.

​
Common Use Cases

​
1. Populate an Instrument Selector

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

# Use instruments to populate UI dropdown
instrument_options = [{"label": instrument, "value": instrument} for instrument in instruments]

​
2. Categorize Instruments by Type

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

// Categorize instruments by type
const stringInstruments = instruments.filter(i =>
  i.includes('Guitar') || i.includes('Violin') || i.includes('Cello') ||
  i.includes('Strings') || i.includes('Harp') || i.includes('Banjo')
);

const brassInstruments = instruments.filter(i =>
  i.includes('Trumpet') || i.includes('Trombone') || i.includes('French Horn') ||
  i.includes('Tuba') || i.includes('Brass')
);

const percussionInstruments = instruments.filter(i =>
  i.includes('Drum') || i.includes('Percussion') || i.includes('Tambourine') ||
  i.includes('Cowbell') || i.includes('Shaker')
);

const vocalInstruments = instruments.filter(i =>
  i.includes('Vocal') || i.includes('Choir')
);

const worldInstruments = instruments.filter(i =>
  ['Sitar', 'Koto', 'Tabla', 'Didgeridoo', 'Duduk', 'Erhu', 'Shamisen'].includes(i)
);

​
3. Validate User Input

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

user_instrument = "Piano"
if user_instrument in valid_instruments:
    # Proceed with music search using this instrument
    print(f"Searching for {user_instrument} music...")
else:
    print("Invalid instrument selected")

​
4. Build Instrument Filter Interface

Create a multi-category instrument filter for advanced music search: 
import requests

instruments = requests.get(
    "https://api.pictory.ai/pictoryapis/v1/music/instruments",
    headers={"Authorization": "YOUR_API_KEY"}
).json()

# Organize by instrument families
categories = {
    "Strings": [i for i in instruments if any(x in i for x in ['Guitar', 'Violin', 'Viola', 'Cello', 'Strings', 'Bass', 'Harp', 'Banjo', 'Ukulele', 'Mandolin'])],
    "Brass": [i for i in instruments if any(x in i for x in ['Trumpet', 'Trombone', 'French Horn', 'Tuba', 'Brass', 'Flugelhorn'])],
    "Woodwind": [i for i in instruments if any(x in i for x in ['Flute', 'Clarinet', 'Oboe', 'Saxophone', 'Bassoon', 'Woodwind', 'Recorder'])],
    "Percussion": [i for i in instruments if any(x in i for x in ['Drum', 'Percussion', 'Tambourine', 'Cowbell', 'Shaker', 'Congas', 'Tabla'])],
    "Keyboard": [i for i in instruments if any(x in i for x in ['Piano', 'Keyboard', 'Organ', 'Rhodes', 'Synth', 'Harpsichord', 'Clavinet'])],
    "Vocal": [i for i in instruments if 'Vocal' in i or 'Choir' in i],
    "World": [i for i in instruments if any(x in i for x in ['Sitar', 'Koto', 'Didgeridoo', 'Duduk', 'Erhu', 'Shamisen', 'Tabla', 'Bagpipes', 'Pan Pipes'])],
    "Electronic": [i for i in instruments if any(x in i for x in ['Synth', 'Electronic', 'Vocoder', 'Scratching'])],
    "FX": [i for i in instruments if 'FX' in i or i in ['Vinyl Crackle', 'Hand Claps', 'Finger Snaps']]
}

for category, instrument_list in categories.items():
    print(f"\n{category}:")
    for instrument in sorted(instrument_list):
        print(f"  - {instrument}")

​
5. Search by Multiple Instruments

Combine instrument filtering with other search criteria: 
async function searchMusicByInstrument(instruments, mood, genre) {
  // Get valid instruments first
  const validInstrumentsResponse = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/music/instruments',
    { headers: { 'Authorization': 'YOUR_API_KEY' } }
  );
  const validInstruments = await validInstrumentsResponse.json();

  // Validate requested instruments
  const validatedInstruments = instruments.filter(i =>
    validInstruments.includes(i)
  );

  if (validatedInstruments.length === 0) {
    console.error('No valid instruments selected');
    return [];
  }

  console.log(`Searching for ${mood} ${genre} music with instruments: ${validatedInstruments.join(', ')}`);

  // Use validated instruments in your music search
  // (This would integrate with a music search endpoint)
}

// Example usage
await searchMusicByInstrument(
  ['Piano', 'Violin / Viola', 'Cello'],
  'Calm / Serene',
  'Classical Period'
);