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

# Get voice preview

> Returns a short audio preview for an existing voice. The preview text is determined server-side and cannot be customized. This endpoint is **not metered or billed**, making it ideal for voice browsing and selection experiences. Audio is always returned in MP3 format.



## OpenAPI

````yaml get /tts/v1/voice:preview
openapi: 3.0.0
info:
  title: Inworld Text-to-Speech API
  version: v1
  contact:
    name: Inworld AI
    url: https://inworld.ai
    email: support@inworld.ai
servers:
  - url: https://api.inworld.ai
security:
  - inworld_basic: []
tags:
  - name: TextToSpeech
  - name: AudioPromptPreparationService
  - name: SpeechToPhonemesService
paths:
  /tts/v1/voice:preview:
    get:
      tags:
        - TextToSpeech
      summary: Get voice preview
      description: >-
        Returns a short audio preview for an existing voice. The preview text is
        determined server-side and cannot be customized. This endpoint is **not
        metered or billed**, making it ideal for voice browsing and selection
        experiences. Audio is always returned in MP3 format.
      operationId: TextToSpeech_GetVoicePreview
      parameters:
        - name: voice_id
          description: >-
            The identifier of the voice to preview. Use the [List
            Voices](/api-reference/voiceAPI/voiceservice/list-voices) endpoint
            to discover available voice IDs.
          in: query
          required: true
          example: Ashley
          schema:
            type: string
            example: Ashley
        - name: model_id
          description: >-
            The identifier of the TTS model to use for generating the preview.
            See [Models](../../../tts/tts-models) for available models.
          in: query
          required: true
          example: inworld-tts-2
          schema:
            type: string
            example: inworld-tts-2
      responses:
        '200':
          description: A successful response containing the voice preview audio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ttsv1GetVoicePreviewResponse'
              examples:
                successful_response:
                  summary: Voice preview audio
                  description: Returns base64-encoded MP3 audio of the voice preview.
                  value:
                    audioContent: >-
                      SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjYwLjE2LjEwMAAAAAAAAAAAAAAA...
        4XX:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            curl
            'https://api.inworld.ai/tts/v1/voice:preview?voice_id=Ashley&model_id=inworld-tts-2'
            \

            --header "Authorization: Basic $INWORLD_API_KEY" \

            | jq -r '.audioContent' | base64 -d > preview.mp3
        - lang: python
          label: Python
          source: |-
            import requests
            import base64
            import os

            url = "https://api.inworld.ai/tts/v1/voice:preview"
            headers = {
                "Authorization": f"Basic {os.getenv('INWORLD_API_KEY')}"
            }
            params = {
                "voice_id": "Ashley",
                "model_id": "inworld-tts-2"
            }

            response = requests.get(url, headers=headers, params=params)
            response.raise_for_status()
            audio_content = base64.b64decode(response.json()["audioContent"])

            with open("preview.mp3", "wb") as f:
                f.write(audio_content)
            print("Preview saved to preview.mp3")
        - lang: javascript
          label: JavaScript
          source: |-
            const fs = require('fs');

            async function main() {
              const url = 'https://api.inworld.ai/tts/v1/voice:preview?voice_id=Ashley&model_id=inworld-tts-2';

              const response = await fetch(url, {
                headers: {
                  'Authorization': `Basic ${process.env.INWORLD_API_KEY}`,
                },
              });

              if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
              }

              const result = await response.json();
              const audioBuffer = Buffer.from(result.audioContent, 'base64');
              fs.writeFileSync('preview.mp3', audioBuffer);
              console.log('Preview saved to preview.mp3');
            }

            main();
components:
  schemas:
    ttsv1GetVoicePreviewResponse:
      type: object
      properties:
        audioContent:
          type: string
          format: byte
          description: >-
            The audio data bytes encoded as MP3. The preview text is determined
            server-side and cannot be customized.
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: >-
            The error code, as specified by [gRPC status
            codes](https://grpc.io/docs/guides/status-codes/).
          example: 5
        message:
          type: string
          description: A short description of the error.
          example: 'Unknown voice: John not found!'
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
          example: []
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
  securitySchemes:
    inworld_basic:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your [authentication](../../../api-reference/introduction) credentials.
        For Basic authentication, please populate `Basic $INWORLD_API_KEY`. You
        can create a key in one command with the [Inworld
        CLI](../../../tts/resources/inworld-cli): `inworld workspace add-key`.

````