apick-api 1.1.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2.1.0 - 2026-09-01
+
+- `downloadTtsSubtitles(jobId)`로 발화 타이밍 ASS 자막을 별도 1회 다운로드할 수 있습니다.
+- TTS 상태 타입에 `subtitles_available`을 추가했습니다.
+- 허용 IP 공란, 단일 IPv4·CIDR 등록, 즉시 반영 규칙을 한영 문서에 추가했습니다.
+
+## 2.0.1 - 2026-08-31
+
+- TTS 작업 취소 범위를 `waiting`과 `processing` 상태로 확장했습니다.
+- 실행 중 취소도 접수 시 과금된 금액을 환불하지 않는 계약을 한영 문서에 반영했습니다.
+- 17개 TTS `voice_id`의 사용자 표시 이름을 공개 문서에 추가했습니다.
+
+## 2.0.0 - 2026-08-30
+
+- 종료된 동기 `textToSpeech()` 계약을 제거했습니다.
+- `createTtsJob()`, `getTtsJob()`, `cancelTtsJob()`, `downloadTtsResult()`로 비동기 한국어 TTS Jobs 계약을 제공합니다.
+- 지원 목소리, 최대 800자, 상태 조회, 대기 중 취소, 결과 MP3(`audio/mpeg`) 1회 다운로드를 문서화했습니다.
+- 정식 게시 전 지원 목소리를 17개 중립 내레이션 음성으로 확장하고 `TTS_VOICE_IDS`를 추가했습니다.
+
 ## 1.1.1 - 2026-08-30
 
 - 공개된 25개 API 계약에 종료 대상 이미지 생성 기능이 포함되지 않았음을 재검증했습니다.

package/README.md

@@ -2,9 +2,9 @@
 
 # APICK API for Node.js
 
-**에이픽 주요 API 20개를 API 키 하나로 간편하게 호출하는 공식 Node.js SDK**
+**에이픽 주요 API 25개를 API 키 하나로 간편하게 호출하는 공식 Node.js SDK**
 
