> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxnexus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Text to Speech

> Convert text to speech audio, returns audio data in real-time using chunked streaming by default



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/tts
openapi: 3.0.0
info:
  title: VoxNexus API
  version: 1.0.0
  description: VoxNexus API Documentation
  contact:
    name: API Support
    url: https://voxnexus.ai/support
    email: support@voxnexus.ai
servers:
  - url: https://api.voxnexus.ai
security: []
paths:
  /v1/tts:
    post:
      tags:
        - tts
      summary: Text to Speech
      description: >-
        Convert text to speech audio, returns audio data in real-time using
        chunked streaming by default
      operationId: textToSpeech
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TTSRequest'
      responses:
        '200':
          description: Successfully returns audio stream
          headers:
            X-Request-ID:
              schema:
                type: string
              description: Request ID
            X-Voice-ID:
              schema:
                type: string
              description: Voice ID used
            X-Language:
              schema:
                type: string
              description: Language code
            X-Audio-Format:
              schema:
                type: string
              description: Audio format
            X-Sample-Rate:
              schema:
                type: integer
              description: Sample rate
            Transfer-Encoding:
              schema:
                type: string
                example: chunked
              description: Transfer encoding (defaults to chunked streaming)
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
            audio/wav:
              schema:
                type: string
                format: binary
            audio/ogg:
              schema:
                type: string
                format: binary
            audio/pcm:
              schema:
                type: string
                format: binary
            audio/webm:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Insufficient credits or rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TTSRequest:
      type: object
      properties:
        text:
          type: string
          description: Text to convert (required)
          example: Hello, this is a test message.
        model_id:
          type: string
          description: |
            Model identifier (required). Specifies which model to use for TTS.
          example: vn-tts-basic
        voice_id:
          type: string
          description: |
            Voice unique identifier (required)
          example: vn-xiaoxiao
        language:
          type: string
          description: >
            Language or locale code (optional, default: "en-US"). Supports both
            ISO 639-1 language codes (e.g. "en", "zh") 

            and BCP 47 locale codes (e.g. "en-US", "zh-CN"). When a language
            code is provided, 

            the system will automatically resolve it to the most common locale
            (e.g. "en" -> "en-US").
          default: en-US
          example: zh-CN
        format:
          type: string
          description: 'Audio format (optional, default: wav)'
          enum:
            - wav
            - pcm
          default: wav
        sample_rate:
          type: integer
          description: 'Sample rate (optional, default: 16000)'
          enum:
            - 16000
            - 24000
            - 48000
          default: 16000
        bit_rate:
          type: integer
          description: >-
            Bit rate (kbps), only valid for compressed formats (NOT SUPPORTED
            YET)
          deprecated: true
          default: 128
          example: 128
        speed:
          type: number
          format: float
          description: 'Speech rate multiplier, range: 0.5 - 2.0, default: 1.0 (optional)'
          minimum: 0.5
          maximum: 2
          default: 1
        pitch:
          type: integer
          description: 'Pitch offset (semitones), range: -12 - 12, default: 0 (optional)'
          minimum: -12
          maximum: 12
          default: 0
        volume:
          type: number
          format: float
          description: 'Volume multiplier, range: 0.0 - 1.0, default: 1.0 (optional)'
          minimum: 0
          maximum: 1
          default: 1
        voice_config:
          type: object
          description: >-
            Voice-specific configuration (optional) — a flat key-value map;
            supported keys are listed in the voice's config_schema (GET
            /v1/voices/{voice_id}), unknown keys are ignored
          additionalProperties: true
          example:
            style: cheerful
            role: Girl
            style_degree: 0.5
      required:
        - text
        - voice_id
        - model_id
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Invalid request parameters
        code:
          type: string
          description: Error code
          example: INVALID_REQUEST
        details:
          type: string
          description: Detailed error information (optional)
          example: Detailed error information
        request_id:
          type: string
          description: Request ID (optional)
          example: req_1234567890
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Authenticate using X-Api-Key header

````