apick-api 3.0.0 → 3.4.0

package/docs/guide.en.md

@@ -1,182 +1,235 @@
-# apick-api English guide
-
-`apick-api` is the official zero-dependency Node.js SDK for a focused set of popular APICK REST APIs. It supports ESM, CommonJS, and TypeScript.
-
-## Install and authenticate
-
-```bash
-npm install apick-api
-```
-
-```js
-import { ApickClient } from 'apick-api';
-
-const client = new ApickClient({
-  apiKey: process.env.APICK_API_KEY,
-  timeoutMs: 60_000
-});
-```
-
-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
-const business = await client.businessDetails('439-87-00761');
-const venture = await client.ventureBusiness('4398700761');
-const email = await client.validateEmail('sample@example.com');
-const phone = await client.validatePhone('01012341234');
-const holidays = await client.holidays(2026, 10);
-const addresses = await client.searchAddress('가산디지털로', { page: 1 });
-```
-
-Hyphens are removed from business numbers automatically. Invalid required values fail locally with `TypeError` or `RangeError` before an API request is sent.
-
-## Parcel tracking
-
-Use carrier-specific tracking when you know the carrier:
-
-```js
-const parcel = await client.trackParcel('cj', '123456789012');
-```
-
-Use automatic carrier detection when you only have the tracking number:
-
-```js
-const parcel = await client.trackParcelAuto('123456789012');
-```
-
-## Domain and search tools
-
-```js
-const dns = await client.dnsLookup('apick.app');
-const location = await client.geolocate('apick.app');
-const registration = await client.whois('apick.app');
-const web = await client.googleSearch('APICK API', { page: 1 });
-const images = await client.googleImageSearch('Seoul skyline', { page: 1 });
-```
-
-## OCR
-
-OCR accepts PNG and JPEG files up to 50MB.
-
-```js
-const ocr = await client.ocr('./receipt.jpg');
-console.log(ocr.data.result.full_text);
-```
-
-For in-memory input, supply a filename and MIME type when needed:
-
-```js
-await client.ocr(bytes, {
-  filename: 'scan.png',
-  contentType: 'image/png'
-});
-```
-
-## 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 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');
-
-const excel = await client.jsonToExcel([{ item: 'A', count: 3 }], {
-  sheetName: 'Inventory'
-});
-await excel.save('./inventory.xlsx');
-```
-
-Binary results expose `bytes`, `size`, `filename`, `contentType`, and `meta`. `save()` writes a file in Node.js, while `toBlob()` creates a standard `Blob`.
-
-## Text AI
-
-```js
-const summary = await client.summarize(longText);
-const polished = await client.polish(draftText);
-```
-
-Text input is limited to 100,000 characters.
-
-## Image AI
-
-```js
-const result = await client.generateImages('A clean product photo on white', {
-  imageCount: 4, size: '1024x1024', outputFormat: 'webp',
-  idempotencyKey: 'product-draft-001'
-});
-
-const referenceResult = await client.generateImages('Keep the product shape and composition, and change the background to a sunny kitchen', {
-  referenceImage: './reference.png',
-  referenceFilename: 'reference.png',
-  referenceContentType: 'image/png'
-});
-
-const job = await client.createImageGenerationJob('Landscape article cover concepts', { imageCount: 20, size: '1536x1024' });
-const status = await client.getImageJob(job.data.job_id);
-```
-
-`imageCount` is the number of images to make and defaults to one. Synchronous generation and editing support 1–4 images; job methods support 1–50. Add `referenceImage` to generation when the prompt should build from an existing composition, palette, or product shape. Editing accepts one PNG, JPEG, or WebP source up to 50 MB plus a prompt; mask files are not supported. Choose one of five sizes: `1024x1024`, `1536x1024`, `1024x1536`, `1152x864`, or `864x1152`; prompts may contain up to 28,000 characters. The full image count × 25 points is deducted when accepted, and 25 points are refunded immediately for every failed image. Accepted jobs cannot be cancelled. Results remain available for 24 hours.
-
-`idempotencyKey` is a safety identifier that prevents duplicate generation and billing if a network problem sends the same request twice. Use 8–128 letters, numbers, underscores, or hyphens. Reuse it only for the exact same request and create a new value when the prompt or options change.
-
-Methods: `generateImages`, `editImages`, `createImageGenerationJob`, `createImageEditJob`, `getImageJob`, `downloadImageJobImage`, and `downloadImageJobArchive`.
-
-## Response shape
-
-JSON methods resolve to:
-
-```ts
-{
-  data: unknown;
-  meta: {
-    cost: number | null;
-    durationMs: number | null;
-  };
-}
-```
-
-`meta.cost` is the point charge reported by the API response. See the APICK documentation for current rates.
-
-## Identity masking
-
-```js
-const png = await client.maskResidentNumber('./id-card.jpg', { type: 3 });
-await png.save('./masked.png');
-
-const result = await client.maskDriverLicense('./license.jpg');
-console.log(result.data.result.fields);
-```
-
-The document-specific methods are `maskResidenceCard`, `maskPassport`, `maskIdCard`, and `maskDriverLicense`. Identity errors are exposed as `IDENTITY_TEXT_UNREADABLE`, `IDENTITY_DOCUMENT_MISMATCH`, or `IDENTITY_PROCESSING_FAILED` through `ApickApiError.serviceCode`.
-
-`maskResidenceCard` accepts one front-side image of a residence card, permanent resident card, or overseas Korean resident card. Permanent and overseas Korean card support is limited to PII masking and does not expand the alien registration card authenticity-check scope.
-
-## Errors and retries
-
-`ApickApiError` includes public error information: `code`, optional `serviceCode`, `status`, and `message`. The SDK does not retry automatically because a retry could duplicate an API call and its charge. If your application needs retries, decide explicitly after checking the error code and whether the operation is safe to repeat.
+# apick-api English guide
+
+## Request and response formats
+
+All SDK requests with a body use `multipart/form-data`. Arrays use separate indexed fields such as `utterance_ids[0]`; let the SDK set the Content-Type boundary. GET requests have no body. The server continues accepting older JSON requests for compatibility.
+
+The SDK preserves original LF/CR characters using UTF-8 Base64 and a `__apick_encoding[field]=base64-utf8` form metadata field. Excel cells also carry type metadata; dates become ISO strings and sparse array cells become null.
+
+Responses remain service-specific JSON or direct files. A failed download may return JSON, which the SDK exposes as `ApickApiError`. Individual REST guides provide OpenAPI and Postman downloads. External MCP connections retain JSON-RPC.
+
+`apick-api` is the official zero-dependency Node.js SDK for a focused set of popular APICK REST APIs. It supports ESM, CommonJS, and TypeScript.
+
+## Install and authenticate
+
+```bash
+npm install apick-api
+```
+
+```js
+import { ApickClient } from 'apick-api';
+
+const client = new ApickClient({
+  apiKey: process.env.APICK_API_KEY,
+  timeoutMs: 60_000
+});
+```
+
+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
+const business = await client.businessDetails('439-87-00761');
+const venture = await client.ventureBusiness('4398700761');
+const email = await client.validateEmail('sample@example.com');
+const phone = await client.validatePhone('01012341234');
+const holidays = await client.holidays(2026, 10);
+const addresses = await client.searchAddress('가산디지털로', { page: 1 });
+```
+
+Hyphens are removed from business numbers automatically. Invalid required values fail locally with `TypeError` or `RangeError` before an API request is sent.
+
+## Parcel tracking
+
+Use carrier-specific tracking when you know the carrier:
+
+```js
+const parcel = await client.trackParcel('cj', '123456789012');
+```
+
+Use automatic carrier detection when you only have the tracking number:
+
+```js
+const parcel = await client.trackParcelAuto('123456789012');
+```
+
+## Domain and search tools
+
+```js
+const dns = await client.dnsLookup('apick.app');
+const location = await client.geolocate('apick.app');
+const registration = await client.whois('apick.app');
+const web = await client.googleSearch('APICK API', { page: 1 });
+const images = await client.googleImageSearch('Seoul skyline', { page: 1 });
+```
+
+## OCR
+
+OCR accepts PNG and JPEG files up to 50MB.
+
+```js
+const ocr = await client.ocr('./receipt.jpg');
+console.log(ocr.data.result.full_text);
+```
+
+For in-memory input, supply a filename and MIME type when needed:
+
+```js
+await client.ocr(bytes, {
+  filename: 'scan.png',
+  contentType: 'image/png'
+});
+```
+
+## Generated files
+
+TTS supports 16 voice IDs. Use `TTS_VOICE_IDS` and the developer guide for the current list.
+
+`v2_ann_m_30s_01`, `v2_ann_m_30s_02`, `v2_ann_m_30s_04`, `v2_ann_m_30s_05`, `v2_ann_f_30s_01`, `v2_ann_f_30s_02`, `v2_ann_f_30s_03`, `v2_ann_f_30s_04`, `v2_ann_f_30s_05`, `v2_m_teen_01`, `v2_m_young_01`, `v2_m_mid_01`, `v2_m_senior_01`, `v2_f_teen_01`, `v2_f_young_01`, `v2_f_senior_01`
+
+```js
+const screenshot = await client.screenshot('https://example.com');
+await screenshot.save('./example.jpeg');
+
+const created = await client.createTtsJob('오늘의 이야기를 시작합니다.', { voiceId: 'v2_ann_m_30s_01' });
+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');
+
+const excel = await client.jsonToExcel([{ item: 'A', count: 3 }], {
+  sheetName: 'Inventory'
+});
+await excel.save('./inventory.xlsx');
+```
+
+Binary results expose `bytes`, `size`, `filename`, `contentType`, and `meta`. `save()` writes a file in Node.js, while `toBlob()` creates a standard `Blob`.
+
+## Text AI
+
+```js
+const summary = await client.summarize(longText);
+const polished = await client.polish(draftText);
+```
+
+Text input is limited to 100,000 characters.
+
+## Image AI
+
+```js
+const result = await client.generateImages('A clean product photo on white', {
+  imageCount: 4, size: '1024x1024', outputFormat: 'webp',
+  idempotencyKey: 'product-draft-001'
+});
+
+const referenceResult = await client.generateImages('Keep the product shape and composition, and change the background to a sunny kitchen', {
+  referenceImage: './reference.png',
+  referenceFilename: 'reference.png',
+  referenceContentType: 'image/png'
+});
+
+const job = await client.createImageGenerationJob('Landscape article cover concepts', { imageCount: 20, size: '1536x1024' });
+const status = await client.getImageJob(job.data.job_id);
+```
+
+`imageCount` is the number of images to make and defaults to one. Synchronous generation and editing support 1–4 images; job methods support 1–50. Add `referenceImage` to generation when the prompt should build from an existing composition, palette, or product shape. Editing accepts one PNG, JPEG, or WebP source up to 50 MB plus a prompt; mask files are not supported. Choose one of five sizes: `1024x1024`, `1536x1024`, `1024x1536`, `1152x864`, or `864x1152`; prompts may contain up to 28,000 characters. The full image count × 25 points is deducted when accepted, and 25 points are refunded immediately for every failed image. Accepted jobs cannot be cancelled. Results remain available for 24 hours.
+
+`idempotencyKey` is a safety identifier that prevents duplicate generation and billing if a network problem sends the same request twice. Use 8–128 letters, numbers, underscores, or hyphens. Reuse it only for the exact same request and create a new value when the prompt or options change.
+
+Methods: `generateImages`, `editImages`, `createImageGenerationJob`, `createImageEditJob`, `getImageJob`, `downloadImageJobImage`, and `downloadImageJobArchive`.
+
+## Response shape
+
+JSON methods resolve to:
+
+```ts
+{
+  data: unknown;
+  meta: {
+    cost: number | null;
+    durationMs: number | null;
+  };
+}
+```
+
+`meta.cost` is the point charge reported by the API response. See the APICK documentation for current rates.
+
+## Identity masking
+
+```js
+const png = await client.maskResidentNumber('./id-card.jpg', { type: 3 });
+await png.save('./masked.png');
+
+const result = await client.maskDriverLicense('./license.jpg');
+console.log(result.data.result.fields);
+```
+
+The document-specific methods are `maskResidenceCard`, `maskPassport`, `maskIdCard`, and `maskDriverLicense`. Identity errors are exposed as `IDENTITY_TEXT_UNREADABLE`, `IDENTITY_DOCUMENT_MISMATCH`, or `IDENTITY_PROCESSING_FAILED` through `ApickApiError.serviceCode`.
+
+`maskResidenceCard` accepts one front-side image of a residence card, permanent resident card, or overseas Korean resident card. Permanent and overseas Korean card support is limited to PII masking and does not expand the alien registration card authenticity-check scope.
+
+## Simple-auth data lookups
+
+Employment, income, pension, driver's license, and health checkup lookups require the user's own simple-auth verification, so the call is split into acceptance (`request*`) and result polling (`get*`).
+
+```js
+const accepted = await client.requestDrivingLicense({
+  name: 'Hong Gildong',
+  birthDate: '19900101',
+  phone: '01011112222',
+  authProvider: 'kakao'
+});
+
+let result;
+do {
+  await new Promise(resolve => setTimeout(resolve, 3000));
+  result = await client.getDrivingLicense(accepted.data.transactionId);
+} while (result.data.status === 'AUTH_WAITING' || result.data.status === 'COLLECTING');
+```
+
+`authProvider` is one of the 13 values in `AUTH_PROVIDERS` (kakao, naver, toss, pass, samsung, kb, shinhan, hana, woori, ibk, nh, kakaobank, banksalad). Acceptance is billed at a flat rate; the result is billed only on its first return and free to re-poll afterward. `requestEmployment` takes an optional `insuranceYears` (1-3), `requestPersonalIncome` takes `incomeYears` (1-5), and `requestNpsJoinHistory` takes optional `from`/`to` (`YYYY-MM`). The remaining products are `requestDrivingLicense` and `requestHealthCheckup`.
+
+## Errors and retries
+
+`ApickApiError` includes public error information: `code`, optional `serviceCode`, `status`, and `message`. The SDK does not retry automatically because a retry could duplicate an API call and its charge. If your application needs retries, decide explicitly after checking the error code and whether the operation is safe to repeat.
+# TTS quality and recovery
+
+Use `getTtsQuality(jobId)` to inspect utterance speed, rejection reasons, and candidate history. Candidates remain available for 72 hours after the job terminates. `downloadTtsCandidate(jobId, candidateId)` does not consume the final MP3 or ASS download.
+
+`retryTtsJob(jobId, ['u002'], idempotencyKey)` requests technical recovery within the same job without an additional charge. Reuse the same key and utterance list after a lost response. Check `resume_revision` to identify the current revision. Required quality checks must pass before a job completes.
+
+## Video model versions
+
+Omitting `version` preserves Seedance 2.5, Veo 3.1 and Kling 3.0. Set `version` and `tier` explicitly to select a generation; jobs are never silently switched to another version. Submission and status responses include `version`.
+
+Available generations: Seedance 1.0/1.5/2.0/2.5, including Seedance 2.0 Standard/Fast/Mini; Veo 3.1 (Standard/Fast/Lite); Kling 1.6/2.0/2.1/2.5/2.6/3.0/O1/O3. Veo 3.0 is unavailable. Seedance 2.0 Mini supports 480p/720p and 4–15 seconds. Modes, tiers, resolutions, durations, audio, file limits and prices vary by combination. See the [Seedance](https://apick.app/dev_guide/seedancejobs), [Veo](https://apick.app/dev_guide/veojobs) and [Kling](https://apick.app/dev_guide/klingjobs) version tables. Unsupported combinations are rejected before submission.
+
+Seedance reference mode accepts `referenceImages`, `referenceVideos`, and `referenceAudios` (MP3/WAV) when supported by the selected version.
+
+```js
+const job = await client.createVideoJob("kling", "A boat crossing the sea", {
+  version: "1.6", tier: "std", mode: "text", duration: 5, audio: false,
+  idempotencyKey: "boat-video-0001"
+});
+const status = await client.getVideoJob("kling", job.data.job_id);
+if (status.data.status === "completed") {
+  await (await client.downloadVideoResult("kling", job.data.job_id)).save("boat.mp4");
+}
+```