음성 합성 권장 사항

좋은 합성 결과는 자연스러운 문장, 정확한 문장 부호, 음성과 일치하는 언어 설정에서 시작합니다. 안정적인 운영을 위해서는 retry와 API 키 보관 방식도 함께 설계해야 합니다.

텍스트는 어느 길이로 보내야 하나요?

한 문장 또는 자연스럽게 한 번에 말할 발화 단위로 보내세요. 너무 짧게 자른 조각은 음높이, 속도, 쉼이 달라질 수 있고, 지나치게 긴 요청은 생성 시간과 실패 비용을 키웁니다.

• 문장 부호로 의도한 쉼과 끝을 명확히 표현합니다.
• 제목, 본문, 버튼 문구처럼 말하기 목적이 다른 텍스트는 요청을 나눕니다.
• 이어 읽는 문맥이 중요하면 자연스러운 문장 단위로 묶어 보냅니다.
• 같은 문장을 여러 조각으로 합칠 때는 최종 파일의 무음 구간을 확인합니다.

표현 태그는 어떻게 사용하나요?

지원 태그는 [laughter], [sigh], [en], [wa], [hnn]입니다. 태그는 발화 흐름 안에 직접 넣고, 한 문장에 너무 많이 사용하지 마세요.

정말 다행이에요. [sigh] 이제 마음을 놓아도 되겠네요.

지원하지 않는 대괄호 태그는 요청 오류로 처리됩니다. HTTP 요청에서 자유로운 연기 지시가 필요하면 instruct 필드에 자연어로 작성하세요.

언어와 음성은 어떻게 선택하나요?

요청 전에 /v1/voices를 조회하고, 계정에서 사용할 수 있는 voice_id와 language 조합을 선택하세요.

• 표시 이름 대신 안정적인 voice_id를 저장합니다.
• 본문 언어와 language_code를 일치시킵니다.
• 여러 언어가 섞이면 의미 있는 발화 단위로 나누어 각각 알맞은 언어를 지정합니다.
• 품질 비교에서는 text, voice, language, output format을 고정합니다.

어떤 출력 형식을 선택해야 하나요?

형식	사용하기 좋은 경우	주의점
mp3_44100_128	웹·앱 재생, 전송 크기 절감	손실 압축
wav_24000	후처리, 편집, 분석	파일 크기가 큼

일반 재생에는 기본값인 MP3를, 편집 파이프라인에는 WAV를 우선 검토하세요. 한 프로젝트 안에서는 sample rate와 format을 통일하면 후처리가 단순해집니다.

retry는 어떻게 설계하나요?

모든 실패를 재시도하지 마세요. 수정 없이 성공할 가능성이 있는 오류만 제한적으로 재시도합니다.

응답	재시도	권장 행동
400·422	아니요	입력과 지원 범위를 수정
401·402	아니요	인증 또는 결제 및 청구 상태 해결
404	보통 아니요	voice_id와 접근 권한 확인
429	예	Retry-After를 따르고 jitter가 있는 exponential backoff
500·502·503·504	제한적으로 예	같은 요청을 최대 2~3회 재시도
timeout	제한적으로 예	응답 수신 여부와 중복 처리를 먼저 확인

예를 들어 1초, 2초, 4초를 기준으로 작은 무작위 지연을 더할 수 있습니다. 대량 작업은 동시 요청 수를 제한하고 계정별 RPM 안에서 큐로 처리하세요. 정확한 한도는 API 키 또는 계약별로 다를 수 있습니다.

API 키는 어떻게 보관하나요?

• 서버 환경 변수나 비밀 관리 서비스에 저장합니다.
• 브라우저와 모바일 클라이언트에서 Kitsch API를 직접 호출하지 않습니다.
• 로그에는 전체 키 대신 prefix와 일부 preview만 남깁니다.
• 개발, staging, production 키를 분리합니다.
• 노출이 의심되면 즉시 revoke하고 새 키로 교체합니다.

export KITSCH_API_KEY="<API_KEY>"

운영 로그에는 무엇을 남기나요?

API 키나 전체 사용자 텍스트를 그대로 남기지 말고 아래 항목을 구조화해 기록하세요.

• 요청 시각과 애플리케이션 작업 ID
• endpoint, voice_id, language, output format
• HTTP 상태 코드
• x-kitsch-request-id
• retry 횟수와 최종 결과

문의할 때 request ID, 발생 시각, endpoint, 상태 코드를 전달하면 원인 확인이 빨라집니다.