# PlayHT Integration via LowCodeAPI

## Overview

PlayHT is a leading text-to-speech service with high-quality AI voices and voice cloning capabilities. The PlayHT API provides:

- **Text-to-Speech** - Convert text to realistic speech using AI voices
- **Streaming TTS** - Real-time audio streaming for low-latency applications
- **Voice Cloning** - Create instant voice clones from audio samples
- **Voice Management** - List available PlayHT and cloned voices

## Base Endpoint

```
https://api.lowcodeapi.com/playht/
```

## Authentication

LowCodeAPI handles authentication automatically using dual-header authentication. You only need to:

1. **Sign up** at [PlayHT](https://play.ht/) to get your API Key and User ID
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your PlayHT API key and User ID
- Apply them to each request (Authorization and X-USER-ID headers)

**Auth Type**: API Key (Dual Header: Authorization + X-USER-ID)

## API Categories

- **Text to Speech AI** - AI-powered text-to-speech synthesis

## Common Endpoints

### Category: Text To Speech

#### Generate Audio From Text

**Method**: `POST` | **LowCodeAPI Path**: `/api/v2/tts`

**Full URL**:
```
https://api.lowcodeapi.com/playht/api/v2/tts?api_token={api_token}
```

**Description**: Creates a new Text-to-Speech (TTS) job that converts input text into audio asynchronously.

**Request Body**:
```json
{
  "text": "Hello, this is a test of the PlayHT text-to-speech system.",
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "output_format": "mp3",
  "quality": "high",
  "speed": 1.0,
  "sample_rate": 24000,
  "seed": 42,
  "voice_engine": "PlayHT2.0",
  "emotion": "female_happy",
  "style_guidance": 5,
  "voice_guidance": 3,
  "temperature": 0.7
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | Yes | The text to be converted to speech |
| `voice` | string | Yes | Unique ID for a PlayHT or Cloned Voice |
| `output_format` | enum | No | Audio format: mp3, mulaw, wav, ogg, flac (default: mp3) |
| `quality` | enum | No | Audio quality: draft, low, medium, high, premium |
| `speed` | number | No | Control speech speed (0 < speed <= 5.0) |
| `sample_rate` | number | No | Sample rate (8000 to 48000 Hz) |
| `seed` | number | No | Integer >= 0 for reproducible audio generation |
| `voice_engine` | enum | No | Engine: PlayHT2.0-turbo, PlayHT2.0, PlayHT1.0 |
| `emotion` | enum | No | Emotion: female_happy, female_sad, male_happy, etc. |
| `style_guidance` | number | No | Emotion strength (1-30, PlayHT2.0 only) |
| `voice_guidance` | number | No | Voice uniqueness (1-6, PlayHT2.0 only) |
| `temperature` | number | No | Variance control (0-2, inclusive) |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/playht/api/v2/tts?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from PlayHT!",
    "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
    "output_format": "mp3",
    "quality": "high"
  }'
```

**Official Documentation**: [Generate Audio](https://docs.play.ht/reference/api-generate-audio)

---

#### Stream Audio From Text

**Method**: `POST` | **LowCodeAPI Path**: `/api/v2/tts/stream`

**Full URL**:
```
https://api.lowcodeapi.com/playht/api/v2/tts/stream?api_token={api_token}
```

**Description**: Streams the audio bytes immediately or returns a URL for immediate streaming.

**Request Body**:
```json
{
  "text": "This is a streaming text-to-speech example.",
  "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
  "output_format": "mp3",
  "quality": "high",
  "speed": 1.0,
  "sample_rate": 24000,
  "seed": 42,
  "voice_engine": "PlayHT2.0",
  "emotion": "female_happy",
  "style_guidance": 5,
  "voice_guidance": 3,
  "temperature": 0.7,
  "text_guidance": 1.5
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | Yes | The text to be converted to speech |
| `voice` | string | Yes | Unique ID for a PlayHT or Cloned Voice |
| `output_format` | enum | No | Audio format: mp3, mulaw, wav, ogg, flac |
| `quality` | enum | No | Audio quality: draft, low, medium, high, premium |
| `speed` | number | No | Control speech speed (0 < speed <= 5.0) |
| `sample_rate` | number | No | Sample rate (8000 to 48000 Hz) |
| `seed` | number | No | Integer >= 0 for reproducible audio |
| `voice_engine` | enum | No | Engine: PlayHT2.0-turbo, PlayHT2.0, PlayHT1.0 |
| `emotion` | enum | No | Emotion: female_happy, female_sad, male_happy, etc. |
| `style_guidance` | number | No | Emotion strength (1-30, PlayHT2.0 only) |
| `voice_guidance` | number | No | Voice uniqueness (1-6, PlayHT2.0 only) |
| `temperature` | number | No | Variance control (0-2) |
| `text_guidance` | number | No | Text adherence (1-2, PlayHT2.0 only) |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/playht/api/v2/tts/stream?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Streaming audio example",
    "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json"
  }'
```

**Official Documentation**: [Stream Audio](https://docs.play.ht/reference/api-generate-tts-audio-stream)

---

#### Get Text-To-Speech Job Data

**Method**: `GET` | **LowCodeAPI Path**: `/api/v2/tts/id`

**Full URL**:
```
https://api.lowcodeapi.com/playht/api/v2/tts/id?id={id}&api_token={api_token}
```

**Description**: Retrieves information about an async text-to-speech job.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The job ID |
| `format` | enum | No | Response format: audio-mpeg, event-stream |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/playht/api/v2/tts/id?id=job_abc123&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get TTS Data](https://docs.play.ht/reference/api-get-tts-data)

---

### Category: Voice Cloning

#### List Cloned Voices

**Method**: `GET` | **LowCodeAPI Path**: `/api/v2/cloned-voices`

**Full URL**:
```
https://api.lowcodeapi.com/playht/api/v2/cloned-voices?api_token={api_token}
```

**Description**: Get all cloned voices created by your account. The cloned voice ID can be used as the `voice` parameter in TTS endpoints.

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/playht/api/v2/cloned-voices?api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "voices": [
      {
        "id": "s3://mockingbird-prod/william_3_d2b62fd7-a52d-4bd1-a09a-fb2748eda979/voices/william_3/manifest.json",
        "name": "William Voice",
        "sampleUrl": "https://example.com/sample.mp3"
      }
    ]
  }
}
```

**Official Documentation**: [List Cloned Voices](https://docs.play.ht/reference/api-list-cloned-voices)

---

#### Create Instant Voice Clone

**Method**: `POST` | **LowCodeAPI Path**: `/api/v2/cloned-voices/instant`

**Full URL**:
```
https://api.lowcodeapi.com/playht/api/v2/cloned-voices/instant?api_token={api_token}
```

**Description**: Create an instant voice clone by providing a sample audio file via file upload. The audio file should be 2 seconds to 1 hour in duration and 5KB to 50MB in size.

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `voice_name` | string | No | The name for this new cloned voice |
| `sample_file` | file | No | Audio file source (5KB to 50MB, 2 sec to 1 hour) |
| `sample_file_url` | string | No | URL of the audio file source |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/playht/api/v2/cloned-voices/instant?api_token=YOUR_API_TOKEN" \
  -F "voice_name=My Custom Voice" \
  -F "sample_file=@voice_sample.mp3"
```

**Official Documentation**: [Create Voice Clone](https://docs.play.ht/reference/api-create-instant-voice-clone)

---

#### Delete Cloned Voices

**Method**: `DELETE` | **LowCodeAPI Path**: `/api/v2/cloned-voices`

**Full URL**:
```
https://api.lowcodeapi.com/playht/api/v2/cloned-voices?api_token={api_token}
```

**Description**: Deletes a cloned voice created by the user using the provided voice_id.

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `voice_id` | string | Yes | The ID of the cloned voice to be deleted |

**Example Request**:
```bash
curl -X DELETE "https://api.lowcodeapi.com/playht/api/v2/cloned-voices?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"voice_id": "s3://example/path/to/voice/manifest.json"}'
```

**Official Documentation**: [Delete Voice Clone](https://docs.play.ht/reference/api-delete-cloned-voices)

---

### Category: Voices

#### List PlayHT Voices

**Method**: `GET` | **LowCodeAPI Path**: `/api/v2/voices`

**Full URL**:
```
https://api.lowcodeapi.com/playht/api/v2/voices?api_token={api_token}
```

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

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/playht/api/v2/voices?api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "voices": [
      {
        "id": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
        "name": "Female US Voice",
        "gender": "Female",
        "language": "en-US",
        "accent": "American"
      }
    ]
  }
}
```

**Official Documentation**: [List Voices](https://docs.play.ht/reference/api-list-ultra-realistic-voices)

---

## Usage Examples

### Example 1: Generate Speech from Text

Convert text to audio using standard voice:

```bash
# Step 1: List available voices
# No ID needed - lists all PlayHT voices
curl -X GET "https://api.lowcodeapi.com/playht/api/v2/voices?api_token=YOUR_API_TOKEN"

# Step 2: Generate audio from text
# No ID needed - creates new TTS job
curl -X POST "https://api.lowcodeapi.com/playht/api/v2/tts?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is an example of text-to-speech conversion using PlayHT",
    "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
    "quality": "high",
    "output_format": "mp3"
  }'

