> ## 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 Voiceover Tracks

> Retrieve a comprehensive list of all available AI voiceover voices with their language, accent, and service provider details

## Overview

Retrieve a complete list of all AI voiceover voices available for text-to-speech conversion in your video projects. The endpoint provides detailed information about each voice including accent, gender, language, service provider (AWS Polly or Google WaveNet/Neural2), sample audio URLs, and SSML support categories.

<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/voiceovers/tracks
```

***

## Request Parameters

### Headers

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

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

***

## Response

Returns an array of voice objects with the following properties:

<ResponseField name="accent" type="string">
  The accent or regional variant of the voice (e.g., "American accent", "British accent", "Indian accent")
</ResponseField>

<ResponseField name="category" type="string">
  Voice quality category, typically "standard"
</ResponseField>

<ResponseField name="engine" type="string">
  The text-to-speech engine type (e.g., "neural", "WaveNet", "Neural2", "standard")
</ResponseField>

<ResponseField name="gender" type="string">
  The voice gender: "male" or "female"
</ResponseField>

<ResponseField name="id" type="integer">
  Unique numeric identifier for the voice
</ResponseField>

<ResponseField name="language" type="string">
  Language code in IETF format (e.g., "en-US", "en-GB", "fr-FR", "es-ES")
</ResponseField>

<ResponseField name="name" type="string">
  The display name of the voice (e.g., "Joanna", "Matthew", "Amy")
</ResponseField>

<ResponseField name="sample" type="string (uri)">
  URL to an MP3 sample of the voice for preview
</ResponseField>

<ResponseField name="service" type="string">
  The voice provider service: "aws" (Amazon Polly) or "google" (Google Cloud Text-to-Speech)
</ResponseField>

<ResponseField name="ssmlHelp" type="string (uri)">
  URL to documentation for supported SSML tags for this voice
</ResponseField>

<ResponseField name="ssmlSupportCategory" type="string">
  SSML support level category (A, B, or C) indicating which SSML features are supported
</ResponseField>

<ResponseField name="voice" type="string">
  The technical voice identifier used by the service provider
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    {
      "accent": "American accent",
      "category": "standard",
      "engine": "neural",
      "gender": "female",
      "id": 1001,
      "language": "en-US",
      "name": "Joanna",
      "sample": "https://pictory-static.pictorycontent.com/polly/samples/Joanna_100_sample.mp3",
      "service": "aws",
      "ssmlHelp": "https://docs.pictory.ai/docs/supported-ssml-tags#category-b",
      "ssmlSupportCategory": "B",
      "voice": "Joanna"
    },
    {
      "accent": "British accent",
      "category": "standard",
      "engine": "WaveNet",
      "gender": "female",
      "id": 1034,
      "language": "en-GB",
      "name": "Fiona",
      "sample": "https://pictory-static.pictorycontent.com/google/samples/Fiona_en-GB-Wavenet-A_FEMALE_updated.mp3",
      "service": "google",
      "ssmlHelp": "https://docs.pictory.ai/docs/supported-ssml-tags#category-c",
      "ssmlSupportCategory": "C",
      "voice": "en-GB-Wavenet-A_FEMALE"
    },
    {
      "accent": "Indian accent",
      "category": "standard",
      "engine": "WaveNet",
      "gender": "female",
      "id": 1039,
      "language": "en-IN",
      "name": "Shreya",
      "sample": "https://pictory-static.pictorycontent.com/google/samples/en-IN-Wavenet-A_FEMALE_updated.mp3",
      "service": "google",
      "ssmlHelp": "https://docs.pictory.ai/docs/supported-ssml-tags#category-c",
      "ssmlSupportCategory": "C",
      "voice": "en-IN-Wavenet-A_FEMALE"
    }
  ]
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "code": "INVALID_REQUEST",
    "message": "Bad request"
  }
  ```
