OpenAI 호환 TTS API로 고품질 음성 생성하기

작성자 NaeumBridge 편집팀 · 업데이트됨 2026-11-19

이 페이지에서는 NaeumBridge의 TTS API를 즉시 활용하는 방법을 안내합니다. Google 로그인이나 이메일로 API 키를 발급받은 후, curl 예제나 OpenAI SDK를 사용해 음성 파일을 생성하는 워크플로우를 단계별로 배울 수 있습니다. 복잡한 설정 없이 RESTful API로 빠르게 통합하세요.

mp3, wav, opus 등 다양한 오디오 형식과 8가지 보이스 프리셋을 활용해 원하는 음성을 생성하세요. 속도 조절, 언어 자동 감지, 에러 처리 및 API 제한 사항까지 실전 개발에 필요한 모든 기술 정보를 제공합니다. 언어 학습이나 오디오 제작을 위한 경량 API를 도입하려는 인디 개발자를 위한 구체적인 가이드입니다.

OpenAI 호환 TTS API로 고품질 음성 생성하기

자주 묻는 질문

API 키는 어떻게 발급하나요?

/get-api-key/ 페이지에서 Google 또는 이메일로 가입하면 API 키를 발급받을 수 있습니다. Google 로그인 시 7일 유효한 $0.50 무료 크레딧이 제공되며, 이메일 가입 시에는 크레딧이 없습니다. 키는 계정당 하나이며, 새 키를 발급하면 이전 키는 즉시 무효화됩니다.

첫 API 요청은 어떻게 하나요?

POST https://api.be888.info/v1/audio/speech 엔드포인트에 JSON 본문을 보내세요. 모델, 텍스트, 음성, 형식, 속도를 지정하고 Authorization 헤더에 Bearer 토큰을 포함합니다. 텍스트는 최대 4096자까지 가능하며, 실패한 요청은 요금이 부과되지 않습니다.

OpenAI SDK를 어떻게 사용하나요?

공식 OpenAI SDK의 base_url을 https://api.be888.info/v1로 변경하고 사이트의 API 키를 사용하면 됩니다. 요청 형식이 동일하므로 기존 코드에서 엔드포인트와 인증 정보만 수정하면 바로 동작합니다. 별도의 자체 SDK나 모바일 SDK는 제공되지 않습니다.

지원되는 오디오 형식은?

mp3, wav, opus, flac, pcm 형식을 지원합니다. response_format 파라미터에 원하는 형식을 지정하여 요청하면 해당 형식의 오디오 파일이 반환됩니다. 특정 하드웨어나 편집 소프트웨어에 맞는 형식을 선택하여 사용할 수 있습니다.

API 에러 코드는 무엇인가요?

API는 별도의 에러 코드 목록을 제공하지 않습니다. 요청 실패 시 응답 본문에 상세한 에러 메시지가 포함되므로, 이를 확인하여 문제를 해결하세요. 인증 실패나 유효성 검사 오류 등 구체적인 사유는 이 메시지를 통해 파악할 수 있습니다.

API 요청 제한은 어떻게 되나요?

키당 분당 60회 요청 제한이 있습니다. 첫 충전 전에는 분당 10회로 제한됩니다. 요청은 순차적으로 처리되므로 부하가 걸리면 대기열에 들어갈 수 있습니다. 제한을 초과하면 요청이 거부되므로 적절한 대기 시간을 설정하세요.

문자 제한은 어떻게 되나요?

요청당 최대 4096자까지 입력할 수 있습니다. 공백과 구두점도 문자 수에 포함됩니다. 긴 텍스트의 경우 4096자 단위로 나누어 여러 요청을 보내고 오디오 파일을 연결해야 합니다. 이는 API의 단일 요청 제한을 위한 것입니다.

속도는 어떻게 조절하나요?

speed 파라미터를 사용하여 0.25에서 4.0 사이의 속도를 설정할 수 있습니다. 기본값은 1.0이며, 더 빠른 속도는 값을 높이고 느린 속도는 값을 낮춰 조정합니다. 음성 생성 속도는 텍스트 길이에 따라 다르지만, 일반적으로 긴 텍스트는 실시간 속도에 가깝습니다.