# Step 3: Check job status
# Replace JOB_ID with the actual job ID returned from Step 2
curl -X GET "https://api.lowcodeapi.com/playht/api/v2/tts/id?id=JOB_ID&api_token=YOUR_API_TOKEN"
```

### Example 2: Create and Use Custom Voice Clone

Create a custom voice and use it for TTS:

```bash
# Step 1: Create a voice clone from audio sample
# No ID needed - creates new voice clone
curl -X POST "https://api.lowcodeapi.com/playht/api/v2/cloned-voices/instant?api_token=YOUR_API_TOKEN" \
  -F "voice_name=John Voice" \
  -F "sample_file=@john_voice_sample.mp3"

# Step 2: List all cloned voices to get the voice ID
# No ID needed - lists cloned voices
curl -X GET "https://api.lowcodeapi.com/playht/api/v2/cloned-voices?api_token=YOUR_API_TOKEN"

# Step 3: Use the cloned voice for TTS
# Replace VOICE_ID with the actual cloned voice ID from Step 2
curl -X POST "https://api.lowcodeapi.com/playht/api/v2/tts?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is John speaking with his cloned voice",
    "voice": "VOICE_ID"
  }'
```

### Example 3: Stream Real-time Audio

Generate streaming audio for low-latency applications:

```bash
# Step 1: Stream audio in real-time
# No ID needed - streams audio immediately
curl -X POST "https://api.lowcodeapi.com/playht/api/v2/tts/stream?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Real-time streaming audio example",
    "voice": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
    "output_format": "mp3"
  }' \
  --output audio.mp3
