API 레퍼런스
시작하기
첫 번째 API 요청을 보내는 데 필요한 모든 것
기본 URL
Moknah는 사용 사례에 따라 두 가지 유형의 엔드포인트를 제공합니다:
표준 REST API (단일 요청용):
https://moknah.io/api/v1/
실시간 WebSocket API (연속 스트리밍용):
wss://moknah.io/api/v1/
인증
Moknah API는 인증을 위해 API 키 를 사용합니다. 모든 HTTP 요청 및 WebSocket 핸드셰이크의 Authorization 헤더에
Bearer 스키마를 사용하여 API 키를 포함하세요.
Authorization: Bearer YOUR_API_KEY
API 키 발급받기
- 로그인: Moknah 대시보드
- Pro 플랜을 구독하거나 기업용 액세스를 위해 영업팀 에 문의하세요.
- 이동: API
- 클릭: API 키 관리
- 클릭: 새 키
- 키를 복사하여 안전하게 보관하세요
키를 안전하게 보관하세요
클라이언트 측 코드나 공개 저장소에 API 키를 절대 노출하지 마세요. 비밀번호처럼 취급하세요.
간단한 HTTP 예제
다음은 표준 REST API를 사용하여 텍스트에서 음성을 생성하는 전체 예제입니다:
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
}' \
--output speech.mp3
import requests
response = requests.post(
"https://moknah.io/api/v1/tts/generate/",
headers={
"Authorization": f"Bearer your_api_key",
},
json={
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1
}
)
if response.status_code == 200:
with open("speech.mp3", "wb") as f:
f.write(response.content)
print("오디오가 저장되었습니다!")
else:
print(f"오류: {response.json()}")
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
})
}
);
if (response.ok) {
const blob = await response.blob();
// 오디오 blob 사용
console.log("오디오가 생성되었습니다!");
} else {
const error = await response.json();
console.error(error);
}
응답 형식
성공 응답
성공 응답은 엔드포인트에 따라 다릅니다:
- TTS 생성 (POST): 요청된 output_format(기본값: audio/mpeg)으로 전체 바이너리 오디오 데이터를 반환합니다
- TTS 스트림 (WSS): 생성되는 대로 바이너리 MP3 청크를 연속으로 스트리밍합니다
- 기타 엔드포인트: 구조화된 JSON 데이터 반환
속도 제한 헤더 (HTTP 전용)
모든 HTTP 응답에는 속도 제한 정보가 포함됩니다 (WebSocket은 연결 종료를 통해 제한을 적용함):
| 헤더 | 설명 |
|---|---|
| RateLimit-Limit | 분당 최대 요청 수 |
| RateLimit-Remaining | 현재 시간 창에 남은 요청 수 |
| RateLimit-Reset | 제한이 초기화되는 Unix 타임스탬프 |
| Moknah-Credits-Remaining | 남은 크레딧 잔액 |
일반적인 오류 코드
| 코드 | 유형 | 설명 |
|---|---|---|
| 400 | INVALID_REQUEST |
잘못된 매개변수 또는 잘못된 형식의 JSON |
| 401 | UNAUTHORIZED |
유효하지 않거나 누락된 API 키 |
| 402 | INSUFFICIENT_CREDITS |
계정에 크레딧이 부족합니다 |
| 429 | RATE_LIMIT_EXCEEDED |
요청이 너무 많음 (HTTP) |
| 4290 | CONCURRENT_LIMIT |
활성 연결이 너무 많음 (WSS) |
| 500 | INTERNAL_SERVER_ERROR |
서버 오류 |
자세히 알아보기
자세한 오류 처리 지침은 오류 페이지를 참조하세요.
다음 단계
설정이 완료되었으니 사용 가능한 엔드포인트를 살펴보세요:
POST
보이스 목록
TTS에 사용 가능한 목소리 가져오기
POST
음성 생성
텍스트를 오디오로 변환
WSS
음성 스트리밍
실시간 WebSocket TTS
POST
음성 받아쓰기
오디오 파일에서 텍스트 추출
WSS
전사 스트리밍
실시간 WebSocket STT
API 지원
API 관련 질문이나 문제는 다음 주소로 문의해 주세요: api@moknah.io.