언어는 어떻게 설정하나요?

language 파라미터에 ISO 코드를 지정하여 언어를 명시적으로 설정할 수 있습니다. 지정하지 않으면 스크립트에 따라 언어가 추론되며, 라틴 문자 텍스트는 기본적으로 영어로 처리됩니다. 비영어권 라틴 문자 텍스트의 경우 language 파라미터를 반드시 설정해야 합니다.

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

/get-api-key/ 페이지에서 현재 키의 상태와 사용량을 확인할 수 있습니다. 새 API 키를 발급하면 기존 키는 즉시 무효화됩니다. 따라서 새 키를 발급하기 전에 기존 키의 사용을 중단해야 합니다. 키는 계정당 하나만 활성화됩니다.

사용량 모니터링은 어떻게 하나요?

/get-api-key/ 페이지에서 잔액, 남은 문자 수, 사용 내역을 확인할 수 있습니다.

API 문서의 업데이트는?

API 문서의 업데이트 일정이나 방법은 별도로 명시되지 않았습니다. 새로운 기능이나 변경사항이 있을 경우 사이트 공지나 문서 업데이트를 통해 안내될 것입니다. 공식 SDK가 아니므로 OpenAI SDK의 변경사항과 무관하게 독립적으로 업데이트됩니다.

지원 언어는 어떻게 확인하나요?

GET /v1/voices 엔드포인트를 호출하면 지원되는 음성, 언어, 형식 및 가격 정보를 확인할 수 있습니다. 현재 23개 언어를 지원하며, 모든 음성이 모든 언어를 구사합니다. 지원하지 않는 언어는 목록에 포함되지 않습니다.

오디오 파일 크기는 어떻게 되나요?

파일 크기는 형식, 속도, 텍스트 길이에 따라 다릅니다. 일반적으로 긴 텍스트는 약 1초당 25자의 생성 속도를 가지며, 파일 크기는 이에 비례합니다. mp3나 opus 같은 압축 형식을 선택하면 파일 크기를 더 작게 만들 수 있습니다.

첫 번째 요청

curl

curl https://api.be888.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.be888.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.be888.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
aria여성
nova여성
luna여성
sage여성
felix남성
milo남성
atlas남성
orion남성
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

API 키 발급

에 대한 소리 파동 일러스트레이션: API 키 발급

API 키를 발급받으려면 먼저 사이트에 로그인해야 합니다. Google 계정으로 간편하게 접속하거나, 이메일과 비밀번호를 사용하여 계정을 생성할 수 있습니다. 각 사이트별로 독립적인 계정이 생성되므로, 별도의 등록 절차가 필요합니다.

Google 로그인

Google 로그인

Google 계정을 통해 간편하게 로그인하면 즉시 무료 체험 크레딧 $0.50(약 50,000자)이 제공됩니다. 이 크레딧은 생성일로부터 7일 동안 유효하며, API 호출 테스트에 적합합니다.

  • Google 계정 연동을 통한 빠른 인증
  • 자동 지급되는 $0.50 무료 체험 크레딧
  • 7일 동안의 제한 없는 테스트 기간

이메일 로그인

이메일 로그인

이메일과 비밀번호로 로그인하는 경우, 별도 체험 크레딧 없이 계정이 생성됩니다. 이는 더 안정적인 인증 방식을 원하는 개발자에게 적합합니다. 로그인 후 /get-api-key/ 페이지에서 키를 확인하세요.

  • 이메일과 비밀번호 기반 계정 생성
  • 체험 크레딧 없이 즉시 사용 가능
  • 고유 API 키 발급

키 생성

로그인 후 대시보드에서 API 키를 발급받습니다. 하나의 계정에 활성 키가 하나만 존재하며, 필요시 새 키를 생성하면 기존 키는 즉시 무효화됩니다. 이 키를 사용하여 API 요청을 인증하세요.

  • 하나의 계정당 하나의 활성 키
  • 새 키 생성 시 기존 키 즉시 정지
  • Authorization: Bearer tts-... 형식 사용