-**Official zero-dependency Node.js SDK for 20 popular APICK Korean data and AI APIs**
+**Official zero-dependency Node.js SDK for 25 popular APICK Korean data and AI APIs**
 
 [![npm](https://img.shields.io/npm/v/apick-api?color=%230a7cff&label=npm%20apick-api)](https://www.npmjs.com/package/apick-api)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933)](https://nodejs.org/)
@@ -45,6 +45,9 @@ console.log(result.data);
 인증키는 [apick.app](https://apick.app) 가입 후 마이페이지에서 발급할 수 있습니다.
 Get an API key from your account page after signing up at [apick.app](https://apick.app).
 
+마이페이지의 허용 IP가 공란이면 제한 없이 호출할 수 있습니다. 제한하려면 APICK에 도착하는 공인 IPv4를 단일 주소 또는 CIDR(`/32` 등)로 등록하세요. 저장 즉시 반영되며 별도 동기화는 필요하지 않습니다.
+Leave the allowed-IP list blank for unrestricted access. To restrict access, register the public IPv4 address seen by APICK as an exact address or CIDR such as `/32`. Changes apply immediately with no separate synchronization.
+
 ## 제공 서비스 / Included services
 
 | Method | APICK service | Result |
@@ -64,7 +67,11 @@ Get an API key from your account page after signing up at [apick.app](https://ap
 | `googleSearch(keyword, options)` | 웹 검색 / Web search | JSON |
 | `googleImageSearch(keyword, options)` | 이미지 검색 / Image search | JSON |
 | `screenshot(url)` | 웹페이지 화면캡처 / Web screenshot | Binary |
-| `textToSpeech(text, options)` | 음성 합성 / Text to speech | Binary |
+| `createTtsJob(text, options)` | 한국어 내레이션 작업 접수 / Create TTS job | JSON |
+| `getTtsJob(jobId)` | TTS 작업 상태 / TTS job status | JSON |
+| `cancelTtsJob(jobId)` | 대기·생성 중 TTS 작업 취소 / Cancel waiting or processing TTS job | JSON |
+| `downloadTtsResult(jobId)` | TTS 결과 1회 다운로드 / One-time TTS result | MP3 |
+| `downloadTtsSubtitles(jobId)` | TTS 자막 1회 다운로드 / One-time TTS subtitles | ASS |
 | `htmlToPdf(html, options)` | HTML→PDF | Binary |
 | `jsonToExcel(data, options)` | JSON→Excel | Binary |
 | `summarize(text)` | 텍스트 요약 / Text summarization | JSON |
@@ -127,6 +134,40 @@ await excel.save('./scores.xlsx');
 
 `ApickBinaryResult` provides `bytes`, `size`, `filename`, `contentType`, `meta`, `toArrayBuffer()`, `toBlob()`, and `save(path)`.
 
+## 비동기 TTS Jobs / Asynchronous TTS Jobs
+
+기존 동기 TTS는 종료되었습니다. 한국어 내레이션은 작업을 접수하고 `completed`가 될 때까지 2~5초 간격으로 상태를 확인한 뒤 MP3 결과를 한 번만 내려받습니다.
+
+The legacy synchronous TTS API has retired. Create a Korean narration job, poll every 2–5 seconds until it is `completed`, then download the MP3 result once.
+
+17 neutral narration voices are supported: the five original `narrator_m_01`–`narrator_m_05` voices plus `narrator_f_10s_01`–`03`, `narrator_m_20s_01`, `narrator_f_20s_01`–`04`, `narrator_m_30s_01`–`02`, `narrator_m_40s_01`, and `narrator_m_80s_01`. Import `TTS_VOICE_IDS` for the exact list.
+
+표시 이름 / voice labels: `narrator_m_01` 태준, `narrator_m_02` 민석, `narrator_m_03` 도현, `narrator_m_04` 강우, `narrator_m_05` 성훈, `narrator_f_10s_01` 서아, `narrator_f_10s_02` 하린, `narrator_f_10s_03` 예린, `narrator_m_20s_01` 도윤, `narrator_f_20s_01` 지안, `narrator_f_20s_02` 서윤, `narrator_f_20s_03` 소연, `narrator_f_20s_04` 유나, `narrator_m_30s_01` 현우, `narrator_m_30s_02` 준혁, `narrator_m_40s_01` 정우, `narrator_m_80s_01` 영수.
+
+```js
+const created = await apick.createTtsJob('오늘의 이야기를 시작합니다.', {
+  voiceId: 'narrator_m_03'
+});
+const jobId = created.data.job_id;
+
+let job;
+do {
+  await new Promise(resolve => setTimeout(resolve, 3000));
+  job = await apick.getTtsJob(jobId);
+} while (job.data.status === 'waiting' || job.data.status === 'processing');
+
+if (job.data.status === 'completed') {
+  const result = await apick.downloadTtsResult(jobId);
+  await result.save(`./${jobId}.mp3`);
+  const subtitles = await apick.downloadTtsSubtitles(jobId);
+  await subtitles.save(`./${jobId}.ass`);
+}
+```
+
+접수 성공 시 과금되며 취소해도 환불되지 않습니다. 취소는 `waiting` 또는 `processing` 상태에서 가능하고, MP3와 ASS 자막은 각각 한 번만 내려받을 수 있습니다. 각 다운로드가 시작되면 해당 서버 원본이 즉시 폐기되므로 전송 중단 시에도 다시 받을 수 없습니다.
+
+The charge is final when the job is accepted. Cancellation is allowed while `waiting` or `processing`. The MP3 and ASS subtitles can each be downloaded once. Starting either download immediately consumes that server copy, so an interrupted transfer cannot be downloaded again.
+
 ## 신분증 마스킹 / Identity masking
 
 ```js

package/docs/guide.en.md

@@ -19,6 +19,8 @@ const client = new ApickClient({
 
 Pass the API key only to the constructor. The SDK does not keep it in enumerable client properties and never prints it in logs or error messages.
 
+Leave the allowed-IP list blank for unrestricted access. To restrict access, register the public IPv4 address seen by APICK as an exact address or CIDR such as `/32`. Changes apply immediately with no separate synchronization.
+
 ## Business, validation, and addresses
 
 ```js
@@ -76,12 +78,30 @@ await client.ocr(bytes, {
 
 ## Generated files
 
+TTS supports 17 neutral narration `voice_id` values: five original narrators and twelve new voices. Import `TTS_VOICE_IDS` for the exact list.
+
+Voice labels: `narrator_m_01` 태준, `narrator_m_02` 민석, `narrator_m_03` 도현, `narrator_m_04` 강우, `narrator_m_05` 성훈, `narrator_f_10s_01` 서아, `narrator_f_10s_02` 하린, `narrator_f_10s_03` 예린, `narrator_m_20s_01` 도윤, `narrator_f_20s_01` 지안, `narrator_f_20s_02` 서윤, `narrator_f_20s_03` 소연, `narrator_f_20s_04` 유나, `narrator_m_30s_01` 현우, `narrator_m_30s_02` 준혁, `narrator_m_40s_01` 정우, `narrator_m_80s_01` 영수.
+
 ```js
 const screenshot = await client.screenshot('https://example.com');
 await screenshot.save('./example.jpeg');
 
-const speech = await client.textToSpeech('Hello.', { language: 'en' });
-await speech.save('./hello.mp3');
+const created = await client.createTtsJob('오늘의 이야기를 시작합니다.', { voiceId: 'narrator_m_03' });
+const jobId = created.data.job_id;
+let job = await client.getTtsJob(jobId);
+while (job.data.status === 'waiting' || job.data.status === 'processing') {
+  await new Promise(resolve => setTimeout(resolve, 3000));
+  job = await client.getTtsJob(jobId);
+}
+if (job.data.status === 'completed') {
+  const result = await client.downloadTtsResult(jobId);
+  await result.save(`./${jobId}.mp3`); // audio/mpeg; downloadable once
+  const subtitles = await client.downloadTtsSubtitles(jobId);
+  await subtitles.save(`./${jobId}.ass`); // ASS subtitles; separately downloadable once
+}
+
+// Cancellation is available while waiting or processing and does not refund the accepted charge.
+// MP3 and ASS downloads each consume their server copy immediately and cannot be repeated.
 
 const pdf = await client.htmlToPdf('<h1>Report</h1>', { pagination: true });
 await pdf.save('./report.pdf');

package/docs/guide.ko.md

@@ -19,6 +19,8 @@ const client = new ApickClient({
 
 인증키는 생성자에만 전달하세요. 클라이언트 객체의 열거 가능한 속성에 저장되지 않으며 SDK가 로그로 출력하지 않습니다.
 
+마이페이지의 허용 IP가 공란이면 제한 없이 호출할 수 있습니다. 제한하려면 APICK에 도착하는 공인 IPv4를 단일 주소 또는 CIDR(`/32` 등)로 등록하세요. 저장 즉시 반영되며 별도 동기화는 필요하지 않습니다.
+
 ## 조회와 검증
 
 ```js
@@ -76,12 +78,30 @@ await client.ocr(bytes, {
 
 ## 파일 생성
 
+TTS는 기존 남성 내레이터 5개와 신규 중립 내레이션 12개를 합쳐 17개 `voice_id`를 지원합니다. 정확한 목록은 `TTS_VOICE_IDS` 상수로 확인할 수 있습니다.
+
+표시 이름: `narrator_m_01` 태준, `narrator_m_02` 민석, `narrator_m_03` 도현, `narrator_m_04` 강우, `narrator_m_05` 성훈, `narrator_f_10s_01` 서아, `narrator_f_10s_02` 하린, `narrator_f_10s_03` 예린, `narrator_m_20s_01` 도윤, `narrator_f_20s_01` 지안, `narrator_f_20s_02` 서윤, `narrator_f_20s_03` 소연, `narrator_f_20s_04` 유나, `narrator_m_30s_01` 현우, `narrator_m_30s_02` 준혁, `narrator_m_40s_01` 정우, `narrator_m_80s_01` 영수.
+
 ```js
 const screenshot = await client.screenshot('https://example.com');
 await screenshot.save('./example.jpeg');
 
-const speech = await client.textToSpeech('안녕하세요.', { language: 'ko' });
-await speech.save('./hello.mp3');
+const created = await client.createTtsJob('오늘의 이야기를 시작합니다.', { voiceId: 'narrator_m_03' });
+const jobId = created.data.job_id;
+let job = await client.getTtsJob(jobId);
+while (job.data.status === 'waiting' || job.data.status === 'processing') {
+  await new Promise(resolve => setTimeout(resolve, 3000));
+  job = await client.getTtsJob(jobId);
+}
+if (job.data.status === 'completed') {
+  const result = await client.downloadTtsResult(jobId);
+  await result.save(`./${jobId}.mp3`); // audio/mpeg, 1회만 다운로드 가능
+  const subtitles = await client.downloadTtsSubtitles(jobId);
+  await subtitles.save(`./${jobId}.ass`); // ASS 자막, 별도 1회 다운로드
+}
+
+// 취소는 waiting 또는 processing 상태에서 가능하며 이미 과금된 금액은 환불되지 않습니다.
+// MP3와 ASS는 각각 다운로드 시작 시 해당 서버 원본이 즉시 폐기되어 재다운로드할 수 없습니다.
 
 const pdf = await client.htmlToPdf('<h1>보고서</h1>', { pagination: true });
 await pdf.save('./report.pdf');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "1.1.1",
+  "version": "2.1.0",
   "description": "Official zero-dependency Node.js client for 25 APICK APIs. 에이픽 주요 API 25개를 간편하게 호출하는 공식 Node.js SDK.",
   "type": "module",
   "main": "./src/index.cjs",
@@ -64,7 +64,7 @@
     "google-search",
     "pdf",
     "excel",
-    "tts",
+    "tts-jobs",
     "text-summary"
   ]
 }

package/src/index.cjs

@@ -3,6 +3,14 @@
 const DEFAULT_BASE_URL = 'https://apick.app';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_OCR_BYTES = 50 * 1024 * 1024;
+const TTS_VOICE_IDS = Object.freeze([
+	'narrator_m_01', 'narrator_m_02', 'narrator_m_03', 'narrator_m_04', 'narrator_m_05',
+	'narrator_f_10s_01', 'narrator_f_10s_02', 'narrator_f_10s_03',
+	'narrator_m_20s_01', 'narrator_f_20s_01', 'narrator_f_20s_02',
+	'narrator_f_20s_03', 'narrator_f_20s_04', 'narrator_m_30s_01',
+	'narrator_m_30s_02', 'narrator_m_40s_01', 'narrator_m_80s_01'
+]);
+const TTS_VOICE_ID_SET = new Set(TTS_VOICE_IDS);
 
 const SERVICE_DEFINITIONS = Object.freeze({
 	businessDetails: { endpoint: '/rest/biz_detail', timeoutMs: 50_000, output: 'json' },
@@ -25,7 +33,7 @@ const SERVICE_DEFINITIONS = Object.freeze({
 	googleSearch: { endpoint: '/rest/google_search', timeoutMs: 35_000, output: 'json' },
 	googleImageSearch: { endpoint: '/rest/google_image_search', timeoutMs: 35_000, output: 'json' },
 	screenshot: { endpoint: '/rest/url_screenshot', timeoutMs: 75_000, output: 'binary', filename: 'screenshot.jpeg' },
-	textToSpeech: { endpoint: '/rest/tts', timeoutMs: 35_000, output: 'binary', filename: 'speech.mp3' },
+	createTtsJob: { endpoint: '/rest/tts/jobs', timeoutMs: 35_000, output: 'json' },
 	htmlToPdf: { endpoint: '/rest/html_to_pdf', timeoutMs: 25_000, output: 'binary', filename: 'document.pdf' },
 	jsonToExcel: { endpoint: '/rest/json_to_excel', timeoutMs: 45_000, output: 'binary', filename: 'data.xlsx' },
 	summarize: { endpoint: '/rest/llm/text_summary', timeoutMs: 75_000, output: 'json' },
@@ -87,6 +95,18 @@ function normalizeUrl(value) {
 	return parsed.toString();
 }
 
+function normalizeTtsJobId(value) {
+	const jobId = requiredString('jobId', value);
+	if (!/^[a-f0-9]{32}$/.test(jobId)) throw new TypeError('jobId must be a 32-character lowercase hexadecimal string.');
+	return jobId;
+}
+
+function normalizeTtsVoice(value) {
+	const voiceId = requiredString('voiceId', value);
+	if (!TTS_VOICE_ID_SET.has(voiceId)) throw new RangeError('voiceId must be one of the supported TTS voice IDs.');
+	return voiceId;
+}
+
 function numberOrNull(value) {
 	if (value === undefined || value === null || value === '') return null;
 	const number = Number(value);
@@ -252,9 +272,10 @@ class ApickClient {
 			: positiveInteger('timeoutMs', options.timeoutMs);
 	}
 
-	async _call(serviceName, payload, formData) {
-		const definition = SERVICE_DEFINITIONS[serviceName];
-		if (!definition) throw new TypeError(`Unknown APICK service: ${serviceName}`);
+	async _call(serviceName, payload, formData, requestOptions) {
+		const baseDefinition = SERVICE_DEFINITIONS[serviceName];
+		if (!baseDefinition) throw new TypeError(`Unknown APICK service: ${serviceName}`);
+		const definition = Object.assign({}, baseDefinition, requestOptions || {});
 
 		const controller = new AbortController();
 		const timeoutMs = this.#timeoutMs || definition.timeoutMs || DEFAULT_TIMEOUT_MS;
@@ -263,14 +284,17 @@ class ApickClient {
 			Accept: definition.output === 'binary' ? '*/*' : 'application/json',
 			CL_AUTH_KEY: this.#apiKey
 		};
+		const method = definition.method || 'POST';
 		const request = {
-			method: 'POST',
+			method,
 			headers,
-			body: formData || JSON.stringify(payload || {}),
 			signal: controller.signal,
 			redirect: 'error'
 		};
-		if (!formData) headers['Content-Type'] = 'application/json';
+		if (method !== 'GET') {
+			request.body = formData || JSON.stringify(payload || {});
+			if (!formData) headers['Content-Type'] = 'application/json';
+		}
 
 		let response;
 		try {
@@ -318,7 +342,7 @@ class ApickClient {
 			throw new ApickApiError(failureMessage, {
 				status: response.status,
 				code: response.status === 401 ? 'APICK_AUTH_ERROR' : 'APICK_API_ERROR',
-				serviceCode: body && body.data && typeof body.data.error_code === 'string' ? body.data.error_code : undefined
+				serviceCode: body && body.data && typeof (body.data.code || body.data.error_code) === 'string' ? (body.data.code || body.data.error_code) : undefined
 			});
 		}
 
@@ -437,15 +461,41 @@ class ApickClient {
 		return this._call('screenshot', { url: normalizeUrl(url) });
 	}
 
-	textToSpeech(text, options) {
+	createTtsJob(text, options) {
 		const config = options || {};
-		const language = config.language || 'ko';
-		if (!['ko', 'en', 'zh', 'de', 'es', 'fr', 'ja'].includes(language)) {
-			throw new RangeError('language must be one of: ko, en, zh, de, es, fr, ja.');
-		}
-		return this._call('textToSpeech', {
-			content: requiredString('text', text, 1_000),
-			language
+		return this._call('createTtsJob', {
+			voice_id: normalizeTtsVoice(config.voiceId || 'narrator_m_03'),
+			text: requiredString('text', text, 800)
+		});
+	}
+
+	getTtsJob(jobId) {
+		const id = normalizeTtsJobId(jobId);
+		return this._call('createTtsJob', null, null, { endpoint: '/rest/tts/jobs/' + id, method: 'GET' });
+	}
+
+	cancelTtsJob(jobId) {
+		const id = normalizeTtsJobId(jobId);
+		return this._call('createTtsJob', null, null, { endpoint: '/rest/tts/jobs/' + id + '/cancel' });
+	}
+
+	downloadTtsResult(jobId) {
+		const id = normalizeTtsJobId(jobId);
+		return this._call('createTtsJob', null, null, {
+			endpoint: '/rest/tts/jobs/' + id + '/result',
+			method: 'GET',
+			output: 'binary',
+			filename: id + '.mp3'
+		});
+	}
+
+	downloadTtsSubtitles(jobId) {
+		const id = normalizeTtsJobId(jobId);
+		return this._call('createTtsJob', null, null, {
+			endpoint: '/rest/tts/jobs/' + id + '/subtitles',
+			method: 'GET',
+			output: 'binary',
+			filename: id + '.ass'
 		});
 	}
 
@@ -479,5 +529,6 @@ module.exports = {
 	ApickApiError,
 	ApickBinaryResult,
 	SERVICES,
+	TTS_VOICE_IDS,
 	DEFAULT_BASE_URL
 };

package/src/index.d.ts

@@ -31,6 +31,24 @@ export interface MaskResidentNumberOptions extends OcrOptions {
 	type: 1 | 2 | 3;
 }
 
+export const TTS_VOICE_IDS: readonly [
+	'narrator_m_01', 'narrator_m_02', 'narrator_m_03', 'narrator_m_04', 'narrator_m_05',
+	'narrator_f_10s_01', 'narrator_f_10s_02', 'narrator_f_10s_03',
+	'narrator_m_20s_01', 'narrator_f_20s_01', 'narrator_f_20s_02',
+	'narrator_f_20s_03', 'narrator_f_20s_04', 'narrator_m_30s_01',
+	'narrator_m_30s_02', 'narrator_m_40s_01', 'narrator_m_80s_01'
+];
+export type TtsVoiceId = typeof TTS_VOICE_IDS[number];
+
+export interface TtsJobData {
+	job_id: string;
+	status: 'waiting' | 'processing' | 'completed' | 'cancelled' | 'failed';
+	voice_id?: TtsVoiceId;
+	character_count?: number;
+	result_available?: boolean;
+	subtitles_available?: boolean;
+}
+
 export class ApickApiError extends Error {
 	readonly status: number;
 	readonly code: string;
@@ -84,7 +102,11 @@ export class ApickClient {
 	googleSearch(keyword: string, options?: { page?: number }): Promise<ApickResult>;
 	googleImageSearch(keyword: string, options?: { page?: number }): Promise<ApickResult>;
 	screenshot(url: string): Promise<ApickBinaryResult>;
-	textToSpeech(text: string, options?: { language?: 'ko' | 'en' | 'zh' | 'de' | 'es' | 'fr' | 'ja' }): Promise<ApickBinaryResult>;
+	createTtsJob(text: string, options?: { voiceId?: TtsVoiceId }): Promise<ApickResult<TtsJobData>>;
+	getTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
+	cancelTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
+	downloadTtsResult(jobId: string): Promise<ApickBinaryResult>;
+	downloadTtsSubtitles(jobId: string): Promise<ApickBinaryResult>;
 	htmlToPdf(html: string, options?: { pagination?: boolean }): Promise<ApickBinaryResult>;
 	jsonToExcel(data: unknown[], options?: { sheetName?: string }): Promise<ApickBinaryResult>;
 	summarize(text: string): Promise<ApickResult>;

package/src/index.js

@@ -5,6 +5,7 @@ export const {
 	ApickApiError,
 	ApickBinaryResult,
 	SERVICES,
+	TTS_VOICE_IDS,
 	DEFAULT_BASE_URL
 } = sdk;