음성 복제 API

음성 복제 API는 참조 음성, 참조 음성의 정확한 transcript와 합성할 텍스트를 하나의 multipart request로 받아 음성을 반환합니다.

API 한눈에 보기

항목	값
Base URL	https://api.kitschlabs.com
인증	xi-api-key: <API_KEY>
Method	POST
Endpoint	/v1/voice-cloning/text-to-speech
Content-Type	multipart/form-data
기본 출력	mp3_44100_128 (audio/mpeg)
추가 출력	wav_24000 (audio/wav)

어떻게 인증하나요?

xi-api-key 헤더에 발급받은 API 키를 보냅니다. 실제 키는 서버 환경 변수나 비밀 관리 서비스에 보관하고 브라우저, 앱 번들, 로그에 남기지 마세요.

xi-api-key: <API_KEY>

음성을 어떻게 생성하나요?

참조 음성과 reference_text가 정확히 일치해야 합니다. 아래 예제는 참조 파일과 합성할 문장을 한 요청에 함께 보냅니다.

cURL

curl --request POST \
  "https://api.kitschlabs.com/v1/voice-cloning/text-to-speech?output_format=wav_24000" \
  --header "xi-api-key: <API_KEY>" \
  --form "text=This is the text to synthesize." \
  --form "reference_text=This is the exact reference transcript." \
  --form "reference_audio=@reference.wav" \
  --form "language_code=en" \
  --output speech.wav

Python

import os

import requests

with open("reference.wav", "rb") as reference_audio:
    response = requests.post(
        "https://api.kitschlabs.com/v1/voice-cloning/text-to-speech",
        params={"output_format": "wav_24000"},
        headers={"xi-api-key": os.environ["KITSCH_API_KEY"]},
        data={
            "text": "This is the text to synthesize.",
            "reference_text": "This is the exact reference transcript.",
            "language_code": "en",
        },
        files={"reference_audio": reference_audio},
        timeout=120,
    )

response.raise_for_status()

with open("speech.wav", "wb") as audio_file:
    audio_file.write(response.content)

JavaScript

import { readFile, writeFile } from "node:fs/promises";

const form = new FormData();
form.append("text", "This is the text to synthesize.");
form.append("reference_text", "This is the exact reference transcript.");
form.append("reference_audio", new Blob([await readFile("reference.wav")]), "reference.wav");
form.append("language_code", "en");

const response = await fetch(
  "https://api.kitschlabs.com/v1/voice-cloning/text-to-speech?output_format=wav_24000",
  {
    method: "POST",
    headers: {"xi-api-key": process.env.KITSCH_API_KEY},
    body: form,
  },
);

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

await writeFile("speech.wav", Buffer.from(await response.arrayBuffer()));

어떤 필드를 보내나요?

필드	위치	타입	필수	설명
text	form	string	예	합성할 텍스트
reference_text	form	string	예	참조 음성에서 실제로 말한 정확한 transcript
reference_audio	form	file	예	WAV, MP3, FLAC 또는 OGG 파일
language_code	form	string	아니요	en, ko, ja, zh 중 하나
instruct	form	string	아니요	말하기 방식에 대한 자연어 지시
speed	form	number	아니요	발화 속도. 0.25부터 4
output_format	query	string	아니요	mp3_44100_128 또는 wav_24000

참조 음성은 최대 25 MiB, 20초까지 지원합니다. reference_text에는 timestamp, 화자명, 자막 기호나 번역을 넣지 말고 실제로 들리는 발화만 적으세요.

참조 음성은 어떻게 준비하나요?

• 한 명이 말하는 깨끗한 speech-only clip을 사용합니다.
• 음악, 반향, 배경 대화와 강한 noise를 피합니다.
• clip의 시작과 끝에서 음성을 자르지 않습니다.
• 필요한 발음과 톤이 잘 드러나는 구간을 고릅니다.
• 본인 음성이거나 명시적으로 사용 허가를 받은 음성만 사용합니다.

권리가 있는 음성만 사용하세요

동의 없이 타인의 음성을 복제하거나 사칭, 기만, 권리 침해 목적으로 사용하지 마세요.

응답과 오류

성공하면 선택한 output_format의 audio binary를 반환합니다. 응답을 파일로 저장하고 x-kitsch-request-id를 운영 로그에 남기세요.

상태 코드	의미	권장 행동
400·422	필수 값, transcript 또는 파일 형식 오류	요청 값과 참조 음성을 수정
401	API 키가 없거나 유효하지 않음	키와 xi-api-key 헤더 확인
402	사용 가능한 credit 부족	결제 및 청구 상태 확인
413	참조 음성 크기 초과	25 MiB 이하로 줄여 재요청
429	계정별 요청 한도 초과	Retry-After를 따르고 backoff 적용
5xx	일시적인 서버 오류	request ID를 기록하고 제한적으로 재시도