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

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

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

<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/instruments
```

***

## Request Parameters

### Headers

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

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

***

## Response

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

***

## Response Examples

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

  ```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/instruments \
    --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/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)
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

## Usage Notes

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

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

## Common Use Cases

### 1. Populate an Instrument Selector

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

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

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

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

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

```javascript theme={null}
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'
);
```