openapi: 3.0.3
info:
  title: Neuphonic Agents Voices API
  description: 'Neuphonic is an ultra-low-latency voice AI platform providing real-time text-to-speech synthesis, voice cloning, and conversational AI agent management. The API supports SSE streaming, voice management, and agent lifecycle operations. Authentication uses API keys via the X-API-KEY header or api_key query parameter.

    '
  version: 0.1.0
  contact:
    url: https://docs.neuphonic.com/
servers:
- url: https://api.neuphonic.com
  description: Neuphonic Production API
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Voices
paths:
  /voices:
    get:
      summary: List Voices
      description: 'Retrieves available voices for the text-to-speech (TTS) feature. Returns a list of TTS voices available in the application, including both standard and cloned voices.

        '
      operationId: tts_endpoint_voices_get
      parameters:
      - $ref: '#/components/parameters/ApiKeyQuery'
      - $ref: '#/components/parameters/JwtTokenQuery'
      - $ref: '#/components/parameters/ApiKeyHeader'
      - $ref: '#/components/parameters/AuthorizationHeader'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      voices:
                        type: array
                        items:
                          $ref: '#/components/schemas/Voice'
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Voices
    post:
      summary: Clone Voice
      description: 'Create a cloned voice by uploading an audio sample. Accepts MP3 or WAV files (minimum 6 seconds, under 10MB). Voice cloning is available in English, French, German, and Spanish.

        '
      operationId: clone_voice_voices_post
      parameters:
      - name: voice_name
        in: query
        required: true
        schema:
          type: string
        description: The desired name for the cloned voice.
      - name: voice_tags
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated tags associated with the voice.
      - name: lang_code
        in: query
        required: false
        schema:
          type: string
          default: en
        description: Language code for the cloned voice (e.g., en, fr, de, es).
      - $ref: '#/components/parameters/ApiKeyQuery'
      - $ref: '#/components/parameters/JwtTokenQuery'
      - $ref: '#/components/parameters/ApiKeyHeader'
      - $ref: '#/components/parameters/AuthorizationHeader'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - voice_file
              properties:
                voice_file:
                  type: string
                  format: binary
                  description: Audio file containing the voice sample (MP3 or WAV).
      responses:
        '200':
          description: Voice cloned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Voices
  /voices/{voice_id}:
    patch:
      summary: Update Voice
      description: 'Update the audio clip or metadata associated with a cloned voice. Requires the voice to belong to the authenticated user.

        '
      operationId: update_voice_voices__voice_id__patch
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the voice to update.
      - name: new_voice_name
        in: query
        required: false
        schema:
          type: string
        description: New name for the cloned voice.
      - name: new_voice_tags
        in: query
        required: false
        schema:
          type: string
        description: Updated comma-separated tags for the voice.
      - $ref: '#/components/parameters/ApiKeyQuery'
      - $ref: '#/components/parameters/JwtTokenQuery'
      - $ref: '#/components/parameters/ApiKeyHeader'
      - $ref: '#/components/parameters/AuthorizationHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                new_voice_file:
                  type: string
                  format: binary
                  nullable: true
                  description: New audio file to replace the existing voice sample.
      responses:
        '200':
          description: Voice updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Voices
    delete:
      summary: Delete Cloned Voice
      description: 'Delete a cloned voice from the system. Removes all associated data. The voice must belong to the authenticated user.

        '
      operationId: delete_cloned_voice_voices__voice_id__delete
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the voice to delete.
      - $ref: '#/components/parameters/ApiKeyQuery'
      - $ref: '#/components/parameters/JwtTokenQuery'
      - $ref: '#/components/parameters/ApiKeyHeader'
      - $ref: '#/components/parameters/AuthorizationHeader'
      responses:
        '200':
          description: Voice deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  voice_id:
                    type: string
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Voices
components:
  schemas:
    ValidationError:
      type: object
      required:
      - loc
      - msg
      - type
      properties:
        loc:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
          description: Location of the error in the request.
        msg:
          type: string
          description: Human-readable error message.
        type:
          type: string
          description: Error type identifier.
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    Voice:
      type: object
      properties:
        voice_id:
          type: string
          description: Unique identifier for the voice.
        voice_name:
          type: string
          description: Display name of the voice.
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the voice.
        lang_code:
          type: string
          description: Language code for the voice.
        is_cloned:
          type: boolean
          description: Whether this is a user-cloned voice.
  parameters:
    AuthorizationHeader:
      name: authorization
      in: header
      required: false
      schema:
        type: string
        nullable: true
      description: Bearer JWT token in the Authorization header.
    ApiKeyQuery:
      name: api_key
      in: query
      required: false
      schema:
        type: string
        nullable: true
      description: API key for authentication.
    JwtTokenQuery:
      name: jwt_token
      in: query
      required: false
      schema:
        type: string
        nullable: true
      description: JWT token obtained from /sse/auth for faster authentication.
    ApiKeyHeader:
      name: X-API-KEY
      in: header
      required: false
      schema:
        type: string
        nullable: true
      description: API key in the X-API-KEY header.
  responses:
    ValidationError:
      description: Validation Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HTTPValidationError'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key passed via the X-API-KEY request header.
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as a query parameter (used for WebSocket connections).