### Install PlayHT SDK

Source: https://docs.play.ht/reference/index

Install the PlayHT SDK for Node.js using npm, pnpm, or yarn. This SDK simplifies making requests to the PlayHT API.

```npm
npm install playht
```

```pnpm
pnpm install playht
```

```yarn
yarn add playht
```

--------------------------------

### Install PlayHT SDK

Source: https://docs.play.ht/reference/api-getting-started

Instructions for installing the PlayHT SDK using different package managers like npm, pnpm, yarn, and pip. These commands set up the necessary libraries for interacting with the PlayHT API in your project.

```npm
npm install playht
```

```pnpm
pnpm install playht
```

```yarn
yarn add playht
```

```pip
pip install pyht
```

--------------------------------

### Install PlayHT SDK (Python)

Source: https://docs.play.ht/reference/index

Install the PlayHT Python SDK using pip. This package allows for easy integration of PlayHT's TTS capabilities into Python applications.

```pip
pip install pyht
```

--------------------------------

### Stream Audio with PlayHT API (Node.js)

Source: https://docs.play.ht/reference/index

Generate and stream audio using the PlayHT Node.js SDK. This example initializes the client with credentials and streams synthesized speech to a file.

```javascript
import * as PlayHT from 'playht';
import fs from 'fs';

// Initialize client
PlayHT.init({
  userId: '<YOUR_USER_ID>',
  apiKey: '<YOUR_API_KEY>',
});

async function streamAudio(text) {
  const stream = await PlayHT.stream('All human wisdom is summed up in these two words: Wait and hope.', { voiceEngine: 'PlayDialog' });
  stream.on('data', (chunk) => {
    // Do whatever you want with the stream, you could save it to a file, stream it in realtime to the browser or app, or to a telephony system
    fs.appendFileSync('output.mp3', chunk);
  });
  return stream;
}

```

--------------------------------

### Stream Audio with PlayHT API (cURL)

Source: https://docs.play.ht/reference/index

Make a POST request to the PlayHT API to stream audio using cURL. This example specifies the text, voice engine, voice, and output format, saving the result to a file.

```bash
curl --request POST \
     --url https://api.play.ht/api/v2/tts/stream \
     --header 'X-USER-ID: <YOUR_USER_ID>' \
     --header 'AUTHORIZATION: <YOUR_API_KEY>' \
     --header 'accept: audio/mpeg' \
     --header 'content-type: application/json' \
     --data \
'{
  "text": "Hello from a realistic voice.",
  "voice_engine": "PlayDialog",
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "output_format": "mp3"
}' --output result.mp3

```

--------------------------------

### Generate Speech Stream with PlayHT SDK (Node.js)

Source: https://docs.play.ht/reference/api-getting-started

Demonstrates how to use the PlayHT Node.js SDK to generate an audio stream from text. It includes initializing the client with user credentials and handling the audio data stream, with an example of saving it to a file. Dependencies include the 'playht' package and Node.js built-in 'fs' module.

```javascript
import * as PlayHT from 'playht';
import fs from 'fs';

// Initialize client
PlayHT.init({
  userId: '<YOUR_USER_ID>',
  apiKey: '<YOUR_API_KEY>',
});

async function streamAudio(text) {
  const stream = await PlayHT.stream('All human wisdom is summed up in these two words: Wait and hope.', { voiceEngine: 'PlayDialog' });
  stream.on('data', (chunk) => {
    // Do whatever you want with the stream, you could save it to a file, stream it in realtime to the browser or app, or to a telephony system
    fs.appendFileSync('output.mp3', chunk);
  });
  return stream;
}
```

--------------------------------

### Voice Cloning API

Source: https://docs.play.ht/reference/api-getting-started

This section outlines the API endpoint for instant voice cloning, allowing you to clone voices with a short audio sample.

```APIDOC
## API Create Instant Voice Clone

### Description
This endpoint allows for instant voice cloning using a short audio sample (approximately 30 seconds of speech).

### Method
POST (Assumed, based on common API patterns for creation)

### Endpoint
/api/v1/clones (Hypothetical, actual endpoint may vary. Refer to PlayHT documentation for the precise endpoint.)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **audio_sample** (file) - Required - An audio file containing the voice to be cloned.
- **voice_name** (string) - Required - A name for the cloned voice.
- **language** (string) - Optional - The language of the voice sample.

### Request Example
(Details on request body structure and file upload will be in the official PlayHT documentation.)

### Response
#### Success Response (200)
- **voice_id** (string) - An identifier for the newly cloned voice.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "voice_id": "cloned_voice_123",
  "message": "Voice cloned successfully."
}
```
```

--------------------------------

### Generate Speech Stream via cURL

Source: https://docs.play.ht/reference/api-getting-started

An example using cURL to make a POST request to the PlayHT API for streaming audio. This method is useful for testing the API directly from the command line. It requires specifying user ID, API key, request body with text and voice parameters, and outputs the audio to a file.

```curl
curl --request POST \
     --url https://api.play.ht/api/v2/tts/stream \
     --header 'X-USER-ID: <YOUR_USER_ID>' \
     --header 'AUTHORIZATION: <YOUR_API_KEY>' \
     --header 'accept: audio/mpeg' \
     --header 'content-type: application/json' \
     --data \
