> ## 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.
# Create cloned voice
> 샘플 오디오 파일을 업로드하여 새 커스텀 보이스를 등록합니다.
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/api-reference/endpoints/create-cloned-voice)을 함께 확인해 주세요.
업로드된 오디오 샘플로부터 보이스를 클론하여 계정의 커스텀 보이스로 등록합니다. 반환되는 `voice_id`는 프리셋 보이스와 동일한 TTS 엔드포인트로 즉시 호출할 수 있습니다.
**API를 통한** 보이스 클로닝은 Free 티어에서 제공되지 않습니다. Free 티어 계정은 [Supertone Play](https://play.supertone.ai)에서 클로닝할 수 있습니다.
## 엔드포인트
```http theme={"dark"}
POST https://supertoneapi.com/v1/custom-voices/cloned-voice
```
`multipart/form-data`로 전송해 주십시오.
## 요청 본문
| Field | Required | Description |
| ------------- | :------: | ---------------------------------------------- |
| `files` | ✅ | 클로닝할 오디오 샘플입니다. **WAV 또는 MP3, 3MB 미만이어야 합니다.** |
| `name` | ✅ | 보이스 이름입니다. 최대 100자. |
| `description` | — | 자유 형식 설명입니다. |
## 샘플 품질 팁
최상의 클론 품질을 위해서는:
* 배경 잡음이 적고 단일 화자만 녹음된 깨끗한 오디오를 사용해 주십시오.
* 일반적으로 5\~30초면 충분합니다.
* 모노를 권장하며, 샘플레이트는 높아도 무방합니다.
## 응답
할당된 `voice_id`를 포함한 새 커스텀 보이스 객체를 반환합니다. ID를 저장해 두었다가 [Create speech](/ko/api-reference/endpoints/text-to-speech)에 전달하여 보이스를 사용해 주십시오.
## 오류
| Status | Cause |
| ---------------------------- | ------------------------------------------ |
| `400 Bad Request` | `files` 또는 `name`이 누락되었거나, `name`이 너무 깁니다. |
| `413 Payload Too Large` | 오디오 파일이 3MB를 초과합니다. |
| `415 Unsupported Media Type` | 파일이 WAV 또는 MP3가 아닙니다. |
| `403 Forbidden` | Free 티어 계정입니다(API를 통한 클로닝이 허용되지 않습니다). |
## 함께 보기
SDK 예제와 함께 보는 라이프사이클 가이드입니다.
클론, 나열, 호출까지 엔드 투 엔드 예제입니다.
## OpenAPI
````yaml openapi.json post /v1/custom-voices/cloned-voice
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/cloned-voice:
post:
tags:
- custom_voices
summary: Create cloned voice
description: Creates a custom (cloned) voice from uploaded audio files.
operationId: create_cloned_voice
parameters: []
requestBody:
required: true
description: Audio file and voice metadata
content:
multipart/form-data:
schema:
type: object
properties:
files:
type: string
format: binary
description: >-
Audio file to clone voice from (all common audio formats
accepted, max 3MB)
name:
type: string
description: Name of the cloned voice
description:
type: string
description: Description of the cloned voice
required:
- files
- name
responses:
'200':
description: Successfully created cloned voice
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomVoiceResponse'
'400':
description: 'Bad Request: Invalid file or request data'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
'401':
description: 'Unauthorized: Invalid API key'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
'403':
description: >-
Forbidden: Insufficient tier access (STARTER tier or higher
required)
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
'404':
description: 'Not Found: No custom voices found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
'413':
description: 'Payload Too Large: File size exceeds 3MB limit'
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeErrorResponse'
'415':
description: 'Unsupported Media Type: Invalid audio file format'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeErrorResponse'
'429':
description: 'Rate Limit Exceeded: Too many requests (10 per 60 seconds)'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
'500':
description: 'Internal Server Error: Failed to get custom voices'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
security:
- api-key: []
components:
schemas:
CreateCustomVoiceResponse:
type: object
properties:
voice_id:
type: string
description: Unique identifier for the created voice
example: voice_123456789
required:
- voice_id
BadRequestErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
type: string
description: Bad request error message
example: Invalid request data
required:
- status
- message
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
ForbiddenErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Forbidden error details
example:
message: Permission denied
error: Forbidden
statusCode: 403
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
PayloadTooLargeErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Payload too large error details
example:
message: File too large
error: Payload Too Large
statusCode: 413
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
UnsupportedMediaTypeErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
type: string
description: Unsupported media type error message
example: >-
Unsupported audio format. Supported formats: WAV, MP3. Received:
application/json
required:
- status
- message
TooManyRequestsErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Too many requests error details
example:
message: rate limit exceeded
error: Too Many Requests
statusCode: 429
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
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
````