> ## 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.

# Search Voices

> Search voices by keyword



## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/voices/search
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/voices/search:
    get:
      tags:
        - voices
      summary: Search Voices
      description: Search voices by keyword
      operationId: searchVoices
      parameters:
        - name: q
          in: query
          description: Search keyword (required)
          required: true
          schema:
            type: string
            example: xiaoxiao
        - name: language
          in: query
          description: Language code (optional)
          required: false
          schema:
            type: string
            example: zh
        - name: locale
          in: query
          description: Locale code (optional, e.g., zh-CN, en-US)
          required: false
          schema:
            type: string
            example: zh-CN
        - name: gender
          in: query
          description: Gender (optional)
          required: false
          schema:
            type: string
            enum:
              - male
              - female
              - neutral
        - name: category
          in: query
          description: Voice category (optional)
          required: false
          schema:
            type: string
            enum:
              - premade
              - cloned
              - generated
        - name: style
          in: query
          description: >
            Voice style filter (optional).

            Filters voices that support the specified style in their
            config_schema.style.enum.

            Common styles: cheerful, sad, angry, friendly, newscast, etc.
          required: false
          schema:
            type: string
            example: cheerful
        - name: page
          in: query
          description: Page number (default 1)
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: page_size
          in: query
          description: Items per page (default 20, max 100)
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Successfully returns search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoicesResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    VoicesResponse:
      type: object
      properties:
        voices:
          type: array
          description: Voice list
          items:
            $ref: '#/components/schemas/Voice'
        pagination:
          type: object
          properties:
            page:
              type: integer
              description: Current page number
              example: 1
            page_size:
              type: integer
              description: Items per page
              example: 20
            total:
              type: integer
              description: Total count
              example: 150
            total_pages:
              type: integer
              description: Total pages
              example: 8
          required:
            - page
            - page_size
            - total
            - total_pages
      required:
        - voices
        - pagination
    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
    Voice:
      type: object
      properties:
        voice_id:
          type: string
          description: Voice unique identifier
          example: vn-xiaoxiao
        name:
          type: string
          description: Voice name
          example: Xiaoxiao
        display_name:
          type: string
          description: Display name (localized)
          example: Xiaoxiao
        gender:
          type: string
          description: Gender
          enum:
            - male
            - female
            - neutral
          example: female
        category:
          type: string
          description: Voice category
          enum:
            - premade
            - cloned
            - generated
          example: premade
        description:
          type: string
          description: Voice description
          example: A warm and friendly female voice, suitable for general scenarios
        primary_locale:
          type: string
          description: Primary locale code
          example: zh-CN
        is_multilingual:
          type: boolean
          description: Whether the voice supports multiple languages
          example: true
        supported_locales:
          type: array
          description: List of supported locales with details
          items:
            type: object
            properties:
              locale:
                type: string
                description: Locale code (e.g., en-US, zh-CN)
                example: zh-CN
              language:
                type: string
                description: Language code (ISO 639-1)
                example: zh
              locale_name:
                type: string
                description: Human-readable locale name
                example: Chinese (Simplified, China)
              accent:
                type: string
                description: Accent for this locale
                example: mandarin
              preview_url:
                type: string
                description: Preview audio URL for this locale
                example: https://api.voxnexus.ai/samples/vn-xiaoxiao/zh-CN.mp3
              is_primary:
                type: boolean
                description: Whether this is the primary locale
                example: true
            required:
              - locale
              - language
        labels:
          type: object
          description: Display labels (personalities, scenarios, etc.)
          additionalProperties: true
          example:
            personalities:
              - warm
              - friendly
            scenarios:
              - assistant
              - news
        preview_url:
          type: string
          description: Default sample audio URL
          example: https://api.voxnexus.ai/samples/vn-xiaoxiao.mp3
        config_schema:
          type: object
          description: >-
            Supported voice_config keys — a flat map from key to its definition
            (type/description/enum). Omitted when the voice has no configurable
            keys
          additionalProperties: true
          example:
            style:
              type: string
              description: Speaking style
              enum:
                - cheerful
                - sad
        models:
          type: array
          description: List of supported model IDs for this voice
          items:
            type: string
          example:
            - vn-tts-basic
            - vn-tts-ultra
      required:
        - voice_id
        - name
        - gender
        - primary_locale
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Authenticate using X-Api-Key header

````