첫 번째 API 요청

에 대한 소리 파동 일러스트레이션: 첫 번째 API 요청

API 키를 발급받았다면 이제 실제 음성 생성을 시작할 수 있습니다. POST 엔드포인트로 텍스트를 보내면 오디오 파일이 반환됩니다. 이 과정은 단순하고 직관적이며, 복잡한 설정 없이 바로 테스트할 수 있습니다.

아래 curl 예시는 한국어 텍스트를 mp3 형식으로 변환하는 가장 기본적인 요청 형태입니다. 이 예시를 복사하여 터미널에서 바로 실행해 보세요. 성공 시 오디오 바이너리가 출력되며, 이는 API의 핵심 기능을 확인하는 첫 단계입니다.

curl 예시

다음 curl 명령어는 'tts-1' 모델을 사용하여 한국어 문장을 음성으로 변환합니다. Authorization 헤더에는 발급받은 API 키를 입력하세요. 입력 텍스트는 4096자를 넘지 않아야 합니다.

$ curl -X POST https://api.be888.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "안녕하세요, NaeumBridge API입니다.", "voice": "nova", "response_format": "mp3" }' \ --output speech.mp3

  • 엔드포인트: https://api.be888.info/v1/audio/speech
  • 메서드: POST
  • 입력 텍스트 최대: 4096자

JSON 형식

요청 본문은 JSON 형식이며, 필수 필드는 model, input, voice입니다. response_format은 mp3, wav, opus, flac, pcm 중 선택할 수 있으며, 기본값은 mp3입니다. speed 필드를 통해 0.25에서 4.0 사이의 속도를 조정할 수 있습니다.

language 필드는 선택 사항이지만, 비영어권 텍스트의 경우 언어 감지 오류를 피하기 위해 명시적으로 ISO 코드를 지정하는 것이 좋습니다. 예를 들어 한국어는 'ko', 영어는 'en'을 사용합니다.

응답 확인

요청이 성공하면 오디오 바이너리가 HTTP 응답 본문으로 반환됩니다. 실패한 경우 에러 코드와 함께 상세 메시지가 반환되며, 이 경우 요금이 부과되지 않습니다. 응답 상태 코드가 200인지 확인하고, 파일이 올바르게 저장되었는지 검증하세요.

반환된 오디오 파일은 즉시 재생 가능합니다. 짧은 문장은 몇 초 내에 생성되며, 긴 텍스트의 경우 처리 시간이 소요될 수 있습니다. 응답 크기를 확인하여 오디오 데이터가 올바르게 수신되었는지 확인하세요.

OpenAI SDK 사용

에 대한 소리 파동 일러스트레이션: OpenAI SDK 사용

OpenAI SDK를 그대로 활용하여 NaeumBridge API와 연동할 수 있습니다. 가장 중요한 설정은 base_url을 https://api.be888.info/v1로 변경하는 것입니다. 이 한 번의 설정만으로 기존 코드에서 별도의 복잡한 수정 없이 음성 생성 기능을 사용할 수 있습니다.

base_url 변경

base_url을 https://api.be888.info/v1로 설정하세요. 이 URL은 OpenAI Speech 엔드포인트와 동일한 요청 구조를 따르므로, 기존 OpenAI SDK의 호환성을 그대로 유지합니다.

  • 기존 코드 수정 최소화
  • 단일 엔드포인트 통합

SDK 설정

Python SDK를 사용할 경우, OpenAI 클래스 초기화 시 base_url과 api_key를 전달합니다. Google 로그인으로 발급된 API 키를 사용하여 인증 정보를 설정하면 바로 호출이 가능합니다.

호환성 확인

요청 형식은 OpenAI의 Speech 엔드포인트와 정확히 일치합니다. model, input, voice 파라미터를 동일하게 전달하면 정상적으로 응답을 받습니다. 추가 설정 없이도 바로 사용 가능합니다.

오디오 형식 선택

에 대한 소리 파동 일러스트레이션: 오디오 형식 선택