</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/voiceovers/tracks \
    --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/voiceovers/tracks"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "accept": "application/json"
  }

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

  # Print voice information
  for voice in voices:
      print(f"{voice['name']} ({voice['accent']}, {voice['gender']})")
      print(f"  Language: {voice['language']}")
      print(f"  Engine: {voice['engine']} ({voice['service']})")
      print(f"  ID: {voice['id']}")
      print(f"  Sample: {voice['sample']}")
      print()
  ```

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

  const voices = await response.json();

  // Print voice information
  voices.forEach(voice => {
    console.log(`${voice.name} (${voice.accent}, ${voice.gender})`);
    console.log(`  Language: ${voice.language}`);
    console.log(`  Engine: ${voice.engine} (${voice.service})`);
    console.log(`  ID: ${voice.id}`);
    console.log(`  Sample: ${voice.sample}`);
    console.log('');
  });
  ```

  ```php PHP theme={null}
  <?php
  // Replace 'YOUR_API_KEY' with your actual API key

  function getVoiceoverTracks($apiKey) {
      $url = 'https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks';

      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Authorization: ' . $apiKey,
          'accept: application/json'
      ]);

      $response = curl_exec($ch);
      $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);

      if ($httpCode !== 200) {
          throw new Exception('Request failed with status ' . $httpCode);
      }

      return json_decode($response, true);
  }

  // Usage
  try {
      $voices = getVoiceoverTracks('YOUR_API_KEY');

      echo "Total voices: " . count($voices) . "\n\n";

      // Print voice information
      foreach ($voices as $voice) {
          echo $voice['name'] . " (" . $voice['accent'] . ", " . $voice['gender'] . ")\n";
          echo "  Language: " . $voice['language'] . "\n";
          echo "  Engine: " . $voice['engine'] . " (" . $voice['service'] . ")\n";
          echo "  ID: " . $voice['id'] . "\n";
          echo "  Sample: " . $voice['sample'] . "\n\n";
      }
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  ?>
  ```

  ```go Go theme={null}
  // Replace "YOUR_API_KEY" with your actual API key

  package main

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

  type VoiceoverTrack struct {
      ID                  int    `json:"id"`
      Name                string `json:"name"`
      Accent              string `json:"accent"`
      Gender              string `json:"gender"`
      Language            string `json:"language"`
      Sample              string `json:"sample"`
      Service             string `json:"service"`
      Engine              string `json:"engine"`
      Category            string `json:"category"`
      Voice               string `json:"voice"`
      SSMLSupportCategory string `json:"ssmlSupportCategory"`
      SSMLHelp            string `json:"ssmlHelp"`
  }

  func getVoiceoverTracks(apiKey string) ([]VoiceoverTrack, error) {
      url := "https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks"

      req, err := http.NewRequest("GET", url, nil)
      if err != nil {
          return nil, err
      }

      req.Header.Set("Authorization", apiKey)
      req.Header.Set("Accept", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          return nil, err
      }
      defer resp.Body.Close()

      body, err := io.ReadAll(resp.Body)
      if err != nil {
          return nil, err
      }

      if resp.StatusCode != http.StatusOK {
          return nil, fmt.Errorf("request failed (status %d): %s", resp.StatusCode, string(body))
      }

      var voices []VoiceoverTrack
      if err := json.Unmarshal(body, &voices); err != nil {
          return nil, err
      }

      return voices, nil
  }

  // Usage
  func main() {
      voices, err := getVoiceoverTracks("YOUR_API_KEY")
      if err != nil {
          panic(err)
      }

      fmt.Printf("Total voices: %d\n\n", len(voices))

      // Print voice information
      for _, voice := range voices {
          fmt.Printf("%s (%s, %s)\n", voice.Name, voice.Accent, voice.Gender)
          fmt.Printf("  Language: %s\n", voice.Language)
          fmt.Printf("  Engine: %s (%s)\n", voice.Engine, voice.Service)
          fmt.Printf("  ID: %d\n", voice.ID)
          fmt.Printf("  Sample: %s\n\n", voice.Sample)
      }
  }
  ```
</CodeGroup>

***

## Usage Notes

<Note>
  **Voice Availability**: The endpoint returns all available voices across multiple languages, accents, and service providers. Filter the results based on your project requirements.
</Note>

<Tip>
  **Sample Audio**: Each voice includes a `sample` URL pointing to an MP3 preview. Use these samples to let users preview voices before selecting.
</Tip>

<Note>
  **SSML Support**: Different voices support different SSML (Speech Synthesis Markup Language) features. Check the `ssmlSupportCategory` and `ssmlHelp` fields to understand what is available for each voice.
</Note>

<Note>
  **Service Providers**:

  * **AWS Polly** voices (`service: "aws"`) use the "neural" or "standard" engine
  * **Google Cloud** voices (`service: "google"`) use "WaveNet" or "Neural2" engines

  Generally, neural/WaveNet voices sound more natural than standard voices.
</Note>

***

## Common Use Cases

### 1. List All Available Voices

Retrieve and display all available voices:

