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

# Using ElevenLabs Voices

> Use any ElevenLabs voice in your Pictory videos: pass the voice ID and it is automatically discovered and added to your library

This guide shows you how to use any voice from the ElevenLabs catalog in your Pictory videos. Simply pass the ElevenLabs voice ID as the `speaker` value; Pictory will automatically discover and add the voice to your library.

## How It Works

<Steps>
  <Step title="Find a voice on ElevenLabs">
    Browse the [ElevenLabs Voice Library](https://elevenlabs.io/voice-library) and copy the voice ID of any voice you want to use.
  </Step>

  <Step title="Pass the voice ID as speaker">
    Use the ElevenLabs voice ID directly in your API request as the `speaker` value.
  </Step>

  <Step title="Automatic discovery">
    If the voice is not already in your Pictory library, it will be automatically discovered and added from ElevenLabs. No manual setup required.
  </Step>
</Steps>

## Finding an ElevenLabs Voice ID

You can find voice IDs from:

1. **ElevenLabs Voice Library**: Browse voices at [elevenlabs.io/voice-library](https://elevenlabs.io/voice-library). The voice ID is shown on each voice's detail page.
2. **ElevenLabs API**: Use the [ElevenLabs Voices API](https://api.elevenlabs.io/v1/voices) to list available voices programmatically.
3. **Pictory Voiceover Tracks API**: Use the [Get Voiceover Tracks](/api-reference/voiceovers/get-voiceover-tracks) endpoint to list voices already in your library, including ElevenLabs voices with their `voice` field containing the ElevenLabs voice ID.

## Basic Example

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from "axios";

  const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
  const API_KEY = "YOUR_API_KEY";

  async function createVideoWithElevenLabsVoice() {
    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "elevenlabs_voice_demo",
        voiceOver: {
          enabled: true,
          aiVoices: [
            {
              speaker: "pNInz6obpgDQGcFmaJgB",  // ElevenLabs voice ID for "Adam"
              speed: 100,
              amplificationLevel: 0,
            },
          ],
        },
        scenes: [
          {
            story: "Welcome to our product demo. Today we'll show you how easy it is to create professional videos with ultra-realistic AI narration.",
            createSceneOnEndOfSentence: true,
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: API_KEY,
        },
      }
    );

    console.log("Job ID:", response.data.data.jobId);
  }

  createVideoWithElevenLabsVoice();
  ```

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

  API_BASE_URL = "https://api.pictory.ai/pictoryapis"
  API_KEY = "YOUR_API_KEY"

  def create_video_with_elevenlabs_voice():
      response = requests.post(
          f"{API_BASE_URL}/v2/video/storyboard/render",
          json={
              "videoName": "elevenlabs_voice_demo",
              "voiceOver": {
                  "enabled": True,
                  "aiVoices": [
                      {
                          "speaker": "pNInz6obpgDQGcFmaJgB",  # ElevenLabs voice ID for "Adam"
                          "speed": 100,
                          "amplificationLevel": 0,
                      }
                  ],
              },
              "scenes": [
                  {
                      "story": "Welcome to our product demo. Today we'll show you how easy it is to create professional videos with ultra-realistic AI narration.",
                      "createSceneOnEndOfSentence": True,
                  }
              ],
          },
          headers={
              "Content-Type": "application/json",
              "Authorization": API_KEY,
          },
      )
      response.raise_for_status()
      print(f"Job ID: {response.json()['data']['jobId']}")

  create_video_with_elevenlabs_voice()
  ```
</CodeGroup>

## Ways to Reference a Voice

The `speaker` field accepts multiple formats:

| Format              | Example                  | Description                                        |
| ------------------- | ------------------------ | -------------------------------------------------- |
| Voice name          | `"Brian"`                | Matches by voice name in your library              |
| Track ID            | `"1776425060651"`        | Numeric track ID from your library                 |
| ElevenLabs voice ID | `"pNInz6obpgDQGcFmaJgB"` | ElevenLabs UUID, auto-discovered if not in library |

### Resolution Order

When you pass a `speaker` value, Pictory resolves it in this order:

1. **Track ID**: If numeric, searches by track ID
2. **Voice name**: Searches by voice name (case-insensitive)
3. **Voice ID**: Searches by the voice provider's ID (e.g., ElevenLabs UUID)
4. **Auto-discovery**: If not found, attempts to discover and add the voice from ElevenLabs

## Using Previously Discovered Voices

Once a voice is discovered and added to your library, you can reference it by name or track ID in future requests, just like any other voice.

Use the [Get Voiceover Tracks](/api-reference/voiceovers/get-voiceover-tracks) endpoint to see all voices in your library:

```bash theme={null}
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/voiceovers/tracks \
  --header 'Authorization: YOUR_API_KEY'
```

ElevenLabs voices in the response will have `"service": "elevenlabs"` and the original voice ID in the `voice` field.

## Premium Voice Settings

For ElevenLabs voices, you can fine-tune the voice output using `premiumVoiceSettings`:

```javascript theme={null}
{
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "pNInz6obpgDQGcFmaJgB",
      speed: 100,
      amplificationLevel: 0,
      premiumVoiceSettings: {
        modelId: "eleven_multilingual_v2",  // ElevenLabs model
        stability: 50,                      // 0-100, higher = more consistent
        similarityBoost: 75,                // 0-100, higher = closer to original
        style: 0,                           // 0-100, higher = more expressive
        useSpeakerBoost: true               // Enhance voice clarity
      }
    }]
  }
}
```

### Premium Voice Settings Reference

| Parameter         | Type    | Range | Description                                                       |
| ----------------- | ------- | ----- | ----------------------------------------------------------------- |
| `modelId`         | string  | -     | ElevenLabs model ID (e.g., `eleven_multilingual_v2`, `eleven_v3`) |
| `stability`       | number  | 0-100 | Voice consistency. Lower values produce more variation.           |
| `similarityBoost` | number  | 0-100 | How closely the output matches the original voice.                |
| `style`           | number  | 0-100 | Expressiveness. Higher values add more emotion.                   |
| `useSpeakerBoost` | boolean | -     | Enhances voice clarity and presence.                              |

<Note>
  `premiumVoiceSettings` only work with ElevenLabs voices. Using them with AWS or Google voices will return a validation error.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Voice Not Found Error">
    **Cause:** The ElevenLabs voice ID is invalid or the voice does not exist.

    **Resolution:**

    1. Verify the ElevenLabs voice ID is correct
    2. Check that the voice exists in the [ElevenLabs Voice Library](https://elevenlabs.io/voice-library)
    3. Ensure your Pictory subscription includes ElevenLabs voice access
  </Accordion>

  <Accordion title="Voice Sounds Different Than Expected">
    **Cause:** Default voice settings may not match the ElevenLabs preview.

    **Resolution:**

    1. Adjust `premiumVoiceSettings`: increase `similarityBoost` for closer matching
    2. Try a different `modelId`: `eleven_multilingual_v2` and `eleven_v3` produce different results
    3. Adjust `stability`: lower values produce more natural variation
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Voiceover Tracks" icon="list" href="/api-reference/voiceovers/get-voiceover-tracks">
    List all voices in your library
  </Card>

  <Card title="AI Voiceover Guide" icon="microphone" href="/guides/text-to-video/ai-voiceover">
    Complete guide to AI voiceover in videos
  </Card>

  <Card title="Multi-Level Voice-Over" icon="layer-group" href="/guides/text-to-video/multi-level-voiceover">
    Use different voices for different scenes
  </Card>

  <Card title="Pronunciation Guide" icon="spell-check" href="/guides/voice-over/pronunciation-guide">
    Control how words are pronounced
  </Card>
</CardGroup>