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

# Search voices

> **Searches and retrieves voices provided by Supertone based on specified criteria.**

You can filter Supertone provided voices available in your account by various conditions such as name, language, style, etc.

### Endpoint

```http theme={"dark"}
https://supertoneapi.com/v1/voices/search
```

### Key Parameters

| Parameter         | Description                                               | Example                                               |
| :---------------- | :-------------------------------------------------------- | :---------------------------------------------------- |
| `name`            | Search by voice name (partial match)                      | `Coco`                                                |
| `language`        | Voice language code (multiple inputs possible with comma) | `ko`, `en`, `ja`                                      |
| `gender`          | Voice gender (multiple inputs possible with comma)        | `male`, `female`                                      |
| `age`             | Voice age group                                           | `child`, `young-adult`, `middle-aged`, `elder`, etc.  |
| `use_case`        | Filter based on the primary use case                      | `audiobook`, `narration`, `advertisement`, etc.       |
| `use_cases`       | Filter based on recommended use cases                     | `audiobook`, `narration`, `advertisement`, etc.       |
| `style`           | Emotion style filter (The first value is the default)     | `neutral`, `happy`, `sad`, `angry`, etc.              |
| `description`     | Searchable by description (partial match)                 | `kind and gentle`, etc.                               |
| `model`           | Filter based on supported voice model                     | `sona_speech_1`, etc.                                 |
| `page_size`       | Number of items per page (default: 20, max: 100)          | `50`                                                  |
| `next_page_token` | Token for pagination                                      | `nextPageToken` value received from previous response |

> ⚠️ `sort` parameter is not supported.

### Example 1: Style and Language Condition Filter

```http theme={"dark"}
GET /v1/voices/search?style=happy&language=ko,en
```

Only voices that include happy in style and contain at least one of Korean (ko) and English (en) in language will be retrieved.

### Example 2: Apply Pagination

```http theme={"dark"}
GET /v1/voices/search?page_size=50&next_page_token=eyJpZCI6IjEyMzQ1In0=
```

* Fetches the next page in units of 50.
* The `next_page_token` value can be obtained from the previous response.

### Notes

* All parameters **can accept multiple conditions (OR) separated by commas.**

  ```http theme={"dark"}
  language=ko,en&style=happy,sad
  ```
* If non-existent combinations are entered, the response will be 200 OK but the results may be empty.
* The response structure includes an `items` array and `next_page_token` value, and also provides each voice's `voice_id`, style, sample URL, etc.


## OpenAPI

````yaml openapi.json get /v1/voices/search
openapi: 3.0.0
info:
  title: Supertone Public API
  description: >-
    Supertone API is a RESTful API for using our state-of-the-art AI voice
    models.
  version: 0.9.0
  contact: {}
servers:
  - url: https://supertoneapi.com
    description: Production
security: []
tags:
  - name: voices
    description: Voice Library API endpoints
  - name: custom_voices
    description: Custom Voice Management API endpoints
  - name: text_to_speech
    description: Text-to-Speech API endpoints
  - name: usage
    description: Usage Analytics API endpoints