```python theme={null}
import requests

def get_all_voices(api_key):
    """
    Retrieve all available voiceover voices
    """
    url = "https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks"
    headers = {"Authorization": api_key}

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

    if response.status_code == 200:
        voices = response.json()
        print(f"Total available voices: {len(voices)}\n")

        for voice in voices[:10]:  # Show first 10
            print(f"{voice['name']} - {voice['accent']} ({voice['language']})")
            print(f"  Gender: {voice['gender']}, Engine: {voice['engine']}")
            print(f"  Sample: {voice['sample']}")
            print()

        return voices
    else:
        print(f"Error: {response.status_code}")
        return []

# Example usage
voices = get_all_voices("YOUR_API_KEY")
```

### 2. Filter Voices by Language

Get all voices for a specific language:

```javascript theme={null}
async function getVoicesByLanguage(apiKey, languageCode) {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks',
    {
      headers: { 'Authorization': `${apiKey}` }
    }
  );

  const allVoices = await response.json();

  // Filter by language code (e.g., "en-US", "en-GB", "fr-FR")
  const filtered = allVoices.filter(voice => voice.language === languageCode);

  console.log(`Found ${filtered.length} voices for ${languageCode}:`);
  filtered.forEach(voice => {
    console.log(`  - ${voice.name} (${voice.accent}, ${voice.gender})`);
  });

  return filtered;
}

// Example usage
const usVoices = await getVoicesByLanguage('YOUR_API_KEY', 'en-US');
```

### 3. Group Voices by Accent

Organize voices by accent type:

```python theme={null}
from collections import defaultdict
import requests

def group_voices_by_accent(api_key):
    """
    Group voices by their accent
    """
    url = "https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks"
    headers = {"Authorization": api_key}

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

    # Group by accent
    by_accent = defaultdict(list)
    for voice in voices:
        accent = voice.get('accent', 'Unknown')
        by_accent[accent].append(voice)

    # Print grouped results
    for accent, voice_list in sorted(by_accent.items()):
        print(f"\n{accent} ({len(voice_list)} voices):")
        for voice in voice_list[:5]:  # Show first 5 per accent
            print(f"  - {voice['name']} ({voice['gender']}, {voice['engine']})")

    return by_accent

# Example usage
grouped = group_voices_by_accent("YOUR_API_KEY")
```

### 4. Find Best Voice Match

Find voices matching specific criteria:

```javascript theme={null}
async function findVoiceMatch(apiKey, criteria) {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks',
    {
      headers: { 'Authorization': `${apiKey}` }
    }
  );

  const voices = await response.json();

  // Filter by multiple criteria
  const matches = voices.filter(voice => {
    return (
      (!criteria.language || voice.language === criteria.language) &&
      (!criteria.gender || voice.gender === criteria.gender) &&
      (!criteria.accent || voice.accent.toLowerCase().includes(criteria.accent.toLowerCase())) &&
      (!criteria.service || voice.service === criteria.service) &&
      (!criteria.engine || voice.engine === criteria.engine)
    );
  });

  console.log(`Found ${matches.length} matching voices:`);
  matches.forEach(voice => {
    console.log(`  - ${voice.name} (ID: ${voice.id})`);
    console.log(`    ${voice.accent}, ${voice.gender}, ${voice.engine}`);
  });

  return matches;
}

// Example usage - find American female neural voices
const matches = await findVoiceMatch('YOUR_API_KEY', {
  language: 'en-US',
  gender: 'female',
  accent: 'American',
  engine: 'neural'
});
```

### 5. Create Voice Selection UI Data

Prepare voice data for a user interface:

```python theme={null}
import requests

def prepare_voice_ui_data(api_key, language_filter=None):
    """
    Prepare voice data structured for UI dropdowns/selectors
    """
    url = "https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks"
    headers = {"Authorization": api_key}

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

    # Filter by language if specified
    if language_filter:
        voices = [v for v in voices if v['language'] == language_filter]

    # Structure for UI
    ui_data = {
        'languages': {},
        'accents': {},
        'genders': ['male', 'female'],
        'engines': set(),
        'voices': []
    }

    for voice in voices:
        # Collect unique languages
        lang = voice['language']
        if lang not in ui_data['languages']:
            ui_data['languages'][lang] = []
        ui_data['languages'][lang].append(voice['name'])

        # Collect unique accents
        accent = voice['accent']
        if accent not in ui_data['accents']:
            ui_data['accents'][accent] = []
        ui_data['accents'][accent].append(voice['name'])

        # Collect engines
        ui_data['engines'].add(voice['engine'])

        # Create simplified voice entry
        ui_data['voices'].append({
            'id': voice['id'],
            'name': voice['name'],
            'label': f"{voice['name']} ({voice['accent']}, {voice['gender']})",
            'language': voice['language'],
            'accent': voice['accent'],
            'gender': voice['gender'],
            'engine': voice['engine'],
            'service': voice['service'],
            'sample': voice['sample']
        })

    ui_data['engines'] = sorted(list(ui_data['engines']))

    print(f"Prepared UI data for {len(ui_data['voices'])} voices")
    print(f"Languages: {len(ui_data['languages'])}")
    print(f"Accents: {len(ui_data['accents'])}")
    print(f"Engines: {ui_data['engines']}")

    return ui_data

# Example usage
ui_data = prepare_voice_ui_data("YOUR_API_KEY", language_filter="en-US")

# Access structured data
print("\nSample voice entries:")
for voice in ui_data['voices'][:3]:
    print(f"  {voice['label']} - ID: {voice['id']}")
```

