텍스트 음성 변환 (TTS)
텍스트를 자연스러운 음성으로 변환
AI 음성 합성을 사용하여 텍스트를 음성으로 변환합니다. MP3 오디오 파일을 반환합니다.
인증
Authorization 헤더에 API 키를 포함하세요.
요청 본문
| 매개변수 | 필수 | 유형 | 설명 |
|---|---|---|---|
| text | 필수 | string | 변환할 텍스트 (최대 1500자) |
| output_format | 선택 | string | 원하는 오디오 출력 형식입니다. codec_sampleRate_bitrate 형식으로 지정합니다(예: mp3_22050_32). 기본값은 mp3_44100_128입니다. 전체 목록은 아래 출력 형식 섹션을 참조하세요. |
| voice_id | 필수 | 정수 (integer) | 다음의 음성 ID: 음성 목록. |
| prerecording | 선택 | 정수 (integer) | 1(기본 향상), 2(AI 향상 / 아랍어 타슈킬) 또는 3(AI 시인). 2와 3은 아랍어 콘텐츠에만 사용할 수 있습니다. language를 참조하세요. |
| language | 선택 | string | ISO 639-1 코드 형식의 콘텐츠 언어입니다(예: ar 또는 en, ar-JO와 같은 지역 코드도 허용됨). 허용되는 사전 녹음 모드를 결정하며 음성에는 전달되지 않습니다. 모드 2와 3은 아랍어(ar)에만 사용할 수 있습니다. language를 생략하면 2와 3은 아랍어로 간주되므로 기존 연동이 계속 작동합니다. 2 또는 3에 다른 언어를 지정하거나 알 수 없는 코드를 사용하면 details.language에 사유와 함께 400 INVALID_REQUEST를 반환합니다. |
| voice_settings | 선택 | 문자열 (JSON) | 음성 사용자 지정 옵션 |
지원되는 출력 형식
output_format 파라미터는 다음 값 중 하나일 수 있습니다:
- MP3: mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192
- PCM: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000
- Opus: opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192
- WAV: wav_16000, wav_22050, wav_24000, wav_44100, wav_48000 — 엔진 자체 출력의 16비트 모노 WAV(무손실). 스트리밍 WebSocket에서는 사용할 수 없으며, 해당 환경에서는 pcm_*을 사용하세요.
이 섹션은 참고용으로 제공되며, 기본 요청 테이블을 복잡하게 만들지 않고 적절한 형식을 선택할 수 있도록 돕습니다.
엔진 및 모드
모든 음성은 두 가지 엔진 중 하나에 속합니다. 음성 목록에서 이를 voice_engine으로 반환하며, 선택한 음성에 따라 적용되는 설정이 달라집니다.
각 API 키는 하나의 엔진용입니다. 표준(기본값) 또는 고급을 키를 만들 때 선택합니다. 키는 자신의 엔진 음성만 목록에 보여 주고 사용합니다. 다른 엔진을 쓰려면 두 번째 키를 만드세요.
- 표준 엔진 (
standard) — 속도, 표현력, 가격의 균형을 조절하는 세 가지 모드를 갖춘 스튜디오 음성입니다. - 고급 엔진 (
advanced, 알파) — 고유한 음성을 사용하며 context, setting, style, pace를 통해 일상 언어로 연출합니다. 모드는 적용되지 않습니다.
표준 엔진 모드
| mode | 이름 | 크레딧 | 추천 용도 |
|---|---|---|---|
emotion 기본값 |
감정 및 방언 | ×1 | 감정과 방언이 담긴 빠르고 표현력 있는 음성입니다. [laughing], [whispering] 같은 감정 태그를 지원합니다. |
quality |
고품질 감정 및 방언 | ×2 | 더 풍부하고 자연스러운 감정과 방언을 표현합니다. 시간이 조금 더 걸리며 감정 태그를 지원합니다. |
studio |
스튜디오 품질 | ×2 | 전체 음성 제어 기능을 갖춘 깔끔하고 일관된 스튜디오 내레이션. 감정 태그 없음. |
mode가 없는 요청은 emotion 모드로 실행됩니다.
음성 설정 객체
표준 엔진 음성
| 매개변수 | 유형 | 범위 | 기본값 | 설명 |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | 표준 엔진 모드입니다. quality 및 studio는 ×2 크레딧이 소모됩니다. 위의 엔진 및 모드를 참조하세요. |
| temperature | 정수 (integer) | 0 – 100 | 25 | 음성의 변화와 표현력을 제어합니다. 값이 낮을수록 더 안정적이고 예측 가능한 음성이 생성되며, 값이 높을수록 변화, 자연스러움 및 창의적인 표현이 증가합니다. |
| voice_similarity | 정수 (integer) | 0 – 100 | 100 | 생성된 음성이 선택한 음성 프로필과 얼마나 일치하는지 결정합니다. 값이 높을수록 원래 음성의 고유한 특성이 유지되며, 값이 낮을수록 톤과 발음에서 더 많은 변화가 허용됩니다. |
| speed | float | 0.7 – 1.2 | 1.0 | 말하기 속도를 조절합니다. 1.0 미만의 값은 명확한 전달을 위해 속도를 늦추고, 1.0 초과의 값은 말하기 속도를 높입니다. studio 모드 전용이며 emotion 및 quality에서는 무시됩니다. |
| enable_emotions 사용 중단됨 | boolean | false / true | — | 호환성을 위해 계속 허용되지만 더 이상 출력에 영향을 주지 않습니다. 대신 mode를 사용하세요. |
| fast_mode 사용 중단됨 | 정수 (integer) | 0, 1, or 2 | — | 호환성을 위해 계속 허용되지만 더 이상 출력에 영향을 주지 않습니다. emotion 모드가 이미 빠른 옵션입니다. 실시간 오디오의 경우 스트리밍 엔드포인트를 사용하세요. |
emotion 및 quality 모드에서는 temperature와 voice_similarity가 음성 제어 항목이며(범위 내의 모든 값이 그대로 사용됨), speed는 studio 모드에만 적용됩니다.
고급 엔진 음성
| 매개변수 | 유형 | 값 | 설명 |
|---|---|---|---|
| context | string | 최대 500자 | 가장 강력한 제어 항목입니다. 억양, 감정, 분위기 또는 목적을 설명하세요(예: “레반트 방언으로 읽는 따뜻한 다큐멘터리 내레이션”). |
| setting | string | 최대 500자 | 장면 및 분위기(예: “차분하고 친밀한 심야 스튜디오”). |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | 전반적인 전달 스타일. |
| pace | string | slow, normal, fast | 말하기 속도. |
고급 엔진 음성은 mode와 표준 엔진 슬라이더를 무시하고 요청된 output_format을 반환합니다. 생성 시간은 표준 엔진보다 조금 더 걸릴 수 있습니다.
음성 설정 규칙 및 제약 조건
- 알 수 없는 키, 유효하지 않은 mode, style, pace 또는 500자를 초과하는 context/setting은 400 INVALID_REQUEST로 거부됩니다.
-
호환성을 위해, 사용 중단된 enable_emotions가 true일 때는 voice_settings에 다음 필드를 포함하지 않아야 합니다:
speed,fast_mode.
요금
크레딧 = 글자 수 × (사전 녹음 요율 + 음성 수수료 %) × 모드 배수. 배수는 quality 및 studio의 경우 ×2, emotion의 경우 ×1, 모든 고급 엔진 음성의 경우 ×1.5입니다.
예시
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1,
"prerecording": 1,
"language": "ar",
"voice_settings": {
"mode": "emotion",
"speed": 1.0,
"temperature": 25
}
}' \
--output speech.mp3
# Advanced engine voice (voice_engine = "advanced")
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 2,
"voice_settings": {
"context": "A warm documentary read in a Levantine dialect.",
"pace": "slow"
}
}' \
--output speech-advanced.mp3
import requests
response = requests.post(
"https://moknah.io/api/v1/tts/generate/",
headers={
"Authorization": "Bearer your_api_key",
"Content-Type": "application/json"
},
json={
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1,
"prerecording": 1,
"language": "ar",
"voice_settings": {
"mode": "emotion",
"speed": 1.0,
"temperature": 25
}
}
)
with open("speech.mp3", "wb") as f:
f.write(response.content)
const response = await fetch(
'https://moknah.io/api/v1/tts/generate/',
{
method: 'POST',
headers: {
'Authorization': 'Bearer your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: 'مرحبا بك في منصة مكنة',
voice_id: 1,
prerecording: 1,
language: 'ar',
voice_settings: {
mode: 'emotion',
speed: 1.0,
temperature: 25
}
})
}
);
const blob = await response.blob();
// Save or play the audio
응답
다음 헤더와 함께 요청된 output_format(기본값 MP3)으로 바이너리 오디오 데이터를 반환합니다:
| 헤더 | 설명 |
|---|---|
Content-Type |
output_format과 일치함: mp3_*는 audio/mpeg, opus_*는 audio/ogg(Ogg/Opus), pcm_*는 audio/pcm;rate=N;channels=1(16비트 리틀 엔디안 원시 데이터, 헤더 없음). |
오류
| 상태 | 코드 | 설명 |
|---|---|---|
400 |
INVALID_REQUEST | 잘못된 매개변수(알 수 없는 mode, style 또는 pace 포함) |
401 |
UNAUTHORIZED | 유효하지 않은 API 키 |
402 |
INSUFFICIENT_CREDITS | 크레딧 부족 |
429 |
RATE_LIMIT_EXCEEDED | 요청이 너무 많습니다 |
API 관련 질문이나 문제는 다음 주소로 문의해 주세요: api@moknah.io.