> ## 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 custom voices
> 계정에 등록된 모든 커스텀(클론드) 보이스를 가져옵니다.
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/api-reference/endpoints/list-custom-voices)을 함께 확인해 주세요.
계정이 소유한 커스텀 보이스를 반환합니다. [Supertone Play](https://play.supertone.ai)에서 생성된 보이스 클론과 [Create cloned voice](/ko/api-reference/endpoints/create-cloned-voice)로 생성된 클론이 **모두** 포함됩니다 — 두 경로 모두 동일한 목록에 반영됩니다.
## 엔드포인트
```http theme={"dark"}
GET https://supertoneapi.com/v1/custom-voices
```
## 쿼리 파라미터
| Name | Required | Description |
| ----------------- | :------: | --------------------------------- |
| `page_size` | — | 페이지당 항목 수입니다. 기본값 `20`, 최대 `100`. |
| `next_page_token` | — | 다음 페이지를 가져오기 위한 이전 응답의 토큰입니다. |
## 응답
커스텀 보이스 객체의 `items` 배열과 선택적 `next_page_token`을 반환합니다.
## 참고사항
* 커스텀 보이스는 **계정 범위**입니다 — 사용된 API 키의 계정이 소유한 보이스만 조회됩니다.
* 커스텀 보이스는 프리셋 보이스와 동일한 TTS 엔드포인트로 호출할 수 있습니다. 커스텀 `voice_id`를 그대로 전달해 주십시오.
## 함께 보기
클론드 보이스의 생성, 관리, 사용 방법입니다.
샘플을 업로드하여 새 클론을 등록합니다.
## OpenAPI
````yaml openapi.json GET /v1/custom-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/custom-voices:
get:
tags:
- custom_voices
summary: Gets custom (cloned) voices
description: >-
Gets a paginated list of custom (cloned) voices available to the user,
using token-based pagination.
operationId: list_custom_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 custom voices response with next page token
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomVoiceListResponse'
'401':
description: 'Unauthorized: Invalid API key'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
'404':
description: 'Not Found: No custom voices found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
'500':
description: 'Internal Server Error: Failed to get custom voices'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
security:
- api-key: []
components:
schemas:
GetCustomVoiceListResponse:
type: object
properties:
items:
description: List of custom voice items
type: array
items:
$ref: '#/components/schemas/GetCustomVoiceResponse'
total:
type: number
description: Total number of available custom voices
example: 25
next_page_token:
type: string
description: >-
Token for fetching the next page of results. A valid non-negative
integer string (e.g., "10", "20"). Null if no more pages.
example: '10'
required:
- items
- total
UnauthorizedErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Unauthorized error details
example:
message: Invalid API Key
error: Unauthorized
statusCode: 401
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
NotFoundErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Not found error details
example:
message: Voice not found
error: Not Found
statusCode: 404
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
InternalServerErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Internal server error details
example:
message: Failed to convert text to speech
error: Internal Server Error
statusCode: 500
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
GetCustomVoiceResponse:
type: object
properties:
voice_id:
type: string
description: Unique identifier for the voice
example: voice_123456789
name:
type: string
description: Name of the voice
example: My Custom Voice
description:
type: string
description: Description of the voice
example: A warm and friendly voice for customer service
nullable: true
required:
- voice_id
- name
ErrorMessageData:
type: object
properties:
message:
type: string
description: Error message
example: Invalid API Key
error:
type: string
description: Error type
example: Unauthorized
status_code:
type: number
description: HTTP status code
example: 401
required:
- message
- error
- status_code
securitySchemes:
api-key:
type: apiKey
in: header
name: x-sup-api-key
````