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

# 퀵 클로닝

> 짧은 오디오 샘플을 업로드해 커스텀 보이스를 생성하면, 이후 텍스트 음성 변환 호출에서 기본 보이스와 동일하게 사용할 수 있습니다.

WAV 또는 MP3 파일(최대 25MB)을 업로드하면 서버가 speaker embedding 을 추출하여 `uc_` prefix 가 붙은 커스텀 보이스 ID 를 반환합니다. 이 ID 는 `POST /v1/text-to-speech` 의 `voice_id` 등 voice_id 를 받는 어떤 엔드포인트에도 그대로 전달할 수 있습니다. 원본 오디오는 응답 후 background 에서 S3 에 업로드됩니다.

**제한 사항**

- 오디오 파일: 최대 25MB. WAV 또는 MP3.
- 오디오 길이: 5초 이상 150초 이하.
- 보이스 이름: 1~30자.
- 모델: `ssfm-v21` 또는 `ssfm-v30`. 클로닝된 보이스는 해당 엔진 모델에 묶입니다.
- 플랜별로 동시에 보유 가능한 커스텀 보이스 수가 제한됩니다(`custom_voice_slot`). 슬롯이 가득 찼다면 `DELETE /v1/voices/{voice_id}` 로 비워주세요.

**일반 사용 흐름**

1. `POST /v1/voices/clone` 으로 샘플 오디오 업로드 → `voice_id` 수신 (예: `uc_64a1b2...`).
2. `POST /v1/text-to-speech` 의 `voice_id` 에 클로닝된 ID 사용.
3. 더 이상 필요 없으면 `DELETE /v1/voices/{voice_id}` 로 삭제.



## OpenAPI

````yaml /ko/api-reference/openapi.json post /v1/voices/clone
openapi: 3.1.0
info:
  title: Typecast API
  version: 0.1.2
  x-logo:
    url: https://typecast.ai/_ipx/_/image/logo/tc_logo.webp
servers:
  - url: https://api.typecast.ai
    description: 프로덕션 서버
security:
  - ApiKeyAuth: []
paths:
  /v1/voices/clone:
    post:
      tags:
        - Voices
      summary: 퀵 클로닝
      description: >-
        짧은 오디오 샘플을 업로드해 커스텀 보이스를 생성하면, 이후 텍스트 음성 변환 호출에서 기본 보이스와 동일하게 사용할 수
        있습니다.


        WAV 또는 MP3 파일(최대 25MB)을 업로드하면 서버가 speaker embedding 을 추출하여 `uc_` prefix
        가 붙은 커스텀 보이스 ID 를 반환합니다. 이 ID 는 `POST /v1/text-to-speech` 의 `voice_id` 등
        voice_id 를 받는 어떤 엔드포인트에도 그대로 전달할 수 있습니다. 원본 오디오는 응답 후 background 에서 S3 에
        업로드됩니다.


        **제한 사항**


        - 오디오 파일: 최대 25MB. WAV 또는 MP3.

        - 오디오 길이: 5초 이상 150초 이하.

        - 보이스 이름: 1~30자.

        - 모델: `ssfm-v21` 또는 `ssfm-v30`. 클로닝된 보이스는 해당 엔진 모델에 묶입니다.

        - 플랜별로 동시에 보유 가능한 커스텀 보이스 수가 제한됩니다(`custom_voice_slot`). 슬롯이 가득 찼다면
        `DELETE /v1/voices/{voice_id}` 로 비워주세요.


        **일반 사용 흐름**


        1. `POST /v1/voices/clone` 으로 샘플 오디오 업로드 → `voice_id` 수신 (예:
        `uc_64a1b2...`).

        2. `POST /v1/text-to-speech` 의 `voice_id` 에 클로닝된 ID 사용.

        3. 더 이상 필요 없으면 `DELETE /v1/voices/{voice_id}` 로 삭제.
      operationId: create_voice_clone_v1_voices_clone_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_create_voice_clone_v1_voices_clone_post
              type: object
              required:
                - file
                - name
                - model
              properties:
                file:
                  type: string
                  format: binary
                  description: 오디오 샘플. WAV 또는 MP3, 최대 25MB, 5초 이상 150초 이하.
                name:
                  type: string
                  minLength: 1
                  maxLength: 30
                  description: 보이스 이름 (1~30자).
                model:
                  type: string
                  enum:
                    - ssfm-v21
                    - ssfm-v30
                  description: 보이스를 클로닝할 엔진 모델.
        required: true
      responses:
        '200':
          description: Successful Response - Custom voice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomVoiceResponse'
              example:
                voice_id: uc_64a1b2c3d4e5f6a7b8c9d0e1
                name: my-voice
                model: ssfm-v30
        '400':
          description: >-
            Bad Request - Invalid audio file, file size, duration, or other
            validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                file_too_large:
                  summary: File is too large
                  value:
                    detail: File size exceeds maximum limit
                audio_too_short:
                  summary: Audio is shorter than 5 seconds
                  value:
                    detail: Audio duration is below minimum
                audio_too_long:
                  summary: Audio is longer than 150 seconds
                  value:
                    detail: Audio duration exceeds maximum
                audio_unreadable:
                  summary: Audio metadata cannot be read
                  value:
                    detail: Failed to read audio metadata
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Invalid API key
        '403':
          description: Forbidden - Voice cloning is not available on your plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Voice cloning is not available on your plan
        '422':
          description: Validation Error - Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Invalid request format
        '429':
          description: Too Many Requests - Rate limit or concurrency limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Too many requests
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl --request POST \
              --url 'https://api.typecast.ai/v1/voices/clone' \
              --header 'X-API-KEY: <api-key>' \
              -F 'file=@sample.wav' \
              -F 'name=my-voice' \
              -F 'model=ssfm-v30'
        - lang: Python
          label: Python (requests)
          source: >
            import requests


            with open("sample.wav", "rb") as f:
                response = requests.post(
                    "https://api.typecast.ai/v1/voices/clone",
                    headers={"X-API-KEY": "<api-key>"},
                    files={"file": ("sample.wav", f, "audio/wav")},
                    data={"name": "my-voice", "model": "ssfm-v30"},
                )

            print(response.json())

            # {"voice_id": "uc_64a1b2c3d4e5f6a7b8c9d0e1", "name": "my-voice",
            "model": "ssfm-v30"}