API 응답에서 response_format 필드를 설정하여 생성된 오디오의 파일 형식을 지정할 수 있습니다. 지원되는 형식은 mp3, wav, opus, flac, pcm이며, 용도나 저장 환경에 맞게 선택하면 됩니다.

mp3 형식

mp3는 가장 널리 사용되는 압축 오디오 형식입니다. 공간 효율이 뛰어나며 거의 모든 플레이어가 지원하므로, 웹 서비스나 모바일 앱에 오디오 파일을 배포할 때 무난한 선택입니다.

wav 형식

wav은 압축되지 않은 원본 음원 형식입니다. 음질 손실이 없어 편집이나 분석이 필요한 작업에 적합합니다. 파일 크기가 크지만, 높은 품질이 필요한 경우 명확한 선택지입니다.

opus 형식

opus 형식 높은 압축 효율을 제공합니다. 저장에 적합한 선택지입니다.

에러 처리

에 대한 소리 파동 일러스트레이션: 에러 처리

API 요청 중 실패 시, 응답 본문에서 에러 코드를 확인하세요. Synthesis 실패 시에는 요금이 차감되지 않고 전액 환불되므로 안심하고 사용할 수 있습니다. HTTP 상태 코드를 통해 실패 원인을 빠르게 파악하고 로깅하세요.

실패 코드 확인

요청 처리 중 오류가 발생하면 응답 본문에 상세한 에러 메시지가 포함됩니다. 음성 합성 실패 시에는 요금이 전액 환불되므로 데이터 손실 걱정이 없습니다. 응답 코드를 로그에 기록하여 문제 원인을 추적하세요.

  • HTTP 400: 요청 본문 형식 오류
  • HTTP 429: 속도 제한 초과 (1분당 60회)
  • HTTP 500: 서버 내부 오류

재시도 로직

일시적 오류 발생 시, 지수 백오프(exponential backoff) 전략으로 재시도하세요. 초기에는 1초 간격으로 시작하여 간격을 점차 늘리는 것이 좋습니다. 429 상태 코드가 반환되면, 1분당 60회라는 제한을 고려하여 대기 후 재요청하세요.

  • 최대 3회 재시도 권장
  • 초기 대기 시간: 1초
  • 최대 대기 시간: 8초

로그 확인

모든 요청과 응답의 메타데이터는 청구 및 디버깅을 위해 저장됩니다. 실패한 요청의 시간, 문자 수, 상태 코드를 로그에 남겨 문제 해결에 활용하세요. 고객 지원은 이메일로만 제공되므로, 정확한 로그 정보가 중요합니다.

에러 처리

API 제한 사항

에 대한 소리 파동 일러스트레이션: API 제한 사항

API 키당 분당 60개의 요청 한도가 있으며, 특히 초창기에는 분당 10개로 제한됩니다. 이는 서버 부하를 관리하고 안정적인 서비스 제공을 위한 설정으로, 대용량 배치 처리 시 적절한 속도 조절이 필요합니다.

1분당 60 요청

정규 상태에서는 분당 60개의 요청을 보낼 수 있습니다. 이는 동시성 처리에 적합한 수준으로, 대부분의 indie 개발자나 소규모 서비스에 충분합니다.

  • 정규 요청 한도: 분당 60회
  • 과부하 시 큐 처리로 지연될 수 있음

초기 1분당 10 요청

초기 단계에서는 분당 10개로 제한됩니다. 첫 충전 후 제한이 해제되며, 이는 시스템 안정성을 위한 초기 조치입니다.

  • 초기 제한: 분당 10회
  • 충전 후 즉시 해제됨

문자 제한 4096자

한 번의 요청당 최대 4096자까지 입력할 수 있습니다. 이를 초과하는 긴 텍스트는 여러 요청으로 나누어 처리해야 하며, 생성된 오디오를 연결해야 합니다.

이 제한은 API의 효율적인 처리를 위해 설정된 것으로, 일반적인 문서나 스크립트 생성에 적합합니다.

  • 최대 문자 수: 4096자
  • 초과 시 분할 요청 필요

속도 조절