'{
  "text": "Hello from a realistic voice.",
  "voice_engine": "PlayDialog",
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "output_format": "mp3"
}' --output result.mp3
```

--------------------------------

### Install PlayHT Node.js SDK

Source: https://docs.play.ht/reference/nodejs-sdk

Instructions for installing the PlayHT Node.js SDK using npm, pnpm, or yarn. This is a prerequisite for using the SDK in your project.

```npm
npm install --save playht
```

```pnpm
pnpm install --save playht
```

```yarn
yarn add playht
```

--------------------------------

### Text-to-Speech Streaming API

Source: https://docs.play.ht/reference/index

This endpoint streams audio generated from the provided text using specified voice configurations.

```APIDOC
## POST /api/v2/tts/stream

### Description
Streams audio generated from the provided text using AI TTS models. Supports various voice engines and output formats.

### Method
POST

### Endpoint
https://api.play.ht/api/v2/tts/stream

### Parameters
#### Headers
- **X-USER-ID** (string) - Required - Your PlayHT User ID.
- **AUTHORIZATION** (string) - Required - Your PlayHT API Key.
- **accept** (string) - Optional - The desired audio format (e.g., 'audio/mpeg'). Defaults to 'audio/mpeg'.
- **content-type** (string) - Optional - The content type of the request body. Defaults to 'application/json'.

#### Request Body
- **text** (string) - Required - The text to convert to speech.
- **voice_engine** (string) - Required - The voice engine to use (e.g., 'PlayDialog').
- **voice** (string) - Optional - The specific voice to use, often a URL to a voice manifest.
- **output_format** (string) - Optional - The desired output audio format (e.g., 'mp3'). Defaults to 'mp3'.

### Request Example
```json
{
  "text": "Hello from a realistic voice.",
  "voice_engine": "PlayDialog",
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "output_format": "mp3"
}
```

### Response
#### Success Response (200)
- The response body contains the raw audio stream in the format specified by the 'accept' header.
```

--------------------------------

### POST /api/v2/tts/stream

Source: https://docs.play.ht/reference/api-getting-started

This endpoint streams audio from text using AI TTS models. You can specify the voice engine, voice, and output format.

```APIDOC
## POST /api/v2/tts/stream

### Description
Streams synthesized audio from the provided text using specified AI TTS models and configurations.

### Method
POST

### Endpoint
https://api.play.ht/api/v2/tts/stream

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **text** (string) - Required - The text to be synthesized into speech.
- **voice_engine** (string) - Optional - The voice engine to use (e.g., 'PlayDialog').
- **voice** (string) - Optional - The specific voice to use, often a URL pointing to a voice model manifest.
- **output_format** (string) - Optional - The desired audio output format (e.g., 'mp3').

### Request Example
```json
{
  "text": "Hello from a realistic voice.",
  "voice_engine": "PlayDialog",
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "output_format": "mp3"
}
```

### Response
#### Success Response (200)
- **audio_stream** (binary) - The synthesized audio data in the requested format.

#### Response Example
(Binary audio data, not shown as JSON)
```

--------------------------------

### Example Text-to-Speech Generation Events (SSE)

Source: https://docs.play.ht/reference/api-generate-audio

Provides a Server-Sent Events (SSE) example illustrating the flow of text-to-speech generation. It includes 'generating' events with progress updates, 'ping' events for keep-alive, and 'completed' events with the final audio URL and metadata. This demonstrates real-time status updates during TTS job execution.

```sse
event: generating
data: {"id":"w92633zG2nrMalFlEg","progress":0.53,"stage":"generate","stage_progress":0.6}

event: ping
data: 2023-03-04T01:12:03.981Z

event: completed
data: {"id":"w92633zG2nrMalFlEg","progress":1,"stage":"complete","url":"https://peregrine-results.s3.amazonaws.com/pigeon/w92633zG2nrMalFlEg_0.mp3","duration":29.9413,"size":600525}


```

--------------------------------

### Example Text-to-Speech 'Generating' Event

Source: https://docs.play.ht/reference/api-generate-audio

Demonstrates a sample 'generating' event payload for a text-to-speech job. It shows the job ID and its progress through the 'generate' stage, including a specific 'stage_progress' value. This example helps in understanding how real-time updates are structured.

```sse
event: generating
data: {"id":"w92633zG2nrMalFlEg","progress":0.53,"stage":"generate","stage_progress":0.6}