components:
  schemas:
    Body_create_voice_clone_v1_voices_clone_post:
      type: object
      properties:
        file:
          type: string
          title: File
          description: 오디오 샘플. WAV 또는 MP3, 최대 25MB, 5초 이상 150초 이하.
          contentMediaType: application/octet-stream
          format: binary
        name:
          type: string
          title: Name
          description: 보이스 이름 (1~30자).
          maxLength: 30
          minLength: 1
        model:
          $ref: '#/components/schemas/TTSModel'
          description: 클로닝할 엔진 모델 (`ssfm-v21` 또는 `ssfm-v30`).
          allOf:
            - $ref: '#/components/schemas/TTSModel'
      required:
        - file
        - name
        - model
      title: Body_create_voice_clone_v1_voices_clone_post
      description: 퀵 클로닝 요청을 위한 multipart 본문.
    CustomVoiceResponse:
      type: object
      properties:
        voice_id:
          type: string
          title: Voice Id
          description: >-
            `uc_` prefix 가 붙은 커스텀 보이스 식별자. `POST /v1/text-to-speech` 등
            `voice_id` 를 받는 엔드포인트에 그대로 사용할 수 있습니다.
          example: uc_64a1b2c3d4e5f6a7b8c9d0e1
        name:
          type: string
          title: Name
          description: 보이스 이름 (1~30자).
        model:
          type: string
          title: Model
          description: 보이스가 클로닝된 엔진 모델 (`ssfm-v21` 또는 `ssfm-v30`).
          allOf:
            - $ref: '#/components/schemas/TTSModel'
      required:
        - voice_id
        - name
        - model
      title: CustomVoiceResponse
      description: '`POST /v1/voices/clone` 응답 — 퀵 클로닝으로 생성된 커스텀 보이스 메타데이터.'
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: 문제를 설명하는 오류 메시지
      required:
        - detail
      example:
        detail: An error occurred processing the request
    TTSModel:
      type: string
      enum:
        - ssfm-v30
        - ssfm-v21
      title: TTSModel
      description: |
        음성 합성에 사용할 TTS 모델 버전. 다양한 모델은 다양한 기능과 품질 수준을 제공합니다.

        사용 가능한 모델:
        - **ssfm-v30**: 향상된 플로우와 추가 감정 프리셋이 있는 최신 모델(권장)
        - **ssfm-v21**: 검증된 신뢰성과 일관된 품질을 갖춘 안정적인 모델
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: 인증을 위한 API 키. 타입캐스트 API 콘솔에서 API 키를 생성할 수 있습니다.

````