openapi: 3.1.0
info:
  title: PlayHT API
  description: |
    REST API for PlayHT TTS, voice listing, and voice cloning. The v2
    endpoints sit under https://api.play.ht/api/v2. Authentication uses two
    credentials supplied as headers: `AUTHORIZATION` (the secret API key)
    and `X-USER-ID` (the user identifier).
  version: "1.0.0"
  contact:
    name: API Evangelist
    email: kin@apievangelist.com
  license:
    name: Proprietary
servers:
  - url: https://api.play.ht/api/v2
    description: PlayHT v2 API
security:
  - apiKey: []
    userId: []
tags:
  - name: TTS
    description: Text-to-speech generation jobs.
  - name: Voices
    description: Prebuilt and cloned voice catalog.
paths:
  /tts:
    post:
      tags: [TTS]
      summary: Stream audio from text
      description: |
        Streams the audio bytes for the supplied text in real time using
        PlayHT's text-in, audio-out API.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TTSStreamRequest'
      responses:
        '200':
          description: Streamed audio bytes.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
            audio/wav:
              schema:
                type: string
                format: binary
  /tts/job:
    post:
      tags: [TTS]
      summary: Create a batch TTS job
      description: |
        Converts one or more input texts into audio asynchronously. Poll the
        job endpoints to retrieve completion status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TTSJobRequest'
      responses:
        '201':
          description: Job created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TTSJob'
    get:
      tags: [TTS]
      summary: Get batch TTS job details
      description: Retrieves batch job information including all child jobs and status.
      responses:
        '200':
          description: Batch job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TTSJob'
  /tts/job/{jobId}:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      tags: [TTS]
      summary: Get batch TTS child job by ID
      responses:
        '200':
          description: Child job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TTSJob'
  /voices:
    get:
      tags: [Voices]
      summary: List prebuilt voices
      description: Returns the complete inventory of available stock voices.
      responses:
        '200':
          description: Voice collection.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Voice'
  /cloned-voices:
    get:
      tags: [Voices]
      summary: List cloned voices
      description: Retrieves the list of all cloned voices created by the user.
      responses:
        '200':
          description: Cloned voice collection.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Voice'
        '401':
          description: Missing or invalid API credentials.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: AUTHORIZATION
      description: Secret API key generated in the PlayHT studio.
    userId:
      type: apiKey
      in: header
      name: X-USER-ID
      description: PlayHT user identifier paired with the API key.
  parameters:
    JobId:
      name: jobId
      in: path
      required: true
      schema:
        type: string
      description: TTS batch job identifier.
  schemas:
    TTSStreamRequest:
      type: object
      required: [text, voice]
      properties:
        text:
          type: string
          description: Text to synthesize.
        voice:
          type: string
          description: Voice identifier.
        voice_engine:
          type: string
          description: Voice engine, for example `PlayDialog`, `Play3.0-mini`.
        output_format:
          type: string
          enum: [mp3, wav, ogg, flac, mulaw]
        speed:
          type: number
        quality:
          type: string
          enum: [draft, low, medium, high, premium]
    TTSJobRequest:
      type: object
      required: [text, voice]
      properties:
        text:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        voice:
          type: string
        voice_engine:
          type: string
        output_format:
          type: string
        speed:
          type: number
        quality:
          type: string
    TTSJob:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [queued, processing, complete, failed]
        url:
          type: string
          format: uri
        duration:
          type: number
        created:
          type: string
          format: date-time
    Voice:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        language:
          type: string
        accent:
          type: string
        gender:
          type: string
        voice_engine:
          type: string
        sample:
          type: string
          format: uri