```

--------------------------------

### Example Batch TTS Request

Source: https://docs.play.ht/reference/api-create-batch-tts

An illustrative example of a request payload for creating a batch TTS job. It showcases how to define multiple jobs with varying levels of detail and specific voice parameters.

```json
{
  "webhook_url": "https://your.domain/batch-webhook",
  "jobs": [
    {
      "custom_id": "my-optional-custom-id-001",
      "webhook_url": "https://your.domain/optional-job1-webhook",
      "voice_engine": "PlayDialog",
      "text": "Hello from job one.",
      "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
      "quality": "medium",
      "output_format": "mp3",
      "speed": 1,
      "sample_rate": 24000,
      "seed": 123,
      "temperature": 0.7,
      "language": "english"
    },
    {
      "text": "Second job, minimal parameters.",
      "voice": "s3://voice-cloning-zero-shot/another-voice-id/manifest.json"
    }
  ]
}
```

--------------------------------

### TextToSpeechJob Example - JSON

Source: https://docs.play.ht/reference/api-generate-audio

This snippet demonstrates the structure of a successful TextToSpeechJob response. It includes details about the job's ID, creation timestamp, input parameters, output information, and a set of links for interacting with the job resource.

```json
{
  href: 'https://play.ht/api/v2/tts/f0gZrOKBKL7veJ6o1M',
  method: 'GET',
  contentType: 'application/json',
  rel: 'self',
  description: "Fetches this job's data. Poll it for the latest status."
}

```

--------------------------------

### Rate Limit Exceeded Example (JSON)

Source: https://docs.play.ht/reference/api-list-ultra-realistic-voices

Provides an example of a response when the API rate limit is exceeded. This indicates that too many requests have been made from the client's IP address within a given time frame.

```json
"Rate limit exceeded. Please wait a few moments and try again."
```

--------------------------------

### Streaming TTS Audio with Play3.0-mini Model (Node.js)

Source: https://docs.play.ht/reference/techniques-to-guarantee-the-lowest-latency-1

This example demonstrates how to stream audio using the PlayHT Node.js SDK, specifically utilizing the `Play3.0-mini` model for reduced latency.

```APIDOC
## POST /tts/stream (using Node.js SDK)

### Description
Streams audio text using the PlayHT Node.js SDK with the `Play3.0-mini` model for optimal latency.

### Method
POST

### Endpoint
(Implicitly handled by the SDK)

### Parameters
#### Request Body (SDK options)
- **text** (string) - Required - The text to synthesize into speech.
- **voiceEngine** (string) - Optional - Specifies the voice engine to use. Set to `"Play3.0-mini"` for lowest latency.

### Request Example
```typescript
import * as PlayHT from "playht";

// Initialize PlayHT API with your credentials
PlayHT.init({
  userId: "<YOUR_USER_ID>",
  apiKey: "<YOUR_API_KEY>",
});

PlayHT.stream("Hello from a realistic voice.", {voiceEngine: "Play3.0-mini"});
```

### Response
#### Success Response (200)
Returns audio stream data.
```

--------------------------------

### Initialize PlayHT Client with Default Voice and Engine

Source: https://docs.play.ht/reference/nodejs-sdk

Initializes the PlayHT client with credentials and sets a default voice and voice engine. This simplifies subsequent speech generation by pre-configuring these options.

```javascript
import * as PlayHT from 'playht';

PlayHT.init({
  apiKey: '<YOUR API KEY>',
  userId: '<YOUR API KEY>',
  defaultVoiceId: 's3://peregrine-voices/oliver_narrative2_parrot_saad/manifest.json',
  defaultVoiceEngine: 'PlayDialog',
});
```

--------------------------------

### Get Batch TTS Job Details - PHP

Source: https://docs.play.ht/reference/batch-text-to-speech

This PHP snippet illustrates how to fetch batch TTS job details using cURL. It sets the request method to GET, specifies the URL with the batch ID, and includes the authorization header.

```php
<?php

$batchId = 'YOUR_BATCH_ID';
$apiKey = 'YOUR_API_KEY';

$url = "https://api.play.ht/api/v2/tts/batches/{$batchId}";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

$headers = array();
$headers[] = 'Accept: application/json';
$headers[] = "Authorization: Bearer {$apiKey}";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($http_code == 200) {
        $data = json_decode($result, true);
        print_r($data);
    } else {
        echo "HTTP Error: {$http_code}\n";
        echo $result;
    }
}

c_url_close($ch);

