Build with PlayHT

List available voices — the public catalog, or your own cloned voices.

curl -s "https://playht.co/api/v1/voices?source=signature&language=en" \
  -H "Authorization: Bearer pk_live_..."

{
  "status": 200,
  "body": {
    "voices": [
      {
        "canonical_id": "abc123",
        "voice_source": "signature",
        "provider_brand": "elevenlabs",
        "name": "Rachel",
        "gender": "female",
        "language": "en",
        "accent": "american",
        "age": "young",
        "use_case": "narration",
        "description": "Calm, professional narration voice.",
        "preview_url": "https://yourapp.com/app/media?sig=...",
        "is_clone": false
      }
    ],
    "pagination": { "page": 1, "page_size": 20, "total": 534 }
  }
}

Results are cached per filter combination for 1 hour. Preview URLs are always routed through the signed media proxy — a vendor domain never reaches the response. provider_brand is a deprecated alias for voice_source, kept for backward compatibility — new integrations should use voice_source.

Convert text (or SSML) to speech. Long text is automatically chunked and merged server-side.

curl -s -X POST https://playht.co/api/v1/tts \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world!", "voice_id": "abc123", "output_format": "mp3"}'

{
  "status": 200,
  "body": {
    "status": "processing",
    "task_id": "t1_9f8c2a..."
  }
}

// or, when the vendor is temporarily at capacity and queueing is enabled:
// HTTP 202
{
  "status": "queued",
  "job_id": "7f3e1a2b-...",
  "message": "The service is busy. Your job has been queued and will be processed automatically."
}

Text longer than the configured chunk size (default 800 chars) is split, submitted as separate vendor tasks, and merged with ffmpeg once every chunk completes — poll GET /tts-job/{job_id} for those. Short, single-chunk requests return a task_id instead — poll GET /tts-poll/{task_id}. Credits are reserved on submission and only charged once audio is confirmed stored.

Generate a multi-speaker spoken dialogue from a script.

curl -s -X POST https://playht.co/api/v1/dialogue \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "speakers": [{"name": "Alex", "voice_id": "abc123"}, {"name": "Jordan", "voice_id": "def456"}],
    "inputs": [{"speaker": "Alex", "text": "Hey, have you tried the new API?"}, {"speaker": "Jordan", "text": "Not yet, how is it?"}]
  }'

{
  "status": 200,
  "body": {
    "status": "processing",
    "task_id": "t1_4b7d1e..."
  }
}

Poll the returned task_id with GET /task/{task_id}. Max speakers and max characters are admin-configured per vendor.

Re-voice an uploaded audio file as a different voice.

curl -s -X POST https://playht.co/api/v1/voice-changer \
  -H "Authorization: Bearer pk_live_..." \
  -F "[email protected]" \
  -F "voice_id=abc123"

{
  "status": 200,
  "body": {
    "status": "processing",
    "task_id": "t1_2c9a4f..."
  }
}

multipart/form-data, not JSON. Max file size is admin-configured (default 25MB). Poll with GET /task/{task_id}.

Translate and dub an audio/video file into another language.

curl -s -X POST https://playht.co/api/v1/dubbing \
  -H "Authorization: Bearer pk_live_..." \
  -F "[email protected]" \
  -F "target_lang=es"

{
  "status": 200,
  "body": {
    "status": "processing",
    "dubbing_id": "t1_7a1d3c..."
  }
}

multipart/form-data. Max file size is admin-configured (default 100MB). Poll with GET /task/{dubbing_id}.

Generate a sound effect from a text prompt.

curl -s -X POST https://playht.co/api/v1/sfx \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Glass shattering on a tile floor", "duration_seconds": 3}'

{
  "status": 200,
  "body": {
    "status": "processing",
    "task_id": "t1_5e8b2d..."
  }
}

Poll with GET /task/{task_id}.

Generate music from a text prompt.

curl -s -X POST https://playht.co/api/v1/music \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Upbeat lo-fi hip hop, 90 BPM", "duration_seconds": 30}'

{
  "status": 200,
  "body": {
    "status": "processing",
    "task_id": "t1_1f4a9b..."
  }
}

Poll with GET /task/{task_id}.

Transcribe an audio file to text.

curl -s -X POST https://playht.co/api/v1/stt \
  -H "Authorization: Bearer pk_live_..." \
  -F "[email protected]" \
  -F "diarize=true"

{
  "status": 200,
  "body": {
    "status": "processing",
    "task_id": "t1_6c3e8a..."
  }
}

// once complete, GET /task/{task_id} body includes:
{
  "status": "done",
  "output": {
    "text": "Hey, have you tried the new API?",
    "transcript": [...],
    "words": [...],
    "language": "en",
    "duration": 4.2
  }
}

multipart/form-data. Max file size is admin-configured (default 25MB). All fields are optional, so this endpoint has no field-validation errors of its own.

Strip background noise from an audio file, isolating the voice.

curl -s -X POST https://playht.co/api/v1/voice-isolate \
  -H "Authorization: Bearer pk_live_..." \
  -F "[email protected]"

{
  "status": 200,
  "body": {
    "status": "processing",
    "task_id": "t1_3d7f2b..."
  }
}

multipart/form-data. Max file size is admin-configured (default 25MB). Poll with GET /task/{task_id}.

Poll the status of any task returned by dialogue, voice-changer, dubbing, sfx, music, stt, or voice-isolate.

curl -s https://playht.co/api/v1/task/t1_9f8c2a... \
  -H "Authorization: Bearer pk_live_..."

{
  "status": 200,
  "body": {
    "status": "done",
    "audio_url": "https://yourapp.com/app/media?sig=...",
    "url": "https://yourapp.com/app/media?sig=...",
    "output_url": "https://yourapp.com/app/media?sig=..."
  }
}

Ownership is enforced: a task_id only resolves for the account that created it. All vendor-hosted media URLs are rewritten to the signed media proxy — a vendor domain never appears in the response.

Poll a single-chunk (short, unsplit) TTS submission. Finalizes the job — charges credits — on completion.

curl -s https://playht.co/api/v1/tts-poll/t1_9f8c2a... \
  -H "Authorization: Bearer pk_live_..."

{
  "status": 200,
  "body": {
    "status": "done",
    "audio_url": "https://yourapp.com/app/audio/...",
    "url": "https://yourapp.com/app/audio/...",
    "output_url": "https://yourapp.com/app/audio/..."
  }
}

Only use this for short text that did NOT get chunked (see POST /tts notes). Credits are charged here, on confirmed completion — not at submission time. If audio download/storage fails transiently, the response reports { "status": "doing", "progress": 99 } so the client keeps polling instead of a false failure.

Poll a chunked TTS job (long text that was automatically split and is being merged).

curl -s https://playht.co/api/v1/tts-job/7f3e1a2b-... \
  -H "Authorization: Bearer pk_live_..."

{
  "status": "complete",
  "audio_url": "https://yourapp.com/app/audio/...",
  "total_chunks": 4,
  "completed_chunks": 4
}

// while still running:
{
  "status": "processing",
  "total_chunks": 4,
  "completed_chunks": 2
}

// on failure:
{
  "status": "failed",
  "error": "1 chunk(s) failed to generate."
}

Each call polls any still-processing chunks, and once every chunk is done, merges them with ffmpeg server-side and charges credits (capped at the amount reserved at submission). If a chunk permanently fails, remaining credits for that job are released back to your balance automatically.