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

> 프리셋 보이스 라이브러리를 언어, 스타일, 성별, 연령, 사용 사례, 모델로 필터링합니다.

<Note>
  이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/api-reference/endpoints/search-voices)을 함께 확인해 주세요.
</Note>

주어진 필터와 일치하는 프리셋 보이스를 반환합니다. 파라미터당 여러 값은 콤마로 구분되며 OR 조건으로 처리됩니다.

## 엔드포인트

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

## 쿼리 파라미터

| Name              | Description                       | Example                                        |
| ----------------- | --------------------------------- | ---------------------------------------------- |
| `name`            | 보이스 이름, 부분 일치.                    | `Coco`                                         |
| `description`     | 설명, 부분 일치.                        | `kind and gentle`                              |
| `language`        | 언어 코드, 콤마로 구분.                    | `ko,en,ja`                                     |
| `gender`          | 보이스 성별, 콤마로 구분.                   | `male,female`                                  |
| `age`             | 보이스 연령대.                          | `child`, `young-adult`, `middle-aged`, `elder` |
| `use_case`        | 주요 사용 사례.                         | `audiobook`, `narration`, `advertisement`      |
| `use_cases`       | 권장 사용 사례 (OR).                    | `audiobook,narration`                          |
| `style`           | 감정 스타일입니다. 첫 번째 값이 기본값입니다.        | `neutral`, `happy`, `sad`, `angry`             |
| `model`           | 지원 모델.                            | `sona_speech_1`                                |
| `page_size`       | 페이지당 항목 수입니다. 기본값 `20`, 최대 `100`. | `50`                                           |
| `next_page_token` | 이전 응답의 토큰입니다.                     | `eyJpZCI6IjEyMzQ1In0=`                         |

<Note>
  `sort`는 지원되지 않습니다. 결과는 자연 순서로 반환되므로 필요하면 클라이언트 측에서 정렬해 주십시오.
</Note>

## 예시

**스타일과 언어로 필터링:**

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

스타일 목록에 `happy`가 포함되고 한국어 또는 영어를 지원하는 보이스를 반환합니다.

**페이지네이션:**

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

## 응답

`items`(보이스 객체 배열)와 `next_page_token`(문자열, 선택)을 반환합니다. 일치하는 보이스가 없으면 `items`는 빈 배열이며, 요청 자체는 `200 OK`를 반환합니다.

## 참고사항

* 콤마로 구분된 값은 **OR**로 결합됩니다: `language=ko,en&style=happy,sad`는 한국어 또는 영어를 지원하고 **동시에** 스타일에 happy 또는 sad가 포함된 보이스를 반환합니다.
* 빈 결과는 오류가 아닙니다 — 4xx 응답에 의존하지 말고 `items.length`로 확인해 주십시오.
* 전체 보이스 객체 구조(샘플, 지원 모델 등)는 [Voices](/ko/docs/core-concepts/voices#the-voice-object)를 참고해 주십시오.

## 함께 보기

<CardGroup cols={2}>
  <Card title="Docs: Voices" icon="users" href="/ko/docs/core-concepts/voices">
    SDK 코드와 함께 보는 개념 가이드입니다.
  </Card>

  <Card title="Voice search example" icon="lightbulb" href="/ko/docs/examples/voice-search-and-preview">
    앱 내 검색 가능한 보이스 선택기를 구축합니다.
  </Card>
</CardGroup>


## 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.6
  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: ''
          nullable: true
        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
            - supertonic_api_1
            - supertonic_api_3
          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
        - 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_3
        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

````