?>
```

--------------------------------

### Get Batch TTS Job Details - Python

Source: https://docs.play.ht/reference/batch-text-to-speech

This Python snippet shows how to retrieve batch TTS job details using the 'requests' library. It makes a GET request to the specified endpoint, including the batch ID and API key in the headers.

```python
import requests

batch_id = 'YOUR_BATCH_ID'
api_key = 'YOUR_API_KEY'

url = f'https://api.play.ht/api/v2/tts/batches/{batch_id}'

headers = {
    'accept': 'application/json',
    'AUTHORIZATION': f'Bearer {api_key}'
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f'Error fetching batch job details: {e}')
```

--------------------------------

### Get Batch TTS Job Details - Node.js

Source: https://docs.play.ht/reference/batch-text-to-speech

This Node.js snippet demonstrates how to fetch batch TTS job details from the PlayHT API. It utilizes the 'node-fetch' library to make the GET request, requiring the batch ID and API key for authentication.

```javascript
import fetch from 'node-fetch';

const batchId = 'YOUR_BATCH_ID';
const apiKey = 'YOUR_API_KEY';

async function getBatchJobDetails() {
    const url = `https://api.play.ht/api/v2/tts/batches/${batchId}`;
    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'accept': 'application/json',
                'AUTHORIZATION': `Bearer ${apiKey}`
            }
        });
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data = await response.json();
        console.log(data);
        return data;
    } catch (error) {
        console.error('Error fetching batch job details:', error);
    }
}

getBatchJobDetails();
```

--------------------------------

### Initialize PlayHT Client with Credentials

Source: https://docs.play.ht/reference/nodejs-sdk

Initializes the PlayHT client with API Key and User ID. These credentials are required for all subsequent API calls. Ensure to keep your API Secret Key confidential.

```javascript
import * as PlayHT from 'playht';

PlayHT.init({
  apiKey: '<YOUR API KEY>',
  userId: '<YOUR API KEY>',
});
```

--------------------------------

### Synchronous Text-to-Speech with pyht Client

Source: https://docs.play.ht/reference/python-sdk

Demonstrates how to use the pyht Client to convert text to speech synchronously. It initializes the client with user ID and API key, sets TTS options including a custom voice, and writes the resulting audio chunks to a WAV file. Supports various voice engines like 'PlayDialog-http'.

```python
from pyht import Client
from dotenv import load_dotenv
from pyht.client import TTSOptions
import os
load_dotenv()

client = Client(
    user_id=os.getenv("PLAY_HT_USER_ID"),
    api_key=os.getenv("PLAY_HT_API_KEY"),
)
options = TTSOptions(voice="s3://voice-cloning-zero-shot/775ae416-49bb-4fb6-bd45-740f205d20a1/jennifersaad/manifest.json")
# Open a file to save the audio
with open("output_jenn.wav", "wb") as audio_file:
    for chunk in client.tts("Hi, I'm Jennifer from Play. How can I help you today?", options, voice_engine = 'PlayDialog-http'):
        # Write the audio chunk to the file
        audio_file.write(chunk)

print("Audio saved as output_jenn.wav")
```

--------------------------------

### List PlayHT Voices

Source: https://docs.play.ht/reference/api-list-ultra-realistic-voices

Gets the full list of stock PlayHT Voices available for use with the API. To get the list of cloned voices, please refer to the Voice Cloning API.

```APIDOC
## GET /api/v2/voices

### Description
Gets the full list of stock PlayHT Voices available for use with the API.

