> ## 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.
# List voices
> 계정에서 사용 가능한 모든 프리셋 보이스를 가져옵니다.
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/api-reference/endpoints/list-voices)을 함께 확인해 주세요.
계정에서 사용 가능한 프리셋 보이스 라이브러리를 반환합니다. Supertone Play 보이스 라이브러리와 Enterprise 고객에게 독점적으로 제공된 보이스가 모두 포함됩니다.
고객이 직접 클론한 보이스는 [List custom voices](/ko/api-reference/endpoints/list-custom-voices)를 사용해 주십시오.
## 엔드포인트
```http theme={"dark"}
GET https://supertoneapi.com/v1/voices
```
## 쿼리 파라미터
| Name | Required | Description |
| ----------------- | :------: | --------------------------------- |
| `page_size` | — | 페이지당 항목 수입니다. 기본값 `20`, 최대 `100`. |
| `next_page_token` | — | 다음 페이지를 가져오기 위한 이전 응답의 토큰입니다. |
## 응답
`items` 배열과 페이지네이션을 위한 선택적 `next_page_token`을 반환합니다. 각 항목은 [보이스 객체](/ko/docs/core-concepts/voices#the-voice-object) 형식을 따릅니다 — `voice_id`, `name`, `language`, `styles`, `models`, `samples` 등.
## 함께 보기
보이스 객체의 구조와 TTS 호출에서 보이스 ID를 사용하는 방법입니다.
언어, 스타일, 성별 등으로 필터링합니다.
## OpenAPI
````yaml openapi.json GET /v1/voices
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:
get:
tags:
- voices
summary: Gets available voices
description: >-
Gets a paginated list of voices available to the user based on internal
group logic, using token-based pagination.
operationId: list_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
responses:
'200':
description: Paginated available voices response with next page token
content:
application/json:
schema:
$ref: '#/components/schemas/GetAPICharacterListResponse'
'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:
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
````