에 대한 소리 파동 일러스트레이션: 속도 조절

API를 통해 생성된 음성의 재생 속도를 미세하게 조정할 수 있습니다. 속도는 0.25부터 4.0까지 16단계로 세밀하게 조절되며, 학습 자료나 오디오북 제작 시 필요에 맞게 최적화할 수 있습니다.

속도 범위 0.25–4.0

속도 파라미터는 0.25(최저속)부터 4.0(최고속)까지 허용됩니다. 기본값은 1.0이며, 이 범위를 벗어나면 API에서 에러를 반환합니다. 이 범위는 모든 모델(tts-1, tts-1-hd)과 음성에서 동일하게 적용됩니다.

속도 설정 방법

POST 요청의 JSON 본문에 speed 필드를 추가하여 설정합니다. 예를 들어, 학습용 오디오의 이해를 돕기 위해 속도를 0.8로 낮추거나, 빠른 정보 전달을 위해 1.5로 높일 수 있습니다.

  • ``json { "model": "tts-1", "input": "학습할 텍스트", "voice": "nova", "speed": 0.8 } ``

효과 확인

속도 변경은 텍스트의 길이(문자 수)에는 영향을 주지 않습니다. 다만, 생성된 오디오 파일의 지속 시간이 비례하여 변합니다. 4096자 제한 내의 긴 텍스트도 속도 조절이 가능하므로, 일관된 오디오 품질을 유지할 수 있습니다.

언어 설정

에 대한 소리 파동 일러스트레이션: 언어 설정

NaeumBridge TTS API는 23개 언어를 지원하며, ISO 언어 코드를 통해 정확한 발화를 제어할 수 있습니다. 이는 언어 학습이나 다국어 오디오 제작 시 필수적인 기능입니다.

ISO 코드 사용

API 요청 시 language 필드에 ISO 639-1 코드를 지정하세요. 예를 들어 한국어는 ko, 스페인어는 es를 사용합니다. 이를 통해 원하지 않는 언어로 발음되는 오류를 방지할 수 있습니다.

  • 지원 언어: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish (총 23개)

자동 감지

language 필드를 생략하면 API는 텍스트의 문자체를 기반으로 언어를 자동 추측합니다. 라틴 문자 텍스트는 기본적으로 영어로 간주되므로, 영어가 아닌 다른 라틴 문자 언어(예: 독일어, 프랑스어)를 사용할 때는 반드시 language를 명시해야 합니다.

언어 지정 방법

모든 8개 음성 아바타는 지정한 언어를 구사할 수 있습니다. tts-1 또는 tts-1-hd 모델과 함께 voice 파라미터와 language 코드를 함께 전달하면 일관된 결과를 얻을 수 있습니다.

  • 언어 미지정 시 라틴 문자 텍스트는 영어로 기본 처리됨
  • 비지원 언어: 베트남어, 인도네시아어, 태국어, 우크라이나어, 루마니아어, 체코어, 벵골어 등

8개 음성 듣기

아래의 각 샘플은 동일한 문장을 이 API로 생성한 것입니다. 복잡한 문장 구조나 새로운 어휘를 학습할 때, 아리아의 선명하고 안정된 발음은 이해도를 높이는 데 큰 도움이 됩니다.

음성 아바타 aria
aria여성
음성 아바타 nova
nova여성
음성 아바타 luna
luna여성
음성 아바타 sage
sage여성
음성 아바타 felix
felix남성
음성 아바타 milo
milo남성
음성 아바타 atlas
atlas남성
음성 아바타 orion
orion남성

23개 언어

모든 음성은 이 언어들을 구사합니다.

출처 및 참고 자료

  1. Wikipedia
  2. TRON developer hub: TRC-20
  3. FFmpeg documentation
  4. Creative Commons Attribution 4.0
  5. IETF RFC 7845: Ogg Opus
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. Tether (USDT)
  8. ISO 639 language codes
  9. Python documentation
  10. openai-node on GitHub
  11. Node.js documentation
  12. LibriVox public-domain audiobooks

이 사이트의 다른 콘텐츠