Moknah 문서
무료로 시작하기
API 레퍼런스

텍스트 음성 변환 (TTS)

텍스트를 자연스러운 음성으로 변환

POST /api/v1/tts/generate/

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 관련 질문이나 문제는 다음 주소로 문의해 주세요: api@moknah.io.