개발가이드

  • 개발가이드

한국어 AI 내레이션 TTS

5가지 전문 내레이션 목소리로 한국어 음성을 비동기로 생성합니다.

빠른 시작

작업을 접수한 뒤 상태가 completed가 될 때까지 조회하고, 24kHz mono·48kbps MP3와 부가 파일이 담긴 결과 ZIP을 내려받습니다.

curl -X POST "https://apick.app/rest/tts/jobs" \
  -H "CL_AUTH_KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id":"narrator_m_03","text":"오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다."}'

요금

구분
500자까지
추가 500자마다
선불(v1)
30P
20P
후불(v2)
40P
25P

공백·문장부호·줄바꿈을 포함한 유니코드 문자 수로 계산합니다. 접수 성공 시 한 번 과금되며 이후 취소해도 환불되지 않습니다. 상태 조회, 취소, 결과 다운로드에는 추가 요금이 없습니다.

지원 목소리

같은 안내 문장으로 만든 샘플을 들어보고 콘텐츠 분위기에 맞는 목소리를 선택하세요.

voice_id
성격·추천 용도
샘플
narrator_m_01
절제형
낮고 담담한 톤으로 중요한 단서에 짧게 호흡합니다.
추천: 사건·범죄 다큐
narrator_m_02
기록형
고른 속도와 중립적인 발음으로 사실을 정확하게 전달합니다.
추천: 뉴스·리포트·정보
narrator_m_03
온기형
부드럽고 따뜻한 호흡으로 인물의 이야기를 자연스럽게 이어갑니다.
추천: 휴먼스토리·에세이
narrator_m_04
긴장형
과장 없이 속도와 쉼을 조절해 서사의 긴장감을 살립니다.
추천: 미스터리·추적
narrator_m_05
신뢰형
안정감 있고 신뢰도 높은 톤으로 긴 정보도 차분히 전달합니다.
추천: 역사·시사·교양

엔드포인트

Method
URL
설명
POST
/rest/tts/jobs
작업 접수
GET
/rest/tts/jobs/{job_id}
상태 조회
POST
/rest/tts/jobs/{job_id}/cancel
waiting 작업만 취소
GET
/rest/tts/jobs/{job_id}/result
결과 1회 다운로드

요청

Header
이름
필수
설명
CL_AUTH_KEY
O
APICK 인증키
Content-Type
O
application/json
JSON Body
이름
타입
필수
설명
voice_id
String
O
지원 목소리 ID 중 하나
text
String
O
합성할 한국어 텍스트, 최대 20,000자

응답과 상태

status
의미
waiting
접수되어 처리 시작을 기다리는 중
processing
음성 생성 중
completed
완료, 결과 다운로드 가능
cancelled
취소 완료
failed
생성 실패

처리 설비나 서버 구성 정보는 API 계약에 포함되지 않습니다. 상태 조회는 2~5초 간격을 권장합니다.

전체 호출 예시

# 1. 접수
JOB_ID=$(curl -sS -X POST "https://apick.app/rest/tts/jobs" \
  -H "CL_AUTH_KEY: $API_KEY" -H "Content-Type: application/json" \
  -d '{"voice_id":"narrator_m_03","text":"오늘의 이야기를 시작합니다."}' \
  | jq -r '.data.job_id')

# 2. 상태 조회
curl -sS "https://apick.app/rest/tts/jobs/$JOB_ID" \
  -H "CL_AUTH_KEY: $API_KEY"

# 3. 완료 후 결과 다운로드
curl -sS "https://apick.app/rest/tts/jobs/$JOB_ID/result" \
  -H "CL_AUTH_KEY: $API_KEY" -o "$JOB_ID.zip"

# waiting 상태에서만 취소 가능(과금액은 환불되지 않음)
curl -sS -X POST "https://apick.app/rest/tts/jobs/$JOB_ID/cancel" \
  -H "CL_AUTH_KEY: $API_KEY"

접수 응답 예시

{
  "data": {
    "job_id": "7f7e43f578cd459db04696416435c789",
    "status": "waiting",
    "voice_id": "narrator_m_03",
    "character_count": 27
  },
  "api": { "success": true, "cost": 30, "pl_id": 12345 }
}

결과 ZIP의 음성 파일은 final.mp3(24kHz mono·48kbps)입니다. 완료 후 24시간 안에 한 번만 내려받을 수 있고, 첫 다운로드 전송 직후 서버 원본이 폐기되므로 재다운로드할 수 없습니다. HTTP 429는 현재 요청이 많다는 뜻이며 Retry-After 이후 재시도합니다.

현재 페이지 북마크