만들기 전에 먼저 들어보세요
64개 프리셋 보이스 중 5개 — 이 API로 직접 합성한 샘플입니다. 한국어(10보이스)·영어(미국·영국)·스페인어·프랑스어·힌디어·이탈리아어·일본어·포르투갈어·중국어를 지원합니다.
전체 64개 보이스 — 언어별로 골라 들어보세요
전체 목록: GET /v1/voices — 키 없이 조회 가능.
1크레딧 = 1글자. 과금 모델은 이게 전부입니다.
좌석·분·보이스별 요금 없음. 합성 실패 시 크레딧은 자동 환불됩니다. 결제 시 API 키를 발급받은 이메일을 사용하면 크레딧이 자동 충전됩니다.
요청 3번이면 출시 준비 끝
순수 REST, 순수 WAV. HTTP를 보낼 수 있는 언어라면 무엇이든 말할 수 있습니다.
키 발급
curl -X POST https://api.opnvoice.cloud/v1/keys \ -H "content-type: application/json" -d '{"email":"you@company.com"}' → {"api_key":"sk_tts_…","free_credits":5000}
합성
voice 기본값은 af_sarah, speed는 0.5–2.0, 요청당 최대 2,000자.
curl -X POST https://api.opnvoice.cloud/v1/tts \ -H "x-api-key: sk_tts_…" -H "content-type: application/json" \ -d '{"text":"Hello from OpnVoice.","voice":"af_sarah","speed":1.0}' \ -o hello.wav → WAV, 24 kHz mono · x-credits-remaining 헤더로 잔액 확인
상태 코드는 4개뿐
| 상태 | 의미 | 대응 |
|---|---|---|
| 200 | 오디오 반환 | 그대로 사용 |
| 400 | 빈 텍스트, 2,000자 초과, 없는 보이스 | 요청 수정 — 크레딧은 환불됨 |
| 401 | API 키 누락·오류 | x-api-key 헤더 확인 |
| 402 | 크레딧 부족 | 응답 본문의 링크로 충전 |
엔드포인트 전체 명세
이 페이지가 곧 전체 문서입니다 — 엔드포인트 3개, 파라미터 4개가 전부입니다.
엔드포인트
| 엔드포인트 | 인증 | 설명 |
|---|---|---|
| POST /v1/keys | — | API 키 발급. body: {"email"} · 이메일당 1키 (중복 시 409) |
| POST /v1/tts | x-api-key | 텍스트 → WAV 합성. 글자 수만큼 크레딧 차감 |
| GET /v1/voices | — | 사용 가능한 보이스 ID 54개 목록 |
POST /v1/tts — 요청 바디
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| text | string | 필수 | 합성할 텍스트, 1–2,000자. 1글자 = 1크레딧 |
| voice | string | af_sarah | 보이스 ID — 위 탐색기 또는 GET /v1/voices 참조 |
| speed | float | 1.0 | 발화 속도, 0.5–2.0 |
| lang | string | en-us | 텍스트의 언어 코드 (아래 표) — 보이스 언어와 일치시킬 것 |
| format | string | wav | 오디오 포맷 — "wav" 또는 "mp3" |
| timestamps | bool | false | true면 JSON 응답 — 오디오(base64) + 문장별 타이밍 세그먼트. 자막·더빙용 |
언어 코드
| lang | 언어 | 보이스 접두사 |
|---|---|---|
| en-us | 영어 (미국) | af_, am_ |
| en-gb | 영어 (영국) | bf_, bm_ |
| es | 스페인어 | ef_, em_ |
| fr-fr | 프랑스어 | ff_ |
| hi | 힌디어 | hf_, hm_ |
| it | 이탈리아어 | if_, im_ |
| ja | 일본어 | jf_, jm_ |
| pt-br | 포르투갈어 (브라질) | pf_, pm_ |
| cmn | 중국어 (표준) | zf_, zm_ |
| ko | 한국어 — 요청당 최대 1,500자 | kf_, km_ |
응답 헤더
| 헤더 | 설명 |
|---|---|
| content-type | audio/wav — 24kHz · 16-bit · mono |
| x-credits-remaining | 이번 요청 차감 후 남은 크레딧 |
| x-license | 엔진 라이선스 고지 (Apache-2.0) — 컴플라이언스는 저희 몫 |
코드 예시
curl -X POST https://api.opnvoice.cloud/v1/tts \ -H "x-api-key: $OPNVOICE_KEY" -H "content-type: application/json" \ -d '{"text":"Bonjour tout le monde","voice":"ff_siwis","lang":"fr-fr","speed":1.1}' \ -o bonjour.wav
import requests r = requests.post("https://api.opnvoice.cloud/v1/tts", headers={"x-api-key": OPNVOICE_KEY}, json={"text": "Hello from Python", "voice": "am_michael"}) r.raise_for_status() open("hello.wav", "wb").write(r.content) print("credits left:", r.headers["x-credits-remaining"])
const r = await fetch("https://api.opnvoice.cloud/v1/tts", { method: "POST", headers: { "x-api-key": process.env.OPNVOICE_KEY, "content-type": "application/json" }, body: JSON.stringify({ text: "Hello from Node", voice: "af_nova" }), }); if (!r.ok) throw new Error(await r.text()); await require("fs").promises.writeFile("hello.wav", Buffer.from(await r.arrayBuffer())); console.log("credits left:", r.headers.get("x-credits-remaining"));
동일한 요청(text·voice·speed·lang)은 24시간 엣지 캐시에서 응답됩니다. 서버 오류로 합성이 실패하면 크레딧은 자동 환불됩니다.
중요한 질문들
생성된 오디오는 누구 소유인가요?
당신 것입니다 — 지적 재산권과 상업적 권리 100%가 요청자에게 귀속됩니다(약관 제1조). 제품, 광고, 영상, 게임 어디에든 쓰세요. 출처 표기도, 로열티도 영원히 없습니다.
정말 상업적으로 써도 안전한가요?
네. 모델(Kokoro-82M)은 Apache-2.0, 런타임(kokoro-onnx)은 MIT — 모두 상업적 이용을 허용합니다. 라이선스 고지는 모든 응답의 x-license 헤더에 저희가 싣습니다. 컴플라이언스 부담은 API 이쪽 편의 몫입니다.
한국어를 지원하나요?
네 — 여성 5(kf_)·남성 5(km_), 총 10개 한국어 보이스가 있습니다. "voice":"kf_sora","lang":"ko"처럼 쓰면 됩니다 (Supertonic 엔진). 위 보이스 탐색기에서 미리 들어보세요.
보이스 클로닝을 제공하나요?
의도적으로 제공하지 않습니다. 사전 승인된 프리셋 보이스만 노출되며, 스택에 클로닝 코드 자체가 없습니다. 산출물이 법적으로 안전한 큰 이유입니다.
속도 제한은 어떻게 되나요?
크레딧 잔액이 곧 제한입니다 — 1글자에 1크레딧, 요청마다 원자적으로 차감됩니다. 서버 측 합성 실패 시 크레딧은 자동 환불됩니다.
어떤 오디오 포맷을 받나요?
기본은 WAV(24kHz·16비트 모노), 요청에 "format":"mp3"를 주면 MP3(128kbps)로 받습니다. 자막이 필요하면 "timestamps":true로 문장별 타이밍 세그먼트가 포함된 JSON을 받을 수 있습니다.