### 6. Compare Voice Providers

Analyze and compare voices by service provider:

```python theme={null}
import requests

def compare_voice_providers(api_key):
    """
    Compare voice offerings between AWS and Google
    """
    url = "https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks"
    headers = {"Authorization": api_key}

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

    # Separate by provider
    aws_voices = [v for v in voices if v['service'] == 'aws']
    google_voices = [v for v in voices if v['service'] == 'google']

    print("Voice Provider Comparison:")
    print(f"\nAWS Polly: {len(aws_voices)} voices")
    print(f"  Engines: {set(v['engine'] for v in aws_voices)}")
    print(f"  Languages: {len(set(v['language'] for v in aws_voices))}")
    print(f"  Male: {len([v for v in aws_voices if v['gender'] == 'male'])}")
    print(f"  Female: {len([v for v in aws_voices if v['gender'] == 'female'])}")

    print(f"\nGoogle Cloud: {len(google_voices)} voices")
    print(f"  Engines: {set(v['engine'] for v in google_voices)}")
    print(f"  Languages: {len(set(v['language'] for v in google_voices))}")
    print(f"  Male: {len([v for v in google_voices if v['gender'] == 'male'])}")
    print(f"  Female: {len([v for v in google_voices if v['gender'] == 'female'])}")

    # Language overlap
    aws_langs = set(v['language'] for v in aws_voices)
    google_langs = set(v['language'] for v in google_voices)
    common_langs = aws_langs & google_langs

    print(f"\nLanguages available in both: {len(common_langs)}")
    print(f"AWS only: {len(aws_langs - google_langs)}")
    print(f"Google only: {len(google_langs - aws_langs)}")

    return {
        'aws': aws_voices,
        'google': google_voices,
        'stats': {
            'aws_count': len(aws_voices),
            'google_count': len(google_voices),
            'common_languages': list(common_langs)
        }
    }

# Example usage
comparison = compare_voice_providers("YOUR_API_KEY")
```

***

## Best Practices

### Voice Selection

1. **Preview Before Use**: Always use the `sample` URLs to let users preview voices before selection
2. **Filter by Language**: Filter voices by the target language to present relevant options to users
3. **Consider Accent**: Match voice accent to your target audience (American, British, Indian, etc.)
4. **Engine Quality**: Neural and WaveNet voices generally sound more natural than standard voices
5. **SSML Support**: Check `ssmlSupportCategory` if you need advanced SSML features like custom pronunciation or emphasis

### Performance Tips

* **Cache Voice List**: Cache the voice list for 24 hours as it rarely changes
* **Client-Side Filtering**: Fetch all voices once and filter on the client side
* **Lazy Load Samples**: Only load audio samples when users preview them
* **Index by ID**: Create an ID-to-voice mapping for quick lookups

### Common Voice Categories

**SSML Support Categories:**

* **Category A**: Basic SSML support (standard engines)
* **Category B**: Advanced SSML support (AWS neural voices)
* **Category C**: Full SSML support (Google WaveNet/Neural2 voices)

**Engine Types:**

* **standard**: Basic quality, faster processing
* **neural**: High quality, natural-sounding (AWS)
* **WaveNet**: Premium quality (Google)
* **Neural2**: Latest generation neural voices (Google)

### Language Coverage

The API provides voices for multiple languages including:

* English variants: en-US, en-GB, en-AU, en-IN, en-NZ, en-ZA
* European: fr-FR, fr-CA, de-DE, de-AT, it-IT, es-ES, nl-NL, nl-BE, pt-PT, pt-BR
* And many more...