openapi: 3.0.1
info:
  title: Async (Podcastle) Voice API
  description: >-
    The Async Voice API is the developer platform behind Podcastle's AI audio
    engine. It exposes low-latency, human-like text-to-speech, a browsable voice
    library, and instant voice cloning. Podcastle.ai rebranded its developer
    platform as Async; the API is served from https://api.async.com and
    authenticated with an x-api-key header plus a version header. Only
    documented endpoints and fields are modeled here; no endpoints are
    fabricated.
  termsOfService: https://async.com/terms
  contact:
    name: Async Support
    url: https://docs.async.com
  version: v1
servers:
  - url: https://api.async.com
    description: Async Voice API production base URL
security:
  - apiKey: []
tags:
  - name: Text to Speech
    description: Synthesize speech from text in batch, streaming, or with word timestamps.
  - name: Voices
    description: Browse the voice library and create instant voice clones.
paths:
  /text_to_speech:
    post:
      operationId: createSpeech
      tags:
        - Text to Speech
      summary: Generate audio from the input text.
      description: >-
        Converts a full transcript into a single audio file. On this endpoint
        only async_flash_v1.0 is documented as supported.
      parameters:
        - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechRequest'
      responses:
        '200':
          description: Audio file in the requested container format.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
            audio/wav:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /text_to_speech/streaming:
    post:
      operationId: createSpeechStreaming
      tags:
        - Text to Speech
      summary: Stream audio while it is being generated.
      description: >-
        Streams synthesized audio as it is generated, returning binary chunks as
        an octet-stream. Supports async_pro_v1.0, async_flash_v1.5, and
        async_flash_v1.0.
      parameters:
        - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechRequest'
      responses:
        '200':
          description: Binary audio stream.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /text_to_speech/with_timestamps:
    post:
      operationId: createSpeechWithTimestamps
      tags:
        - Text to Speech
      summary: Generate audio with word-level timestamps.
      description: >-
        Returns base64-encoded audio plus a word-level alignment object with
        per-word start and end times in milliseconds. On this endpoint only
        async_flash_v1.0 is documented as supported.
      parameters:
        - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechRequest'
      responses:
        '200':
          description: Audio with word alignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimestampedSpeechResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /voices:
    post:
      operationId: listVoices
      tags:
        - Voices
      summary: List voices from the voice library.
      description: >-
        Returns a paginated list of predefined and custom voices. Filters by
        model, language, accent, gender, and style are supported, along with a
        cursor for pagination.
      parameters:
        - $ref: '#/components/parameters/Version'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListVoicesRequest'
      responses:
        '200':
          description: A page of voices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVoicesResponse'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
  /voices/clone:
    post:
      operationId: cloneVoice
      tags:
        - Voices
      summary: Create an instant voice clone.
      description: >-
        Creates a production-ready custom voice from a short audio clip. Accepts
        multipart/form-data with the audio sample and optional metadata.
        Supported audio formats: wav, mp3, flac, aiff.
      parameters:
        - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CloneVoiceRequest'
      responses:
        '200':
          description: The newly created cloned voice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloneVoiceResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key issued from the Async developer console.
  parameters:
    Version:
      name: version
      in: header
      required: true
      description: API version, for example v1.
      schema:
        type: string
        example: v1
  schemas:
    Voice:
      type: object
      properties:
        mode:
          type: string
          description: Voice selection mode.
          enum:
            - id
        id:
          type: string
          description: Voice identifier from the voice library.
      required:
        - mode
        - id
    OutputFormat:
      type: object
      properties:
        container:
          type: string
          description: Audio container format.
          enum:
            - raw
            - mp3
            - wav
        encoding:
          type: string
          description: PCM encoding (used with the raw container).
          enum:
            - pcm_f32le
            - pcm_s16le
            - pcm_mulaw
          default: pcm_s16le
        sample_rate:
          type: integer
          description: Sample rate in Hz.
          minimum: 8000
          maximum: 48000
        bit_rate:
          type: integer
          description: Bit rate in bits per second (MP3 only).
          minimum: 32000
          maximum: 320000
          default: 192000
      required:
        - container
        - sample_rate
    TextToSpeechRequest:
      type: object
      properties:
        model_id:
          type: string
          description: >-
            Synthesis model. async_pro_v1.0 (English, highest quality),
            async_flash_v1.5 (six languages, optimized for speed), and
            async_flash_v1.0 (legacy, fifteen languages). The batch and
            with_timestamps endpoints document support for async_flash_v1.0.
          enum:
            - async_pro_v1.0
            - async_flash_v1.5
            - async_flash_v1.0
        transcript:
          type: string
          description: The text to convert to speech.
        voice:
          $ref: '#/components/schemas/Voice'
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        language:
          type: string
          description: Force synthesis in the specified language (ISO 639-1).
        speed_control:
          type: number
          description: Playback speed multiplier.
          minimum: 0.7
          maximum: 2.0
        stability:
          type: integer
          description: Voice stability.
          minimum: 0
          maximum: 100
      required:
        - model_id
        - transcript
        - voice
        - output_format
    TimestampedSpeechResponse:
      type: object
      properties:
        audio_base64:
          type: string
          description: Base64-encoded audio in the requested format.
        alignment:
          type: object
          description: Word-level timing aligned with the synthesized audio.
          properties:
            words:
              type: array
              items:
                type: string
            word_start_times_milliseconds:
              type: array
              items:
                type: number
            word_end_times_milliseconds:
              type: array
              items:
                type: number
    ListVoicesRequest:
      type: object
      properties:
        limit:
          type: integer
          description: Number of voices per page.
          minimum: 1
          maximum: 100
          default: 10
        model_id:
          type: string
          description: Filter by model.
        language:
          type: string
          description: Filter by language (ISO 639-1).
        accent:
          type: string
          description: Filter by accent.
        gender:
          type: string
          description: Filter by gender.
          enum:
            - Male
            - Female
            - Neutral
            - Unspecified
        style:
          type: string
          description: Filter by style.
        my_voice:
          type: boolean
          description: Return only voices owned by the current user.
        after:
          type: string
          description: Pagination cursor for subsequent pages.
    VoiceSummary:
      type: object
      properties:
        voice_id:
          type: string
        voice_type:
          type: string
          enum:
            - PREDEFINED
            - CUSTOM
        name:
          type: string
        description:
          type: string
        language:
          type: string
        gender:
          type: string
        accent:
          type: string
        style:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
    ListVoicesResponse:
      type: object
      properties:
        voices:
          type: array
          items:
            $ref: '#/components/schemas/VoiceSummary'
        next_cursor:
          type: string
          description: Cursor for fetching the next page.
    CloneVoiceRequest:
      type: object
      properties:
        audio:
          type: string
          format: binary
          description: 'Audio clip file. Supported formats: wav, mp3, flac, aiff.'
        name:
          type: string
          description: Voice name or label.
        description:
          type: string
          description: Voice description.
        accent:
          type: string
          description: Accent specification.
        gender:
          type: string
          description: Voice gender.
          enum:
            - Male
            - Female
            - Neutral
            - Unspecified
        style:
          type: string
          description: Voice style(s), comma-separated.
        enhance:
          type: boolean
          description: Apply noise reduction to the sample.
          default: false
      required:
        - audio
        - name
    CloneVoiceResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        language:
          type: string
          description: ISO 639-1 codes, comma-separated.
    Error:
      type: object
      properties:
        detail:
          type: object
          properties:
            error_code:
              type: string
            message:
              type: string
            extra:
              type: object
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'