APICK 한국어 TTS 연동: 견적부터 MP3·ASS 내레이션 받기까지

10월 11, 2026

텍스트 대본을 음성 파형과 MP3 오디오, ASS 자막 파일로 연결한 TTS 개념도 — 이해를 돕기 위한 AI 생성 개념 이미지입니다. 실제 API 응답 화면이 아닙니다.

확인일: 2026-10-11 · 공식 공개 문서 기반 · 아래 코드는 실행하지 않은 연동 예제입니다. 실제 키·고객 데이터는 포함하지 않았습니다.

서비스 이용 가이드를 짧은 한국어 내레이션으로

새 기능을 소개하는 30초 영상에는 짧고 또렷한 대본이 필요합니다. 먼저 화면 순서와 설명 문장을 확정하고, TTS 결과를 들으면서 고유명사와 숫자 발음을 검수하세요. APICK TTS는 작업을 접수한 뒤 상태를 확인하고 파일을 받는 비동기 흐름으로 구성할 수 있습니다.

견적과 접수를 나눠 연결하기

공식 TTS 가이드는 Gemini와 ChatGPT 엔진, 무료 견적 POST /rest/tts/quote, 작업 접수와 결과 다운로드를 안내합니다. 견적에 사용할 engine은 gemini 또는 openai입니다. 정규화는 기본으로 켜져 있으며 별도 스킬 비용이 합산됩니다. 아래 대본은 짧은 합성 예제로 실제 생성하지 않았습니다. TTS 가이드

# 먼저 예상 합성·정규화 비용과 최대 예약금을 확인하는 단계
curl --fail-with-body --request POST https://apick.app/rest/tts/quote \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'engine=gemini' \
  --form-string 'voice_id=Kore' \
  --form-string 'text=새로운 검색 필터를 소개합니다. 원하는 조건을 선택하고 결과를 확인하세요.' \
  --form-string 'normalize_text=true'

# 견적과 실행 예산을 확인한 뒤에만 접수
# 새 작업마다 새 키를 정하고, 같은 입력의 재전송에만 동일 키를 유지합니다.
curl --fail-with-body --request POST https://apick.app/rest/tts/jobs \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --header 'X-Idempotency-Key: narration-demo-20261011-001' \
  --form-string 'voice_id=Kore' \
  --form-string 'text=새로운 검색 필터를 소개합니다. 원하는 조건을 선택하고 결과를 확인하세요.' \
  --form-string 'normalize_text=true'

Node.js: 접수 ID로 완료까지 확인

import { ApickClient } from 'apick-api';
const client = new ApickClient(process.env.APICK_API_KEY);
const input = {
  engine: 'gemini', voice_id: 'Kore', normalize_text: true,
  text: '원하는 조건을 선택하고 결과를 확인하세요.'
};
const quote = await client.quoteTts(input);
console.log(quote.data); // 실행 전 견적 검토 단계
// 아래 블록은 실행 예산 확인 후 별도로 실행합니다.
// 새 작업마다 새 멱등 키를 생성·저장하고, 같은 입력 재전송에만 재사용합니다.
async function createAndCollect() {
  const created = await client.createTtsJob(input.text, {
    voiceId: input.voice_id, normalizeText: true,
    idempotencyKey: 'narration-sdk-demo-20261011-001'
  });
  const id = created.data.job_id;
  let job = created;
  const deadline = Date.now() + 10 * 60 * 1000; // 앱이 정한 대기 한도
  while (['waiting', 'processing'].includes(job.data.status)) {
    if (Date.now() >= deadline) throw new Error(`조회 대기 종료. 작업 ID 보존: ${id}`);
    await new Promise(resolve => setTimeout(resolve, 3000));
    job = await client.getTtsJob(id);
  }
  if (job.data.status !== 'completed') throw new Error(`작업 종료: ${job.data.status}`);
  await (await client.downloadTtsResult(id)).save('./guide.mp3');
  await (await client.downloadTtsSubtitles(id)).save('./guide.ass');
}

위 SDK의 TTS 메서드는 확인한 4.3.1 소스에서 JSON을 전송합니다. cURL의 form-data는 웹 가이드 계약을 따릅니다. SDK가 모든 경로를 같은 형식으로 전송한다고 일반화하지 마세요. 동일 접수 복구에는 같은 멱등 키와 같은 입력이 필요합니다. 앱의 대기 시간이 끝나도 서버 작업이 자동 취소됐다는 뜻은 아닙니다. TTS 구현

요금과 문서 제한을 읽는 방법

합성료는 실제 토큰 원가·적용 환율·1.4배를 바탕으로 계산하며 정규화 비용이 추가됩니다. 고정된 “영상 1분당 가격”으로 환산해 보장하지 마세요. 2026-11-06부터 최소 5P 기본요금이 안내되어 있습니다. 이 글에서는 현재 엔진별 최종 원화 가격을 실제 견적으로 확인하지 않았으므로 실행 전 견적을 기준으로 예산을 잡습니다.

입력 한도에는 공개 문서 차이가 있습니다. 상단 설명과 MCP 카탈로그는 정규화 사용 2,000자·미사용 8,000자를 안내하지만 같은 웹 가이드의 일부 상세 필드에는 800자가 남아 있습니다. 이 글의 짧은 예제로 시작하고 긴 대본은 최신 지원 한도를 확인한 뒤 나누세요.

파일 전달과 FAQ

공식 안내상 MP3와 ASS는 완료 후 24시간 동안 각각 한 번의 완료 다운로드를 허용합니다. 먼저 서버가 파일을 안전하게 저장한 뒤 편집자에게 자체 저장본을 전달하는 편이 운영하기 좋습니다. 브라우저 미리보기가 다운로드 권한을 먼저 소비하지 않는지도 확인하세요. 다운로드·정산 안내

취소하면 무료인가요? 이미 수행한 유료 처리분이 정산될 수 있습니다. 숫자 정규화를 끄면 되나요? normalize_text=false는 스킬 실행과 그 비용을 제외합니다. 대신 원하는 발음을 대본에 직접 써 보고 청취 검수를 해야 합니다.

공식 문서에서 다음 단계 확인하기

구현 전 현재 옵션·요금을 다시 확인하세요. TTS 개발가이드 · TTS SDK 사용법 · SDK TTS 전송 계약 · TTS 도구 설명

#APICK #한국어TTS #내레이션 #음성합성

이 블로그 검색

apick