paths:
  /v1/voices/search:
    get:
      tags:
        - voices
      summary: Search voices.
      description: Search and filter voices based on various parameters.
      operationId: search_voices
      parameters:
        - name: page_size
          required: false
          in: query
          description: 'Number of items per page (default: 20, min: 10, max: 100)'
          schema:
            type: number
        - name: next_page_token
          required: false
          in: query
          description: Token for pagination (obtained from the previous page's response)
          schema:
            type: string
        - name: name
          required: false
          in: query
          description: Search across name. Space separated.
          schema:
            type: string
        - name: description
          required: false
          in: query
          description: Search across description. Space separated.
          schema:
            type: string
        - name: language
          required: false
          in: query
          description: Filter by language (comma-separated)
          schema:
            type: string
        - name: gender
          required: false
          in: query
          description: Filter by gender (comma-separated)
          schema:
            type: string
        - name: age
          required: false
          in: query
          description: Filter by age (comma-separated)
          schema:
            type: string
        - name: use_case
          required: false
          in: query
          description: Filter by use case (comma-separated)
          schema:
            type: string
        - name: use_cases
          required: false
          in: query
          description: Filter by use cases array (comma-separated for OR logic)
          schema:
            type: string
        - name: style
          required: false
          in: query
          description: >-
            Filter by style (comma-separated for OR, semicolon-separated for
            AND). Mixing comma and semicolon is invalid and will result in 400.
            Note: AND semantics apply across styles on a single character;
            cloned voices have a single style and will only match AND when
            exactly one style is requested and equals the cloned voice style.
          schema:
            type: string
        - name: model
          required: false
          in: query
          description: Filter by model (comma-separated)
          schema:
            type: string
      responses:
        '200':
          description: Paginated available voices response with next page token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAPICharacterListResponse'
        '400':
          description: >-
            Bad Request: Invalid style parameter (use either comma (OR) or
            semicolon (AND), not both)
        '401':
          description: 'Unauthorized: Invalid API key'
        '404':
          description: 'Not Found: No voices found'
        '500':
          description: 'Internal Server Error: Failed to get voices'
      security:
        - api-key: []
components:
  schemas:
    GetAPICharacterListResponse:
      type: object
      properties:
        items:
          description: List of character items
          type: array
          items:
            $ref: '#/components/schemas/GetAPICharacterResponseData'
        total:
          type: number
          description: >-
            Total number of available characters (might be approximate or
            removed in future)
          example: 150
        next_page_token:
          type: string
          description: >-
            Token for fetching the next page of results. Undefined if no more
            pages.
          example: some_opaque_token_string_representing_last_id
      required:
        - items
        - total
    GetAPICharacterResponseData:
      type: object
      properties:
        voice_id:
          type: string
          description: Unique identifier for the voice
          example: <voice-id>
        name:
          type: string
          description: Name of the voice
          example: Agatha
        description:
          type: string
          description: Description of the voice
          example: ''
        age:
          type: string
          description: Age of the voice
          example: young-adult
        gender:
          type: string
          description: Gender of the voice
          example: female
        use_case:
          type: string
          description: Use case of the voice
          example: narration
        use_cases:
          description: Use cases of the voice (array)
          example:
            - narration
            - storytelling
          type: array
          items:
            type: string
        language:
          description: Languages supported by the voice
          example:
            - ar
            - bg
            - cs
            - da
            - de
            - el
            - en
            - es
            - et
            - fi
            - fr
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - nl
            - pl
            - pt
            - ro
            - ru
            - vi
          type: array
          items:
            type: string
        styles:
          description: Styles available for the voice
          example:
            - kind-default
            - normal
            - serene
          type: array
          items:
            type: string
        models:
          description: Models available for the voice
          example:
            - sona_speech_1
            - sona_speech_2
            - sona_speech_2_flash
            - sona_speech_2t
            - supertonic_api_1
          type: array
          items:
            type: string
        samples:
          description: URL to the sample audio file for the voice
          type: array
          items:
            $ref: '#/components/schemas/APISampleData'
        thumbnail_image_url:
          type: string
          description: URL to the thumbnail image for the voice
          example: https://example.com/thumbnails/voice-thumbnail.png
      required:
        - voice_id
        - name
        - description
        - age
        - gender
        - use_case
        - use_cases
        - language
        - styles
        - models
    APISampleData:
      type: object
      properties:
        language:
          type: string
          description: Language of the sample
          example: ko
        style:
          type: string
          description: Style of the sample
          example: kind-default
        model:
          type: string
          description: Model of the sample
          example: supertonic_api_1
        url:
          type: string
          description: URL to the sample audio file
          example: https://example.com/samples/sample-audio.wav
      required:
        - language
        - style
        - model
        - url
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-sup-api-key

````