```

## Complete Endpoint Reference

For a complete list of all 7 endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/playht/definition
- **Official PlayHT Documentation**: https://docs.play.ht/reference/api-getting-started

## Voice Engine Options

- **PlayHT2.0-turbo** - Fastest generation, high quality
- **PlayHT2.0** - Best quality, supports emotions
- **PlayHT1.0** - Legacy engine, mp3/mulaw only

## Emotion Support (PlayHT2.0 engines only)

- **Female**: female_happy, female_sad, female_angry, female_fearful, female_disgust, female_surprised
- **Male**: male_happy, male_sad, male_angry, male_fearful, male_disgust, male_surprised

## Rate Limits & Best Practices

- **Rate Limit**: Refer to your PlayHT account plan
- **Best Practices**:
  - Use streaming endpoint for real-time applications
  - Set appropriate sample rates for your use case (24000 Hz recommended)
  - Use seed parameter for reproducible audio generation
  - Cache voice IDs to avoid repeated voice listing calls
  - Start with draft quality for testing, use premium for production
  - Keep text segments under 5000 characters for best results

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from PlayHT
  }
}
```

Common errors:
- **400 Bad Request**: Invalid parameters or voice ID
- **401 Unauthorized**: Invalid API credentials
- **404 Not Found**: Voice or job not found
- **429 Too Many Requests**: Rate limit exceeded
- **500 Server Error**: PlayHT server error