openapi: 3.0.3
info:
  title: Neuphonic Agents Sse 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: Sse
paths:
  /sse/auth:
    post:
      summary: Authenticate for SSE
      description: 'Exchange an API key for a JWT token to be used in subsequent SSE requests. Using a JWT token allows faster authentication for subsequent requests.

        '
      operationId: swap_api_key_for_jwt_token_sse_auth_post
      parameters:
      - name: expiration
        in: query
        required: false
        schema:
          type: integer
          default: 3600
        description: JWT token expiration time in seconds (default 3600).
      - $ref: '#/components/parameters/ApiKeyQuery'
      - $ref: '#/components/parameters/JwtTokenQuery'
      - $ref: '#/components/parameters/ApiKeyHeader'
      - $ref: '#/components/parameters/AuthorizationHeader'
      responses:
        '200':
          description: JWT token issued successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      jwt_token:
                        type: string
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Sse
  /sse/speak/{lang_code}:
    post:
      summary: SSE Text-to-Speech
      description: 'Generate speech from text using Server-Sent Events (SSE) streaming. Returns a real-time audio stream in PCM format. Supports language selection, voice selection, speed control, and sampling rate configuration. Sub-25ms latency for the first audio chunk.

        '
      operationId: sse_generator_sse_speak__lang_code__post
      parameters:
      - name: lang_code
        in: path
        required: true
        schema:
          type: string
        description: 'Language code for the speech synthesis (e.g., en, es, de, fr, ur, ja, ko, zh, pt).

          '
      - $ref: '#/components/parameters/ApiKeyQuery'
      - $ref: '#/components/parameters/JwtTokenQuery'
      - $ref: '#/components/parameters/ApiKeyHeader'
      - $ref: '#/components/parameters/AuthorizationHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SseRequest'
      responses:
        '200':
          description: 'Streaming SSE response with audio data in PCM format.

            '
          content:
            text/event-stream:
              schema:
                type: string
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Sse
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'
    SseRequest:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          description: The text to synthesize into speech.
        voice:
          type: string
          description: Voice ID or name to use for synthesis.
        speed:
          type: number
          format: float
          description: Speech speed multiplier (e.g., 1.0 for normal speed).
        sampling_rate:
          type: integer
          description: Audio sampling rate in Hz (e.g., 22050, 44100).
  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).