웹사이트용 TTS: 글마다 오디오 파일 하나 만들기

웹사이트에 텍스트 음성 변환(TTS)을 넣으려면 글을 발행하거나 수정할 때 서버에서 그 글의 오디오 파일을 생성해 저장하고, 페이지에서는 HTML <audio> 플레이어로 재생하세요. 그러면 모든 방문자가 같은 녹음을 듣고, 합성은 방문할 때마다가 아니라 텍스트 버전마다 한 번만 실행됩니다. Sume에서는 글 하나가 백엔드에서 호출하는 TTS 1.0 Job 하나(POST /v1/tts-1.0/generate)입니다.

Sume 관련 사실은 Sume API 레퍼런스의 TTS 1.0 스키마와 인증, 미디어 입력 문서에서 가져왔습니다. Sume API 레퍼런스는 API 레퍼런스 문서의 바탕이 되는 OpenAPI 문서입니다. 플레이어 동작은 MDN의 `<audio>` 요소 페이지를 따릅니다. 모두 2026-09-27에 확인했습니다. 요청 필드 전체는 텍스트 음성 변환 API에서 다룹니다.

글을 발행할 때 오디오는 어떻게 생성하나요?

CMS 웹훅, 빌드 단계, 백그라운드 작업처럼 이미 발행에 반응하고 있는 곳에서 실행하세요. 글마다 할 일은 다음과 같습니다.

• HTML 마크업을 뺀 글의 일반 텍스트를 transcript로 보내고, 음성은 사이트 전체에 하나만 쓰세요.
• Idempotency-Key는 article-812-rev-5처럼 글 ID와 리비전으로 만드세요. 같은 키와 본문으로 재시도하면 두 번째 Job을 과금하는 대신 원래 Job이 반환됩니다.
• Job이 끝날 때 콜백을 받으려면 공개 HTTPS webhook_url을 넘기고, 아니면 status_url을 폴링하세요. 콜백은 종료 상태(job.completed, job.failed, job.canceled)에서만 오고 서명되어 있으므로, 받은 콜백을 믿기 전에 서명을 검증하세요.
• GET /v1/jobs/{id}/result를 읽으세요. 현재 코드에서 여기의 audio_url은 Sume 미디어 호스트에 있는 파일이며, Sume는 생성 결과를 이 호스트로 미러링합니다. 이 URL을 글과 함께 저장하거나 파일을 자체 스토리지로 복사하세요. Sume 결과 URL이 얼마나 유지되는지를 참고하세요.

페이지에서 바로 TTS API를 호출하면 왜 안 되나요?

키가 모든 방문자에게 전달되기 때문입니다. Sume API 키는 크레딧을 소모하며 브라우저에서 안전하게 쓸 수 있는 변형이 없으므로, 클라이언트 JavaScript에 넣으면 안 됩니다. 브라우저와 모바일 클라이언트는 백엔드를 호출하고, 백엔드가 키를 붙여야 합니다. 이 프록시 패턴은 브라우저에서 Sume API 호출하기에서 보여 줍니다. 발행할 때 생성하면 페이지 조회가 유료 Job을 시작하는 일도 없습니다.

글에 오디오 플레이어는 어떻게 넣나요?

파일 URL을 넣은 <audio> 요소 하나면 충분합니다. MDN 문서에 따르면 controls는 듣는 사람에게 볼륨, 탐색, 일시정지와 재개 컨트롤을 제공하고, preload="metadata"는 길이 같은 오디오 메타데이터만 가져옵니다. preload의 기본값은 브라우저마다 다르고 명세는 metadata를 권장하며, 브라우저가 이 속성을 반드시 따라야 하는 것도 아닙니다. 이 속성은 힌트입니다.

재생 중에 단어를 하나씩 강조하려면 단어별 타이밍도 함께 요청하세요. 단어 하이라이트 TTS를 참고하세요.

<figure>
  <figcaption>Listen to this article</figcaption>
  <audio controls preload="metadata"
         src="https://example.com/audio/article-812-rev-5.mp3"></audio>
</figure>

긴 글과 수정은 어떻게 처리하나요?

• 요청 하나는 최대 20,000자까지 받으며, 합성된 오디오가 1,200초를 넘으면 tts_duration_exceeded로 실패하고 크레딧은 확정되지 않습니다. 더 긴 글은 문단 경계에서 나누고, 같은 음성을 유지한 채 긴 텍스트 TTS에서처럼 부분을 이어 붙이세요.
• 텍스트가 바뀌면 새 리비전을 새 키로 생성하고 이전 파일을 교체하세요. 그래야 오디오가 항상 페이지와 일치합니다.

글 오디오의 비용은 얼마인가요?

TTS 1.0 요금은 1,000자당 $0.0475이며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. 공백과 문장 부호를 포함해 대본의 모든 글자가 과금 대상입니다. 이 요율이면 10,000자짜리 글은 리비전마다 한 번, 수수료 전 $0.475입니다. 페이지를 조회할 때는 저장된 파일을 재생할 뿐 TTS API를 호출하지 않습니다.