실시간 텍스트 음성 변환(TTS)
텍스트를 점진적으로 스트리밍하고 원시 PCM 또는 MP3 오디오 바이트를 즉시 수신합니다
실시간 텍스트 음성 변환 스트리밍을 위해 양방향 WebSocket 연결을 설정합니다. 텍스트 청크를 점진적으로 전송하고(LLM 출력에 이상적) 바이너리 오디오 스트림을 연속적으로 수신하세요. 크레딧은 HTTP 엔드포인트와 동일하게 계산됩니다.
초저지연(~200ms TTFB)을 달성하려면 텍스트 청크가 마침표(.), 느낌표(!) 또는 물음표(?)와 같은 명확한 구두점으로 끝나도록 하세요. AI는 자연스러운 억양을 보장하기 위해 문장 경계를 감지할 때까지 텍스트를 버퍼링합니다.
인증
WebSocket 핸드셰이크 중에 Authorization 헤더를 사용하여 인증합니다:
Authorization: Bearer YOUR_API_KEY
연결 설정
연결 후 원하는 구성으로 초기화 메시지를 전송합니다:
{
"type": "init",
"voice_id": 1710,
"prerecording": 1,
"language": "ar",
"output_format": "pcm_24000",
"voice_settings": {
"temperature": 25,
"similarity": 100,
"expressiveness": 0,
"speed": 1.0,
"fast_mode": 2
}
}
초기화 매개변수
| 매개변수 | 필수 | 유형 | 설명 |
|---|---|---|---|
| type | 필수 | string | 초기화 메시지에는 반드시 "init"이어야 합니다. |
| voice_id | 필수 | 정수 (integer) | 다음의 음성 ID: 음성 목록. |
| output_format | 선택 | string | 원하는 오디오 형식입니다. 기본값은 pcm_24000입니다. 옵션은 다음과 같습니다:
|
| 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을 다른 언어와 함께 사용하거나 알 수 없는 코드를 입력하면 오류 메시지가 반환되고 스트림이 초기화되지 않습니다. |
| voice_settings | 선택 | object | 음성 맞춤설정 옵션입니다. 아래의 음성 설정 섹션을 참조하세요. |
음성 설정 객체
스트리밍은 두 엔진 모두에서 자체 글자당 요금으로 작동하며 모드에 따라 배율이 적용됩니다. emotion(기본값) 및 fast_mode ×1, quality 및 studio ×2. 고급 엔진 음성은 ×1.5의 비용이 듭니다.
- 표준 엔진 음성은 모든 모드에서 스트리밍됩니다: emotion(기본값, 최저 지연 시간), quality, studio. fast_mode는 저지연 모델로 전환합니다.
- 고급 엔진 음성은 문장 단위로 스트리밍됩니다. 각 문장이 완성되는 즉시 해당 문장의 오디오가 시작됩니다. pcm_* 또는 mp3_* 출력 형식을 사용하세요(이 음성에는 Opus를 사용할 수 없습니다).
표준 엔진 음성
| 매개변수 | 유형 | 범위 | 기본값 | 설명 |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | 선택 사항. emotion(감정 및 방언, ×1), quality(고품질 감정 및 방언, ×2) 또는 studio(스튜디오 품질, ×2). emotion 및 quality에서는 temperature 및 similarity만 적용됩니다. |
| temperature | 정수 (integer) | 0 – 100 | 25 | 낮음 = 안정적이고 예측 가능함, 높음 = 창의적이고 다양함. |
| similarity | 정수 (integer) | 0 – 100 | 100 | 음성이 원본 보이스 클론과 얼마나 유사한지 나타냅니다. |
| speed | float | 0.5 – 2.0 | 1.0 | 재생 속도 배율입니다. |
| fast_mode | 정수 (integer) | 0, 1, or 2 | 0 | 1 또는 2는 저지연 모델(×1 크레딧)로 전환하며 mode를 재정의합니다. 0 = 끔. |
고급 엔진 음성
| 매개변수 | 유형 | 값 | 설명 |
|---|---|---|---|
| context | string | 최대 500자 | 가장 강력한 제어 수단입니다. 억양, 감정, 분위기 또는 목적을 설명하세요. |
| setting | string | 최대 500자 | 장면 및 분위기. |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | 전반적인 전달 스타일. |
| pace | string | slow, normal, fast | 말하기 속도. |
팁: 첫 오디오를 가장 빠르게 받으려면 온전한 문장(. ! ? 또는 줄바꿈으로 끝남) 단위로 전송하세요.
스트리밍 파이프라인
1. 텍스트 청크 전송
LLM이 생성하는 대로 텍스트를 점진적으로 전송합니다:
{"type": "text", "data": "مرحبا بكم."}
서버가 즉시 청크를 처리하고 해당 길이만큼 크레딧을 차감한 뒤 오디오 스트리밍을 시작합니다.
2. 완료 신호 보내기 (중지)
텍스트 생성이 완전히 끝나면 중지 신호를 전송합니다:
{"type": "stop"}
서버는 버퍼에 남은 텍스트 합성을 마치고 마지막 오디오 바이트를 모두 전달한 후 스트림 종료 신호를 보냅니다.
메시지 수신
서버는 WebSocket을 통해 두 가지 유형의 프레임을 푸시합니다:
1. 바이너리 오디오 청크 (PCM / MP3)
생성되는 즉시 스트리밍되는 원시 오디오 바이트입니다. 포맷은 요청한 output_format에 따라 달라집니다(기본값: 24kHz의 16비트 PCM). MP3를 요청한 경우 이 바이트를 파일에 바로 기록할 수 있습니다.
2. JSON 제어 메시지
초기화 완료:
{"status": "ready", "message": "초기화되었으며 텍스트를 수신할 준비가 되었습니다."}
스트림 종료 (안전한 연결 종료 신호):
{"type": "end_of_stream"}
이 메시지를 수신하면 오디오 청크가 100% 전달되었음이 수학적으로 보장됩니다. 이제 클라이언트 측에서 WebSocket 연결을 안전하게 닫을 수 있습니다.
스트리밍 중 오류:
{"error": "스트리밍 중 크레딧 부족"}
프로덕션용 예제
# pip install websockets
import asyncio
import websockets
import json
API_KEY = "YOUR_API_KEY"
url = "wss://api.moknah.io/api/v1/tts/ws/"
async def stream_tts():
headers = {"Authorization": f"Bearer {API_KEY}"}
async with websockets.connect(url, additional_headers=headers) as ws:
# 1. Initialize session (Requesting MP3 so we can save to file)
await ws.send(json.dumps({
"type": "init",
"voice_id": 1710,
"output_format": "mp3_44100_128",
"voice_settings": {"fast_mode": 2}
}))
print(f"Server: {await ws.recv()}")
# 2. Receiver Task
async def receive_audio():
with open("audio.mp3", "wb") as f:
async for msg in ws:
if isinstance(msg, bytes):
f.write(msg)
else:
data = json.loads(msg)
if data.get("type") == "end_of_stream":
print("✅ Stream finished safely.")
await ws.close()
break
receiver = asyncio.create_task(receive_audio())
# 3. Send Text
for chunk in ["مرحبا بكم.", "في منصة مُكنة."]:
await ws.send(json.dumps({"type": "text", "data": chunk}))
await asyncio.sleep(0.5)
# 4. Signal Stop
await ws.send(json.dumps({"type": "stop"}))
await receiver
asyncio.run(stream_tts())
// npm install ws
const WebSocket = require('ws');
const fs = require('fs');
const API_KEY = "YOUR_API_KEY";
const ws = new WebSocket('wss://api.moknah.io/api/v1/tts/ws/', {
headers: { "Authorization": `Bearer ${API_KEY}` }
});
const audioStream = fs.createWriteStream('audio.mp3');
ws.on('open', function open() {
// Requesting MP3 to safely write to an MP3 file
ws.send(JSON.stringify({
type: "init",
voice_id: 1710,
output_format: "mp3_44100_128",
voice_settings: { fast_mode: 2 }
}));
});
ws.on('message', function incoming(data, isBinary) {
if (isBinary) {
audioStream.write(data); // Save MP3 chunks
} else {
const msg = JSON.parse(data.toString());
if (msg.status === 'ready') {
console.log("Ready! Sending text...");
ws.send(JSON.stringify({ type: "text", data: "مرحبا بكم." }));
setTimeout(() => ws.send(JSON.stringify({ type: "text", data: "في منصة مُكة." })), 500);
setTimeout(() => ws.send(JSON.stringify({ type: "stop" })), 1000);
} else if (msg.type === 'end_of_stream') {
console.log("✅ All audio received. Closing connection.");
ws.close();
}
}
});
<?php
// composer require textalk/websocket
require 'vendor/autoload.php';
use WebSocket\Client;
$apiKey = "YOUR_API_KEY";
$client = new Client("wss://api.moknah.io/api/v1/tts/ws/", [
'headers' => ['Authorization' => "Bearer $apiKey"],
'timeout' => 60
]);
// 1. Initialize (Requesting MP3 format)
$client->text(json_encode([
"type" => "init",
"voice_id" => 1710,
"output_format" => "mp3_44100_128",
"voice_settings" => ["fast_mode" => 2]
]));
echo "Server: " . $client->receive() . "\n";
// 2. Send Text Chunks
$client->text(json_encode(["type" => "text", "data" => "مرحبا بكم."]));
$client->text(json_encode(["type" => "text", "data" => "في منصة مُكنة."]));
$client->text(json_encode(["type" => "stop"]));
// 3. Receive Audio & Control Messages
$audioFile = fopen("audio.mp3", "wb");
while (true) {
$message = $client->receive();
$decoded = json_decode($message, true);
if ($decoded && isset($decoded['type']) && $decoded['type'] == 'end_of_stream') {
echo "✅ Stream finished successfully.\n";
break;
} elseif (!$decoded) {
// If it can't be decoded as JSON, it's our binary MP3 audio chunk
fwrite($audioFile, $message);
}
}
fclose($audioFile);
$client->close();
?>
# Standard cURL does not support bidirectional WebSockets easily.
# Use 'websocat' to test WebSockets from the command line:
websocat wss://api.moknah.io/api/v1/tts/ws/ \
-H "Authorization: Bearer YOUR_API_KEY"
# Once connected, paste the JSON payloads interactively:
{"type": "init", "voice_id": 1710, "output_format": "mp3_44100_128"}
{"type": "text", "data": "مرحبا بكم."}
{"type": "stop"}
종료 코드 및 오류
WebSocket 연결은 다음 표준 코드 중 하나로 닫힐 수 있습니다:
| 코드 | 유형 | 설명 |
|---|---|---|
1000 |
SUCCESS | 스트림이 정상적으로 완료되었습니다. |
3011 |
GENERATION_ERROR | 업스트림 API에서 오디오 생성에 실패했습니다. 요청을 다시 시도하세요. |
4001 |
MISSING_API_KEY | Authorization 헤더에 API 키가 제공되지 않았습니다. |
4002 |
AUTH_FAILED | 잘못된 키, 비활성 계정, 초기 크레딧 부족 또는 IP 제한. |
4290 |
CONCURRENT_LIMIT | 사용자에게 이미 활성화된 TTS WebSocket 연결이 있습니다. 한도는 사용자당 1개입니다. |
API 관련 질문이나 문제는 다음 주소로 문의해 주세요: api@moknah.io.