한국어 TTS API: 한글 대본에 language ko 지정하기

한국어로 텍스트 음성 변환(TTS)을 하려면 한글로 쓴 대본을 보내고 언어를 한국어(ko)로 명시하세요. Sume API에서는 한글 transcript, 음성, language: "ko"를 담은 POST /v1/tts-1.0/generate 요청 하나면 됩니다. 이 요청은 Job으로 실행되며, 한국어 음성을 Sume에 호스팅된 오디오 파일로 반환합니다.

요청 필드는 2026-09-27에 확인한 Sume API 레퍼런스의 TTS 스키마에서 가져왔습니다. 이 레퍼런스는 API 레퍼런스 문서의 바탕이 되는 OpenAPI 문서입니다. 현재 동작이라고 설명한 검사는 Sume의 코드에서, 가격은 API 요금 페이지를 만드는 코드에서 확인했습니다. 요청 전반은 텍스트 음성 변환 API를 참고하고, 나중에 한국어 문구를 영상에 자막으로 입히려면 한국어 자막 API를 참고하세요.

한국어 TTS 요청은 어떻게 보내나요?

한국어 대본은 1–20,000자 범위로 transcript에 넣고, 언어는 BCP-47 / ISO-639 코드인 ko로 지정하세요. 음성은 목소리가 준비된 아바타의 avatar_id나 avatar_handle로 고르거나, 이미 있는 Sume voice.id로 고릅니다. voice.id는 음성 UUID나 Voices 라이브러리 ID(voi_ 뒤에 hex 문자 32개)입니다.

기본 async 모드는 status_url과 result_url을 담아 바로 응답합니다. Job과 결과 (영문) 문서에 나온 대로 terminal이 true가 될 때까지 status_url을 폴링한 다음 result_url을 읽으세요. 완료된 결과는 오디오를 media.sume.com 아티팩트로 제공합니다.

curl -X POST https://api.sume.com/v1/tts-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tts-ko-welcome-001" \
  -d '{
    "transcript": "안녕하세요. 오늘은 새 기능을 소개합니다.",
    "voice": { "id": "voi_0123456789abcdef0123456789abcdef" },
    "language": "ko",
    "output_format": { "container": "wav", "encoding": "pcm_s16le", "sample_rate": 44100 }
  }'

언어를 빼면 어떻게 되나요?

language를 생략하면 공급사 기본값인 영어가 쓰이며, Sume는 한글로만 된 대본에서 보조 수단으로만 ko를 추론합니다. 현재 코드에서 이 보조 추론은 글자 수를 세어 한글 글자가 라틴 문자보다 많을 때만 ko를 반환하므로, 영어 제품명이나 URL이 많이 섞인 대본은 영어로 처리될 수 있습니다. 한국어 대본에는 항상 language: "ko"를 함께 보내세요.

반대 방향의 실수는 거부됩니다. 현재 코드에서는 language: "ko"인데 대본에 한글 음절이 하나도 없으면 400 tts_language_script_mismatch로 실패하므로, annyeonghaseyo처럼 로마자로 적은 한국어는 거부됩니다. 오류 메시지는 다시 시도하기 전에 원문과 인코딩을 확인하라고 안내합니다. 잘못된 인코딩으로 깨진 한글은 음절이 모두 사라질 수 있고, 그러면 같은 방식으로 실패하기 때문입니다.

한국어는 어떤 음성으로 읽어야 하나요?

API 레퍼런스에는 한국어 음성 목록이 공개되어 있지 않습니다. Sume가 확인하는 것은 음성의 언어입니다. 현재 코드에서는 Sume에 음성의 주 언어가 기록되어 있고 그 언어가 한국어가 아니면 제출이 409 tts_voice_language_mismatch로 실패하며, 메시지는 발음이 부자연스럽게 들릴 수 있다고 경고합니다. 이 시점에는 Job도 요금도 생기지 않은 상태입니다.

• 그래도 그 음성을 쓰려면 같은 요청과 같은 Idempotency-Key에 confirm_language_mismatch: true를 더해 다시 보내세요. 이 재확인 절차는 API로 영상 보이스오버 번역하기에서 단계별로 다룹니다.
• 현재 코드에서는 언어가 기록되지 않은 음성은 검사하지 않으며, 아바타 자체의 음성은 언어가 영어로 설정된 채 복제됩니다. 긴 대본을 보내기 전에 짧은 한국어 문장 하나를 먼저 들어 보세요.

한국어 TTS 요금은 어떻게 매겨지나요?

텍스트 음성 변환 요금은 1,000자당 $0.0475이며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. 사용량은 공백과 문장 부호를 포함한 대본 글자 수로 계산하며, 한국어에만 적용되는 요율은 따로 없습니다. 현재 코드에서 과금되는 글자 수는 결과의 character_count와 마찬가지로 대본의 길이이며, ‘한’ 같은 한글 음절 하나가 한 글자입니다. 합성된 오디오가 1,200초를 넘으면 tts_duration_exceeded로 실패하며, 크레딧은 확정되지 않습니다.

한국어 TTS 요청은 왜 거부되었나요?

한국어 요청을 멈출 수 있는 검사는 네 가지입니다. 앞의 세 가지는 제출 시점에 응답하고, 마지막 하나는 크레딧을 확정하지 않은 채 Job을 실패시킵니다.