기사 음성 변환(ATS)
전체 기사를 내레이션 오디오와 자막으로 변환하여 콜백 URL로 비동기 전송합니다.
기사 음성 변환(ATS) 엔드포인트는 기사 텍스트를 받아 MP3 내레이션과 동기화된 자막(.srt) 파일을 생성합니다. 생성은 비동기식으로 진행됩니다. 요청은 즉시 202 Accepted를 반환하며, 완료된 파일은 제공한 callbackURL로 전달됩니다. 이는 ATS WordPress 플러그인을 구동하는 것과 동일한 서비스입니다.
오디오를 받기 위해 HTTP 응답을 기다리지 마세요. 엔드포인트는 즉시 202를 반환하고 생성이 완료되면 callbackURL로 결과를 POST 전송합니다.
인증
Authorization 헤더에 회사 API 키를 Bearer 토큰으로 포함하세요.
Authorization: Bearer your_api_key
요청 본문
원본 기사 텍스트와 요청을 설명하는 postData 객체가 포함된 JSON 본문을 전송하세요.
| 매개변수 | 필수 | 유형 | 설명 |
|---|---|---|---|
| text | 필수 | string | 음성으로 변환할 전체 기사 텍스트입니다. |
| postData | 필수 | object | 요청 메타데이터입니다. 아래 필드를 참조하세요. |
postData 객체
| 필드 | 필수 | 유형 | 기본값 | 설명 |
|---|---|---|---|---|
| name | 필수 | string | — | 기사의 제목입니다. 생성된 오디오 요청의 제목으로 사용됩니다. |
| articleId | 필수 | string | — | 기사의 고유 식별자입니다. 멱등성 키 역할을 하며(아래 멱등성 참조) 콜백에서 그대로 반환됩니다. |
| voiceId | 필수 | string | — | 내레이션에 사용할 음성입니다. 다음의 ID를 사용하세요: 음성 목록. 회사 API 키 유형에 맞는 음성을 사용하세요. 표준 키는 표준 음성(voice_engine = standard), 고급 키는 고급 음성(voice_engine = advanced)을 사용합니다. 유형은 키를 생성할 때 선택합니다. 어느 경우든 .srt 파일의 모든 문장에 단어 단위 타이밍이 들어갑니다. |
| callbackURL | 필수 | string (URL) | — | Moknah가 완료된 오디오 및 자막 URL을 POST로 전송할 HTTPS URL입니다. 최신 값이 회사 계정에 저장됩니다. |
| preprocessType | 선택 | string | "0" | 텍스트 준비 모드: 처리 없음(그대로 읽기)은 "0", 아랍어 타슈킬은 "2"입니다(AI가 모음 기호를 붙이고 숫자를 글자로 풀어 씁니다. 글자 수 비용 2배). 문자열이나 숫자 모두 가능합니다. "2"는 아랍어에서만 사용할 수 있으며, AI에는 아랍어 문장만 전송됩니다. |
| language | 선택 | string | "auto" | 콘텐츠 언어: "auto" 또는 "ar", "en" 같은 ISO 639-1 코드입니다. "auto"이면 텍스트가 아랍어일 때만 preprocessType "2"가 적용되고, 그렇지 않으면 기사가 "0"으로 낭독되며 비용도 1배만 부과됩니다. 아랍어가 아닌 언어와 함께 "2"를 보내면 422 VALIDATION_ERROR로 거부됩니다. |
| regenerate | 선택 | boolean | false | true로 설정하면 이 articleId가 이전에 생성된 적이 있더라도 새로 생성을 강제합니다. |
요청 예시
curl -X POST "https://api.moknah.io/process-text" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
"postData": {
"name": "AI is evolving fast",
"articleId": "post-123",
"voiceId": "12",
"callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
"preprocessType": "0",
"language": "auto",
"regenerate": false
}
}'
import requests
response = requests.post(
"https://api.moknah.io/process-text",
headers={
"Authorization": "Bearer your_api_key",
"Content-Type": "application/json"
},
json={
"text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
"postData": {
"name": "AI is evolving fast",
"articleId": "post-123",
"voiceId": "12",
"callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
"preprocessType": "0",
"language": "auto",
"regenerate": False
}
}
)
# 202 Accepted — the audio is delivered to your callbackURL
print(response.status_code, response.text)
const response = await fetch(
'https://api.moknah.io/process-text',
{
method: 'POST',
headers: {
'Authorization': 'Bearer your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: 'الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.',
postData: {
name: 'AI is evolving fast',
articleId: 'post-123',
voiceId: '12',
callbackURL: 'https://your-site.com/wp-json/ats/v1/callback',
preprocessType: '0',
language: 'auto',
regenerate: false
}
})
}
);
// 202 Accepted — result arrives at your callbackURL
즉시 응답
요청이 수락되면 엔드포인트는 즉시 다음과 같이 응답합니다:
Processing started. Results will be sent to the callback URL.
콜백 페이로드
생성이 완료되면 Moknah는 다음 JSON 본문과 함께 callbackURL로 POST 요청을 보냅니다:
{
"articleId": "post-123",
"response": {
"audioFile": "https://api-storage.moknah.io/.../******.mp3",
"srtFile": "https://api-storage.moknah.io/.../******.srt",
"signature": "<hmac-sha256-hex>"
}
}
| 필드 | 설명 |
|---|---|
| articleId | 요청 시 전송한 것과 동일한 articleId입니다. |
| response.audioFile | 생성된 MP3 내레이션의 공개 URL이며, 생성에 실패한 경우 null입니다. |
| response.srtFile | 동기화된 자막(.srt) 파일의 공개 URL이며, 생성에 실패한 경우 null입니다. |
| response.signature | 페이로드의 진위를 확인하는 데 사용할 수 있는 HMAC-SHA256 서명입니다(아래 참조). |
생성이 오디오를 만들어내지 못한 경우에도 콜백이 전송됩니다. 이 경우 response.audioFile 및 response.srtFile은 null입니다(서명은 여전히 articleId|null|null을 포함함). audioFile 또는 srtFile이 null인 모든 콜백은 실패로 처리하세요. 기사를 완료로 표시하지 말고 regenerate를 true로 설정하여 다시 전송하세요.
서명 확인
서명은 API 키의 SHA-256 16진수 다이제스트를 키로 사용하여 생성한 articleId|audioFile|srtFile 문자열의 HMAC-SHA256(16진수) 값입니다. 자체적으로 다시 계산하여 비교함으로써 콜백이 Moknah에서 전송되었으며 위변조되지 않았는지 확인하세요.
import crypto from 'crypto';
const keyHash = crypto.createHash('sha256').update(API_KEY).digest('hex');
const payload = `${articleId}|${audioFile}|${srtFile}`;
const expected = crypto.createHmac('sha256', keyHash).update(payload).digest('hex');
const isValid = expected === signature;
import hashlib, hmac
key_hash = hashlib.sha256(API_KEY.encode()).hexdigest()
payload = f"{article_id}|{audio_file}|{srt_file}"
expected = hmac.new(key_hash.encode(), payload.encode(), hashlib.sha256).hexdigest()
is_valid = hmac.compare_digest(expected, signature)
멱등성 및 재생성
- 요청은 회사별로 articleId를 기준으로 구분됩니다. 새로운 articleId는 새로운 생성을 시작합니다.
- 기사가 현재 생성 중인 경우 중복 요청은 409 ALREADY_PROCESSING으로 거부됩니다.
- 기사가 이미 생성되었고 regenerate가 false인 경우, 다시 생성하거나 과금하지 않고 기존 오디오가 callbackURL로 재전송됩니다.
- 기존 articleId에 대해 완전히 새로운 생성을 강제하려면 regenerate를 true로 설정하세요.
- 어떤 articleId의 이전 시도가 실패했다면 다시 보내면 새로 생성됩니다. 새 articleId는 필요 없습니다.
동시성 및 처리량
기사는 모든 클라이언트가 공정한 몫을 받는 대기열에서 생성됩니다. 많은 기사를 한 번에 보낼 수 있습니다. 모두 접수되고 몇 개씩 생성되며, 각 기사는 준비되는 대로 콜백 URL로 전달됩니다.
- 따라서 대량의 기사는 한꺼번에가 아니라 차례로 완료됩니다. 보내는 쪽에서 기사를 보류할 필요가 없습니다.
- 실패한 기사는 regenerate를 true로 설정하여 다시 시도하세요. 이미 생성된 기사는 캐시되므로 다시 전송할 필요가 없습니다.
- /process-text 엔드포인트 또한 클라이언트별로 속도 제한(Rate Limit)이 적용됩니다. 제한을 초과하는 갑작스러운 요청은 429 Too Many Requests를 받게 되므로 제출 간격을 두거나 일괄 처리(배치)하세요.
결제 및 청구
글자 비용은 text의 글자 수에 전처리 계수(기본값 1, preprocessType이 2일 때는 2)를 곱하여 계산됩니다. 크레딧은 생성이 실제로 실행될 때만 차감됩니다. 이미 생성된 아티클의 재전송은 무료이며, 생성이나 전송에 실패하면 차감된 크레딧이 자동으로 환불됩니다.
고급 음성(voice_engine = advanced)에는 전처리 배수에 더해 고급 모드 요금이 적용됩니다.
오류
| 상태 | 코드 | 설명 |
|---|---|---|
401 |
AUTH_FAILED | Authorization 헤더가 누락되었거나 유효하지 않은 API 키입니다. |
422 |
VALIDATION_ERROR | 텍스트가 누락되었거나 postData 필드가 유효하지 않거나 누락되었습니다. |
400 |
INVALID_VOICE_ID | 제공된 voiceId가 존재하지 않습니다. |
400 |
UNSUPPORTED_VOICE | 이 음성은 API 키 유형(표준 또는 고급)과 맞지 않거나 지금은 사용할 수 없습니다. |
409 |
ALREADY_PROCESSING | 이 아티클은 이미 생성 중입니다. 완료된 후 다시 시도하세요. |
422 |
PROCESSING_ERROR | 생성에 실패했습니다. 차감된 크레딧은 환불됩니다. |
422 |
REFUND_FAILED | 처리에 실패했으며 자동 환불이 완료되지 않았습니다. api@moknah.io로 문의해 주세요. |
API 관련 질문이나 문제는 다음 주소로 문의해 주세요: api@moknah.io.