> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview Voice

> Generate an audio preview of a voice with optional custom text

Generates a base64-encoded audio sample for a given voice ID. Use this to let users hear how a voice sounds before assigning it to an agent.

## Request Body

<ParamField body="voiceId" type="string" required>
  The voice ID to preview. Get available IDs from the [List Voices](/api-reference/voices/list) endpoint.
</ParamField>

<ParamField body="text" type="string" default="Hello, I'm your voice agent. How can I help you today?">
  Custom text to speak (1–500 characters). If omitted, a default greeting is used.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.telzino.com/v1/voices/preview" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "voiceId": "79a125e8-cd45-4c13-8a67-188112f4dd22",
      "text": "Hello, thank you for calling. How can I help you?"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.telzino.com/v1/voices/preview', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      voiceId: '79a125e8-cd45-4c13-8a67-188112f4dd22',
      text: 'Hello, thank you for calling. How can I help you?'
    })
  });

  const { success, audioData } = await response.json();
  // audioData is base64-encoded audio
  ```

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

  response = requests.post(
      'https://api.telzino.com/v1/voices/preview',
      headers={
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'voiceId': '79a125e8-cd45-4c13-8a67-188112f4dd22',
          'text': 'Hello, thank you for calling. How can I help you?'
      }
  )

  data = response.json()
  # data['audioData'] contains base64-encoded audio
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "audioData": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA..."
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Invalid request data",
    "details": [
      {
        "code": "too_small",
        "minimum": 1,
        "type": "string",
        "inclusive": true,
        "exact": false,
        "message": "voiceId is required",
        "path": ["voiceId"]
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "error": "invalid_token",
    "error_description": "Missing or invalid authorization token"
  }
  ```
</ResponseExample>

## Response Fields

| Field       | Type    | Description                                    |
| ----------- | ------- | ---------------------------------------------- |
| `success`   | boolean | Whether the preview was generated successfully |
| `audioData` | string  | Base64-encoded audio data                      |

<Note>
  This endpoint generates previews for **Cartesia** voice IDs only. Minimax voices are not supported by this endpoint — use the static `previewUrl` field returned by the [List Voices](/api-reference/voices/list) endpoint instead.

  Voice previews are generated by the upstream TTS provider (Cartesia). In rare cases, the provider may return a `502` or `503` error due to temporary availability issues.
</Note>