To get the list of cloned voices, please refer to the [Voice Cloning API](https://docs.play.ht/reference/api-list-cloned-voices).

### Method
GET

### Endpoint
https://api.play.ht/api/v2/voices

### Parameters
#### Query Parameters

#### Request Body

### Request Example

### Response
#### Success Response (200)
- **id** (string) - The unique ID for a PlayHT or Cloned Voice.
- **name** (string) - The name of the voice.
- **sample** (string) - A sample audio URI for the voice.
- **accent** (string) - The accent of the voice (e.g., american, australian, british, canadian).
- **age** (string) - The age category of the voice (e.g., adult, old, youth).
- **gender** (string) - The gender of the voice (e.g., female, male).
- **language** (string) - The language of the voice (e.g., English (US), English (AU)).
- **language_code** (string) - The language code for the voice (e.g., en-US, en-AU).
- **loudness** (string) - The loudness level of the voice (e.g., low, neutral, whisper, high).
- **style** (string) - The speaking style of the voice (e.g., narrative, videos, training).
- **tempo** (string) - The speaking tempo of the voice (e.g., neutral, slow, fast).
- **texture** (string) - The vocal texture of the voice.

#### Response Example
```json
[
  {
    "id": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
    "name": "larry",
    "sample": "https://peregrine-samples.s3.amazonaws.com/editor-samples/william_vo.wav",
    "accent": "american",
    "age": "adult",
    "gender": "male",
    "language": "English (US)",
    "language_code": "en-US",
    "loudness": "neutral",
    "style": "narrative",
    "tempo": "neutral",
    "texture": "default"
  }
]
```
```

--------------------------------

### POST /websites/play_ht_reference

Source: https://docs.play.ht/reference/api-create-batch-tts

Initiates playback of a dialog with specified audio configurations.

```APIDOC
## POST /websites/play_ht_reference

### Description
This endpoint plays a dialog using the provided text and audio configurations. It allows for customization of output format, speech speed, sample rate, language, and voice.

### Method
POST

### Endpoint
/websites/play_ht_reference

### Parameters
#### Request Body
- **text** (string) - Required - The text content to be spoken.
- **output_format** (string) - Optional - Format of the generated audio. Allowed values: `mp3`, `wav`, `ogg`, `flac`, `mulaw`.
- **speed** (number) - Optional - Speed of the speech. Should be between 0.1 and 5.
- **sample_rate** (integer) - Optional - Sample rate of the audio in Hz. Should be between 8000 and 48000.
- **seed** (integer) - Optional - Seed for reproducibility.
- **temperature** (number) - Optional - Controls randomness. Higher values are more random. Should be between 0 and 2.
- **language** (string) - Optional - Language of the text/voice. See enum for allowed values.
- **voice_2** (string) - Optional - Secondary voice for dialogs. Defaults to a specific S3 URL.
- **turn_prefix** (string) - Optional - Prefix to add before each turn in the dialog.

### Request Example
```json
{
  "text": "Hello, how are you doing today?",
  "output_format": "mp3",
  "voice_2": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "language": "english"
}
```

### Response
#### Success Response (200)
- **audio_url** (string) - URL to the generated audio file.

#### Response Example
```json
{
  "audio_url": "https://example.com/path/to/your/audio.mp3"
}
```
```

--------------------------------

### Get Batch TTS Job Details

Source: https://docs.play.ht/reference/batch-text-to-speech

Retrieves the details of a specific batch TTS job, including all its child jobs and their current status.

```APIDOC
## GET /api/v2/tts/batches/{batchId}

### Description
Retrieves the details of a specific batch TTS job, including all its child jobs and their current status.

### Method
GET

### Endpoint
`https://api.play.ht/api/v2/tts/batches/{batchId}`

### Parameters
#### Path Parameters
- **batchId** (string) - Required - The ID of the batch TTS job to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "Not applicable for GET request"
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for a batch TTS job.
- **created_at** (date-time) - ISO 8601 timestamp of when the batch job was created.
- **status** (string) - Current overall status of the batch job (`pending`, `in_progress`, `completed`, `failed`).
- **webhook_url** (url | null) - URL to send webhook notifications to.
- **webhook_result** (object | null) - Details of the webhook call.
  - **called_at** (date-time) - ISO 8601 timestamp of when the webhook was called.
  - **response_status** (integer) - HTTP status code received from the webhook endpoint.
- **jobs** (array of objects) - List of child jobs within the batch.
  - **id** (string) - Unique identifier for a child job.
  - **custom_id** (string | null) - User-defined custom identifier for a child job.
  - **created_at** (date-time) - ISO 8601 timestamp of when the child job was created.
  - **input** (object) - Input parameters for the TTS child job.
  - **status** (string) - Current status of the child job (`pending`, `in_progress`, `completed`, `failed`).
  - **output** (object | null) - Output details of a completed TTS child job.
  - **webhook_url** (url | null) - URL to send webhook notifications to.
  - **webhook_result** (object | null) - Details of the webhook call.
- **_links** (object) - Links related to the batch job.
  - **self** (object) - Self link.

#### Response Example
```json
{
  "id": "batch_12345",
  "created_at": "2023-10-27T10:00:00Z",
  "status": "completed",
  "webhook_url": null,
  "webhook_result": null,
  "jobs": [
    {
      "id": "job_abcde",
      "custom_id": null,
      "created_at": "2023-10-27T10:00:05Z",
      "input": {
        "text": "Hello world.",
        "voice": "en-US-Standard-C"
      },
      "status": "completed",
      "output": {
        "audio_url": "https://play.ht/audio/abcde.mp3"
      },
      "webhook_url": null,
      "webhook_result": null
    }
  ],
  "_links": {
    "self": {
      "href": "/api/v2/tts/batches/batch_12345"
    }
  }
}
```

#### Error Responses
- **401**: Unauthorized. Please verify your authorization headers.
- **403**: The provided API key's plan does not have access to the requested resource.
- **404**: The requested job does not exist.
- **429**: Too many requests. Rate limit exceeded.
- **500**: An unexpected error occurred.
```

--------------------------------

### Authentication

Source: https://docs.play.ht/reference/api-create-instant-voice-clone

PlayHT API supports authentication using an API Key and a User ID, provided in the request headers.

```APIDOC
## Authentication

### API Key Authentication

**Type**: `apiKey`
**In**: `header`
**Name**: `AUTHORIZATION`
**Description**: API key required for this endpoint. Use `Bearer YOUR_SECRET_API_KEY`. Get your key from <https://play.ht/app/api-access>.

### User ID Authentication

**Type**: `apiKey`
**In**: `header`
**Name**: `X-USER-ID`
**Description**: User ID required for this endpoint. Get it from <https://play.ht/app/api-access>.
```

--------------------------------

### Get Batch TTS Job Details - Shell (cURL)

Source: https://docs.play.ht/reference/batch-text-to-speech

This snippet shows how to retrieve the details of a specific batch TTS job using cURL. It requires the batch ID as a path parameter and specifies the desired response format as JSON.

```Shell
curl --request GET \
     --url https://api.play.ht/api/v2/tts/batches/batchId \
     --header 'accept: application/json'
```

--------------------------------

### Error Responses

Source: https://docs.play.ht/reference/api-create-instant-voice-clone

This section details common error responses you might encounter when interacting with the PlayHT API, including unauthorized access, unsupported plans, invalid media types, rate limits, and internal server errors.

```APIDOC
## Error Responses

### 401 Unauthorized

**Description**: The request was not authorized. Please verify your authorization headers.

**Content**: `application/json`

**Schema**: 
```json
{
  "type": "object",
  "properties": {
    "error_message": {"type": "string"},
    "error_id": {"type": "string"}
  }
}
```

**Example**: 
```json
{
  "error_message": "The authorization header must be provided in the format 'Bearer <YOUR-API-KEY>'",
  "error_id": "UNAUTHORIZED"
}
```

### 403 Forbidden

**Description**: The provided API key's plan does not have access to the requested resource.

**Content**: `application/json`

**Schema**: 
```json
{
  "type": "object",
  "properties": {
    "error_message": {"type": "string"},
    "error_id": {"type": "string"}
  }
}
```

**Example**: 
```json
{
  "error_message": "API access is not available on your current plan.",
  "error_id": "UNSUPPORTED_PLAN"
}
```

### 415 Unsupported Media Type

**Description**: The server could not process your request because the format of the data you sent is not supported. Check `Content-Type` header of your request and ensure that it is set to a supported media type. You may also need to update your request payload to match the expected media type for the resource you are trying to access.

**Content**: `application/json`

**Schema**: 
```json
{
  "type": "object",
  "properties": {
    "error_message": {"type": "string"},
    "error_id": {"type": "string"}
  }
}
```

**Example**: 
```json
{
  "error_message": "Requests to this endpoint must be in example/media-type.",
  "error_id": "UNSUPPORTED_MEDIA_TYPE"
}
```

### 429 Too Many Requests

**Description**: The server has received too many requests from your IP address within a certain time frame and has temporarily blocked your access to this resource. This error is used to prevent abuse of the server. Please refer to the [Rate-Limits](https://docs.play.ht/reference/api-rate-limits) section for more information.

**Content**: `application/json`

**Schema**: `string`

**Example**: 
```
Rate limit exceeded. Please wait a few moments and try again.
```

### 500 Internal Server Error

**Description**: An unexpected error occurred on the server.

**Content**: `application/json`

**Schema**: 
```json
{
  "type": "object",
  "properties": {
    "message": {"type": "string"},
    "error": {"type": "string"}
  }
}
```

```

--------------------------------

### Asynchronous Text-to-Speech with pyht AsyncClient

Source: https://docs.play.ht/reference/python-sdk

Shows how to perform asynchronous Text-to-Speech operations using the pyht AsyncClient. This is beneficial for applications requiring non-blocking I/O. The example iterates over audio chunks asynchronously using an async for loop.

```python
from pyht import AsyncClient

client = AsyncClient(
    user_id=os.getenv("PLAY_HT_USER_ID"),
    api_key=os.getenv("PLAY_HT_API_KEY"),
)
options = TTSOptions(voice="s3://voice-cloning-zero-shot/775ae416-49bb-4fb6-bd45-740f205d20a1/jennifersaad/manifest.json")
async for chunk in client.tts("Hi, I'm Jennifer from Play. How can I help you today?", options):
    # do something with the audio chunk
    print(type(chunk))
```

--------------------------------

### Get Batch TTS Job Details - Ruby

Source: https://docs.play.ht/reference/batch-text-to-speech

This Ruby snippet demonstrates retrieving batch TTS job details using the Net::HTTP library. It constructs the URL with the batch ID and sets the necessary headers for authorization and content type.

```ruby
require 'net/http'
require 'uri'
require 'json'

batch_id = 'YOUR_BATCH_ID'
api_key = 'YOUR_API_KEY'

uri = URI.parse("https://api.play.ht/api/v2/tts/batches/#{batch_id}")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['accept'] = 'application/json'
request['Authorization'] = "Bearer #{api_key}"

begin
  response = http.request(request)
  if response.code == '200'
    data = JSON.parse(response.body)
    puts data
  else
    puts "Error: #{response.code} - #{response.message}"
  end
rescue StandardError => e
  puts "An error occurred: #{e.message}"
end
```

--------------------------------

### Initialize PlayHT Client (Node.js)

Source: https://docs.play.ht/reference/authentication

Initializes the PlayHT client with user credentials. Requires the 'playht' package. Takes userId and apiKey as input.

```javascript
import * as PlayHT from 'playht';

PlayHT.init({
  userId: '<YOUR_USER_ID>',
  apiKey: '<YOUR_API_KEY>',
});
```

--------------------------------

### GET /tts

Source: https://docs.play.ht/reference/api-get-batch-tts-child-job-by-id

This endpoint allows you to convert text to speech. It supports various languages and voices.

```APIDOC
## GET /tts

### Description
Convert text to speech.

### Method
GET

### Endpoint
/tts

### Query Parameters
- **voice** (string) - Optional - The voice to use for speech synthesis. Example: `en-US-Wavenet-D`
- **text** (string) - Required - The text to convert to speech.
- **output_format** (string) - Optional - The desired audio output format. Example: `mp3`
- **speed** (number) - Optional - The speech speed (0.5 to 2.0). Example: `1.0`
- **emotion** (string) - Optional - The emotion to convey (e.g., `Neutral`, `Happy`). Example: `Happy`
- **pitch** (number) - Optional - The speech pitch (0.5 to 2.0). Example: `1.0`

### Request Example
```
GET /tts?voice=en-US-Wavenet-D&text=Hello%2C%20world!&output_format=mp3
```

### Response
#### Success Response (200)
- **audio_content** (string) - The base64 encoded audio content of the speech.

#### Response Example
```json
{
  "audio_content": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAIBAQEBAQ..."
}
```

#### Error Responses
- **400**: Bad Request - Invalid input parameters.
- **401**: Unauthorized - API key is missing or invalid.
- **404**: Not Found - The requested resource does not exist.
- **429**: Too Many Requests - Rate limit exceeded.
- **500**: Internal Server Error - An unexpected error occurred.
```

--------------------------------

### PlayHT Batch TTS Job Example

Source: https://docs.play.ht/reference/api-get-batch-tts-child-job-by-custom-id

Demonstrates the structure of a successful batch Text-to-Speech job response from the PlayHT API. It includes job identifiers, creation time, input configuration (voice, text, language), output format and duration, status, and webhook details.

```json
{
  "id": "bc-98dsfghi012jkl345",
  "custom_id": "my-special-job-007",
  "created_at": "2023-11-01T10:01:10Z",
  "input": {
    "voice_engine": "PlayDialog",
    "text": "This audio was identified by a custom ID.",
    "voice": "s3://voice-cloning-zero-shot/voice-three/manifest.json",
    "quality": "medium",
    "output_format": "ogg",
    "speed": 1.1,
    "sample_rate": 22050,
    "language": "french",
    "temperature": 0.5
  },
  "status": "completed",
  "output": {
    "duration": 12,
    "size": 456789,
    "url": "https://playht-audio-outputs.s3.amazonaws.com/bc-98dsfghi012jkl345.ogg"
  },
  "webhook_url": "https://my.webhook.service/notifications",
  "webhook_result": {
    "called_at": "2023-11-01T10:05:30Z",
    "response_status": 201
  },
  "_links": {
    "self": {
      "href": "https://api.play.ht/api/v2/tts/batches/bb-GHIJKL789012MNOPQR/job/bc-98dsfghi012jkl345",
      "description": "Fetches this specific job's data."
    },
    "alternate": {
      "href": "https://api.play.ht/api/v2/tts/batches/bb-GHIJKL789012MNOPQR/job/custom-id/my-special-job-007",
      "description": "Fetches this specific job's data through the custom_id."
    },
    "batch": {
      "href": "https://api.play.ht/api/v2/tts/batches/bb-GHIJKL789012MNOPQR",
      "description": "Fetches this job's Batch info."
    }
  }
}
```

--------------------------------

### GET /api/v1/tts.get?job_id={job_id}

Source: https://docs.play.ht/reference/api-get-batch-tts-child-job-by-id

Retrieve the audio file or its URL for a previously submitted text-to-speech job.

```APIDOC
## GET /api/v1/tts.get

### Description
Retrieve the audio file or its URL for a submitted text-to-speech job using its job ID.

### Method
GET

### Endpoint
/api/v1/tts.get

### Query Parameters
- **job_id** (string) - Required - The ID of the text-to-speech job.

### Headers
- **AUTHORIZATION** (string) - Required - API key. Format: `Bearer YOUR_SECRET_API_KEY`
- **X-USER-ID** (string) - Required - User ID. Get it from <https://play.ht/app/api-access>

### Request Example
```
GET /api/v1/tts.get?job_id=j-a1b2c3d4e5f67890
```

### Response
#### Success Response (200)
- **audio_url** (string) - The URL of the generated audio file.

#### Response Example
```json
{
  "audio_url": "https://play.ht/audio/j-a1b2c3d4e5f67890.mp3"
}
```

#### Error Responses
- **400**: Bad Request - Invalid input parameters (e.g., missing `job_id`).
- **401**: Unauthorized - API key is missing or invalid.
- **404**: Not Found - The requested job does not exist.
- **429**: Too Many Requests - Rate limit exceeded.
- **500**: Internal Server Error - An unexpected error occurred.
```

--------------------------------

### Multi-Turn Dialog Generation with PlayDialog (Python)

Source: https://docs.play.ht/reference/models

Illustrates generating multi-turn dialogue audio using the PlayDialog voice engine in Python. This example requires specific voice URIs, user credentials, and defines multiple speakers with their respective turn prefixes to create a conversational output saved as an MP3 file.

```python
import requests

url = "https://api.play.ht/api/v2/tts/stream"

payload = {
    "voice": "s3://voice-cloning-zero-shot/baf1ef41-36b6-428c-9bdf-50ba54682bd8/original/manifest.json",
    "output_format": "mp3",
    "text": "Country Mouse: How are you, my town mouse cousin? Town Mouse: I am doing fine, country mouse. Country Mouse: This is the greatest place ever, but it is so much busier than where I am from! Town Mouse: Thank you cousin, I love the hustle and bustle as well.",
    "voice_2": "s3://voice-cloning-zero-shot/e040bd1b-f190-4bdb-83f0-75ef85b18f84/original/manifest.json",
    "voice_engine": "PlayDialog",
    "turn_prefix_2": "Town Mouse:",
    "turn_prefix": "Country Mouse:"
}
headers = {
    "accept": "audio/mpeg",
    "content-type": "application/json",
    "AUTHORIZATION": "<YOUR_API_KEY>",
    "X-USER-ID": "<YOUR_USER_ID>"
}

response = requests.post(url, json=payload, headers=headers)

with open('dialogue.wav', 'wb') as f:
    f.write(response.content)
    print("Audio file saved as dialogue.wav")

```

--------------------------------

### GET /v2/tts/batches/{batchId}

Source: https://docs.play.ht/reference/api-get-batch-tts-job

Fetches the data for a specific text-to-speech batch job using its unique ID.

```APIDOC
## GET /v2/tts/batches/{batchId}

### Description
Fetches the data for a specific batch job.

### Method
GET

### Endpoint
`/v2/tts/batches/{batchId}`

### Parameters
#### Path Parameters
- **batchId** (string) - Required - The unique identifier for the batch job.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **batchId** (string) - The ID of the batch job.
- **createdAt** (string) - The timestamp when the batch job was created.
- **updatedAt** (string) - The timestamp when the batch job was last updated.
- **status** (string) - The current status of the batch job (e.g., "completed", "processing").
- **userId** (string) - The ID of the user who created the batch job.
- **audioResponse** (object) - An object containing information about the generated audio files.
  - **audios** (array) - A list of audio objects.
    - **text** (string) - The original text for this audio file.
    - **voice** (string) - The voice used for this audio file.
    - **audioUrl** (string) - The URL to download the generated audio file.
    - **generatedAt** (string) - The timestamp when the audio file was generated.

#### Response Example
```json
{
  "example": {
    "batchId": "bb-GHIJKL789012MNOPQR",
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:05:00Z",
    "status": "completed",
    "userId": "user-12345",
    "audioResponse": {
      "audios": [
        {
          "text": "Hello world.",
          "voice": "en-US-Ava",
          "audioUrl": "https://cdn.play.ht/audio/bb-GHIJKL789012MNOPQR/audio-1.mp3",
          "generatedAt": "2023-10-27T10:04:00Z"
        }
      ]
    }
  }
}
```

### Error Handling
- **401 Unauthorized**: The request was not authorized. Please verify your authorization headers.
- **403 Forbidden**: The provided API key's plan does not have access to the requested resource.
- **404 Not Found**: The requested job does not exist.
- **429 Too Many Requests**: Rate limit exceeded. Please wait a few moments and try again.
- **500 Internal Server Error**: An unexpected error occurred.
```