apick-api 4.3.0 → 4.3.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 4.3.1
+
+- Pricing notes (Terms art. 9 amended, effective 2026-11-06): TTS synthesis has a 5-point base fee per job and result-billed collection jobs have a 10-point base fee per job with results (Instagram comments 50). Fractional points are rounded up (0.1 → 1) and every billed use is at least 1 point. No method or type changes.
+- 요금 안내 갱신(이용약관 제9조 개정, 2026-11-06 시행): TTS 합성 작업당 기본요금 5P, 결과 건수 과금 수집 작업은 결과가 있을 때 작업당 10P(인스타그램 댓글 50P)입니다. 포인트 계산의 소수점은 올림하며(0.1P → 1P) 과금되는 이용 1건은 최소 1P입니다. 메서드·타입 변경은 없습니다.
+- 에이픽 에이전트(`apick-agent`) 안내: AI 사용 작업 기본 5P(2026-11-06부터), 캐시 재사용 1P로 표기를 실제 요금에 맞췄습니다. / `apick-agent` notes now match billing: 5-point base fee for AI jobs from 2026-11-06, cache reuse 1 point.
+
 # 4.3.0
 
 - Add `createGoogleMapsPlaceJob(placeIdOrUrl)` with the `GoogleMapsPlace` result type: rating, reviews count, 1-5 star distribution, top reviews (up to 10), opening hours, busy hours, similar places and photos. 20 points per place, refunded if not found; text is returned in English.

package/README.md

@@ -491,9 +491,9 @@ if (status.data.status === "completed") {
 
 ## 서브에이전트 / Subagent
 
-설치형 `apick-agent` 상품은 `apick-subagent` 스킬 패키지와 전용 REST·MCP를 사용합니다. 원가 +40%, 승인된 동일 결과 캐시 무료, 충전 잔액 외 상품 한도 없음. [연동 가이드](https://apick.app/dev_guide/subagent).
+설치형 `apick-agent` 상품은 `apick-subagent` 스킬 패키지와 전용 REST·MCP를 사용합니다. 설치비·도입비·구독료 없이 원가 +40%(소수점 올림, 2026-11-06부터 AI 사용 작업 기본 5P), 승인된 동일 결과 캐시 1P, 충전 잔액 외 상품 한도 없음. [연동 가이드](https://apick.app/dev_guide/subagent).
 
-The installed `apick-agent` product uses the `apick-subagent` skill package and dedicated REST/MCP interfaces. Confirmed cost plus 40%; approved identical cache reuse is free, with no product quota beyond prepaid balance. [Integration guide](https://apick.app/dev_guide/subagent).
+The installed `apick-agent` product uses the `apick-subagent` skill package and dedicated REST/MCP interfaces. No installation, setup or subscription fee. Confirmed cost plus 40% (fractions rounded up, 5-point base fee for AI jobs from 2026-11-06); approved identical cache reuse costs 1 point, with no product quota beyond prepaid balance. [Integration guide](https://apick.app/dev_guide/subagent).
 
 ```sh
 npx -y apick-mcp --server subagent

package/docs/guide.en.md

@@ -96,6 +96,8 @@ const done = await client.waitForScrapeJob(job.data.job_id); // every 10 s, up t
 console.log(done.data.status, done.data.charged_point, done.data.items);
 ```
 
+Result-billed collection jobs are charged per result; from 2026-11-06 a job with at least one result has a base fee (10 points, Instagram comments 50). Jobs with no results or failures are fully refunded.
+
 For a Google Maps place, pass the `place_id` from `googleMapsSearch` to get details, the star distribution and top reviews (up to 10). 20 points per place; text is returned in English.
 
 ```js

package/docs/guide.ko.md

@@ -96,6 +96,8 @@ const done = await client.waitForScrapeJob(job.data.job_id); // 기본 10초 간
 console.log(done.data.status, done.data.charged_point, done.data.items);
 ```
 
+결과 건수 과금 수집 작업은 결과 1건당 단가로 정산하며, 2026-11-06부터 결과가 1건 이상이면 작업당 기본요금(10P, 인스타그램 댓글 50P)을 최소액으로 받습니다. 결과가 없거나 실패하면 예약한 포인트를 모두 돌려드립니다.
+
 구글 지도 장소는 `googleMapsSearch` 결과의 `place_id` 로 상세·별점 분포·대표 리뷰(최대 10건)를 받습니다. 건당 20포인트이고 텍스트는 영어로 제공합니다.
 
 ```js

package/docs/skill-artifacts.md

@@ -1,24 +1,24 @@
-# 스킬 결과 파일 · Skill artifacts
-
-스킬 상세와 견적의 `execution_info`는 예상 가격 범위, 처리 시간 범위, 도구별 보통·최대 호출 수를 제공합니다. 실측 표본에 따른 예상이며 입력에 따라 달라집니다. 실행 전 견적의 `max_points`를 확인하세요.
-
-`execution_info` on Skill details and quotes describes estimated price and duration ranges and typical/maximum tool calls. These are estimates, not guarantees. Check `max_points` before running a Skill.
-
-```js
-const quote = await apick.quoteSkill(skillId, input);
-console.log(quote.data.execution_info);
-const run = await apick.runSkill(skillId, input, {
-  idempotencyKey: 'my-unique-request',
-  quoteId: quote.data.quote_id,
-  maxCostPoints: quote.data.max_points
-});
-// Poll getSkillRun until status is succeeded, then:
-const result = await apick.getSkillRunResult(run.data.run_id);
-const file = result.data.result.artifacts[0];
-const downloaded = await apick.getSkillArtifact(run.data.run_id, file.id);
-await downloaded.save('./result.png');
-```
-
-파일의 `name`, `mime_type`, `bytes`, `sha256`을 확인하고 실제 형식에 맞는 확장자로 저장하세요. 인증키 소유자의 실행 파일만 내려받을 수 있고, 실행 결과가 만료되면 파일도 만료됩니다. 실패·취소·시간 초과는 예약액을 반환하며, 가변 요금 상품은 성공 시 실제 사용료를 정산합니다. 공급자 청구서와 대조한 확정 원가를 뜻하지 않습니다.
-
-Use `name`, `mime_type`, `bytes`, and `sha256` to identify and verify each file; choose a matching extension. Downloads require the run owner's API key and expire with the result. Failed, cancelled, and timed-out runs release the reservation. Variable-price Skills settle recorded tool usage on success; calculated vendor costs are not invoice-reconciled amounts.
+# 스킬 결과 파일 · Skill artifacts
+
+스킬 상세와 견적의 `execution_info`는 예상 가격 범위, 처리 시간 범위, 도구별 보통·최대 호출 수를 제공합니다. 실측 표본에 따른 예상이며 입력에 따라 달라집니다. 실행 전 견적의 `max_points`를 확인하세요.
+
+`execution_info` on Skill details and quotes describes estimated price and duration ranges and typical/maximum tool calls. These are estimates, not guarantees. Check `max_points` before running a Skill.
+
+```js
+const quote = await apick.quoteSkill(skillId, input);
+console.log(quote.data.execution_info);
+const run = await apick.runSkill(skillId, input, {
+  idempotencyKey: 'my-unique-request',
+  quoteId: quote.data.quote_id,
+  maxCostPoints: quote.data.max_points
+});
+// Poll getSkillRun until status is succeeded, then:
+const result = await apick.getSkillRunResult(run.data.run_id);
+const file = result.data.result.artifacts[0];
+const downloaded = await apick.getSkillArtifact(run.data.run_id, file.id);
+await downloaded.save('./result.png');
+```
+
+파일의 `name`, `mime_type`, `bytes`, `sha256`을 확인하고 실제 형식에 맞는 확장자로 저장하세요. 인증키 소유자의 실행 파일만 내려받을 수 있고, 실행 결과가 만료되면 파일도 만료됩니다. 실패·취소·시간 초과는 예약액을 반환하며, 가변 요금 상품은 성공 시 실제 사용료를 정산합니다. 공급자 청구서와 대조한 확정 원가를 뜻하지 않습니다.
+
+Use `name`, `mime_type`, `bytes`, and `sha256` to identify and verify each file; choose a matching extension. Downloads require the run owner's API key and expire with the result. Failed, cancelled, and timed-out runs release the reservation. Variable-price Skills settle recorded tool usage on success; calculated vendor costs are not invoice-reconciled amounts.

package/docs/subagent.md

@@ -1,8 +1,8 @@
 # 서브에이전트 / Subagent
 
-`apick-agent`는 설치형 상품이며 `quoteSkill`·`runSkill` 대신 전용 API를 사용합니다. 성공 작업의 확인된 원가에 40%를 가산하며 승인된 동일 결과 캐시는 무료입니다. 충전 잔액 외 상품 사용량 한도는 없습니다.
+`apick-agent`는 설치형 상품이며 `quoteSkill`·`runSkill` 대신 전용 API를 사용합니다. 설치비·도입비·구독료는 없고, 성공 작업의 확인된 원가에 40%를 가산합니다(소수점 올림, 2026-11-06부터 AI 사용 작업 기본 5P). 승인된 동일 결과 캐시는 1P입니다. 충전 잔액 외 상품 사용량 한도는 없습니다.
 
-`apick-agent` is an installed-agent product. Use the dedicated API rather than `quoteSkill` or `runSkill`. Successful work is billed at confirmed model cost plus 40%; approved identical-result cache reuse is free. There are no product usage quotas beyond prepaid balance.
+`apick-agent` is an installed-agent product. Use the dedicated API rather than `quoteSkill` or `runSkill`. There is no installation, setup or subscription fee. Successful work is billed at confirmed model cost plus 40% (fractions rounded up, 5-point base fee for AI jobs from 2026-11-06); approved identical-result cache reuse costs 1 point. There are no product usage quotas beyond prepaid balance.
 
 ```js
 import { ApickClient } from 'apick-api';

package/docs/tts.md

@@ -25,9 +25,9 @@ Style, emotion, tone, accent, pace, pitch and volume options can be set per requ
 
 Normalization is enabled by default and costs extra. Disable it with `normalize_text: false` (`normalizeText: false` for the string SDK helper). Input limits are 2,000 characters including utterance separators with normalization, or 8,000 without it. Query a quote, engine-specific voices and supported options before submitting.
 
-실제 AI 원가 × 고정된 환율 × 1.4에 정규화 요금을 더해 정산합니다. Gemini 프로모션 입력/출력 단가는 2026-12-31까지 백만 토큰당 $0.50/$6.00이며 2027-01-01 00:00 UTC부터 $1.00/$12.00입니다. 약 $0.54/시간은 참고값이며 시간 단위 청구가 아닙니다. 엔진별 요금이 다릅니다.
+실제 AI 원가 × 고정된 환율 × 1.4에 정규화 요금을 더해 정산합니다. 소수점은 올림하며, 2026-11-06부터 합성 작업 1건의 기본요금 5P를 최소액으로 받습니다. Gemini 프로모션 입력/출력 단가는 2026-12-31까지 백만 토큰당 $0.50/$6.00이며 2027-01-01 00:00 UTC부터 $1.00/$12.00입니다. 약 $0.54/시간은 참고값이며 시간 단위 청구가 아닙니다. 엔진별 요금이 다릅니다.
 
-AI usage is charged at verified cost × the pinned exchange rate × 1.4, plus normalization. Gemini promotional input/output rates are $0.50/$6.00 per million tokens through 2026-12-31, then $1.00/$12.00 from 2027-01-01 00:00 UTC. The approximate hourly figure is informational; billing uses actual usage and differs by engine.
+AI usage is charged at verified cost × the pinned exchange rate × 1.4, plus normalization. Fractions are rounded up, and from 2026-11-06 each synthesis job has a 5-point base fee. Gemini promotional input/output rates are $0.50/$6.00 per million tokens through 2026-12-31, then $1.00/$12.00 from 2027-01-01 00:00 UTC. The approximate hourly figure is informational; billing uses actual usage and differs by engine.
 
 두 엔진은 같은 작업 조회·취소·MP3·원문 ASS 계약을 사용합니다. `billing`의 예약·해제·확정·환불을 확인하세요. MP3는 24kHz 모노 48kbps, 결과는 완료 후 24시간 보관합니다. MP3와 ASS는 각각 완료된 다운로드 1회만 허용하며 전송 중단은 재시도할 수 있습니다. 접수 응답 유실 시 같은 입력과 멱등 키를 재사용하세요. 서버·공급자 최종 실패는 정규화까지 환불하며, 연결 종료는 작업 취소가 아닙니다. 취소 시 이미 수행된 작업분을 정산합니다.
 

package/examples/basic.mjs

@@ -1,10 +1,10 @@
-import { ApickClient } from 'apick-api';
-
-const client = new ApickClient(process.env.APICK_API_KEY);
-
-const business = await client.businessDetails('439-87-00761');
-console.log(business.data);
-console.log(business.meta);
-
-const parcel = await client.trackParcelAuto('123456789012');
-console.log(parcel.data);
+import { ApickClient } from 'apick-api';
+
+const client = new ApickClient(process.env.APICK_API_KEY);
+
+const business = await client.businessDetails('439-87-00761');
+console.log(business.data);
+console.log(business.meta);
+
+const parcel = await client.trackParcelAuto('123456789012');
+console.log(parcel.data);

package/examples/commonjs.cjs

@@ -1,12 +1,12 @@
-const { ApickClient } = require('apick-api');
-
-async function main() {
-	const client = new ApickClient(process.env.APICK_API_KEY);
-	const result = await client.whois('apick.app');
-	console.log(result.data);
-}
-
-main().catch((error) => {
-	console.error(error.message);
-	process.exitCode = 1;
-});
+const { ApickClient } = require('apick-api');
+
+async function main() {
+	const client = new ApickClient(process.env.APICK_API_KEY);
+	const result = await client.whois('apick.app');
+	console.log(result.data);
+}
+
+main().catch((error) => {
+	console.error(error.message);
+	process.exitCode = 1;
+});

package/examples/files.mjs

@@ -1,9 +1,9 @@
-import { ApickClient } from 'apick-api';
-
-const client = new ApickClient(process.env.APICK_API_KEY);
-
-const ocr = await client.ocr('./receipt.jpg');
-console.log(ocr.data.result.full_text);
-
-const pdf = await client.htmlToPdf('<h1>APICK report</h1>', { pagination: true });
-await pdf.save('./report.pdf');
+import { ApickClient } from 'apick-api';
+
+const client = new ApickClient(process.env.APICK_API_KEY);
+
+const ocr = await client.ocr('./receipt.jpg');
+console.log(ocr.data.result.full_text);
+
+const pdf = await client.htmlToPdf('<h1>APICK report</h1>', { pagination: true });
+await pdf.save('./report.pdf');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
   "type": "module",
   "main": "./src/index.cjs",

package/src/form.cjs

@@ -1,28 +1,28 @@
-'use strict';
-
-// Client-only multipart serialization. Each value occupies its own form part.
-function createForm(payload, endpoint) {
-    const form = new FormData();
-    const typed = endpoint === '/rest/json_to_excel';
-    const forbidden = new Set(['__proto__', 'prototype', 'constructor']);
-    function visit(value, parts) {
-        if (parts.some(key => forbidden.has(key) || /[\[\]]/.test(key)) || parts.length > 12) throw new TypeError('Invalid form field path.');
-        const name = parts[0] + parts.slice(1).map(key => `[${key}]`).join('');
-        const cell = typed && parts[0] === 'data_list';
-        if (value === undefined || (value === null && !cell)) return;
-        if (value instanceof Blob) { form.append(name, value); return; }
-        if (value && typeof value === 'object' && Object.keys(value).length) {
-            if (cell) form.append('__apick_type' + parts.map(key => `[${key}]`).join(''), Array.isArray(value) ? 'array' : 'object');
-            for (const key of Object.keys(value)) visit(value[key], parts.concat(key));
-            return;
-        }
-        if (cell && typeof value !== 'string') {
-            form.append('__apick_type' + parts.map(key => `[${key}]`).join(''), value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value);
-        }
-        if (!cell && value && typeof value === 'object') return;
-        form.append(name, value === null || typeof value === 'object' ? '' : String(value));
-    }
-    for (const key of Object.keys(payload || {})) visit(payload[key], [key]);
-    return form;
-}
-module.exports = { createForm };
+'use strict';
+
+// Client-only multipart serialization. Each value occupies its own form part.
+function createForm(payload, endpoint) {
+    const form = new FormData();
+    const typed = endpoint === '/rest/json_to_excel';
+    const forbidden = new Set(['__proto__', 'prototype', 'constructor']);
+    function visit(value, parts) {
+        if (parts.some(key => forbidden.has(key) || /[\[\]]/.test(key)) || parts.length > 12) throw new TypeError('Invalid form field path.');
+        const name = parts[0] + parts.slice(1).map(key => `[${key}]`).join('');
+        const cell = typed && parts[0] === 'data_list';
+        if (value === undefined || (value === null && !cell)) return;
+        if (value instanceof Blob) { form.append(name, value); return; }
+        if (value && typeof value === 'object' && Object.keys(value).length) {
+            if (cell) form.append('__apick_type' + parts.map(key => `[${key}]`).join(''), Array.isArray(value) ? 'array' : 'object');
+            for (const key of Object.keys(value)) visit(value[key], parts.concat(key));
+            return;
+        }
+        if (cell && typeof value !== 'string') {
+            form.append('__apick_type' + parts.map(key => `[${key}]`).join(''), value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value);
+        }
+        if (!cell && value && typeof value === 'object') return;
+        form.append(name, value === null || typeof value === 'object' ? '' : String(value));
+    }
+    for (const key of Object.keys(payload || {})) visit(payload[key], [key]);
+    return form;
+}
+module.exports = { createForm };

package/src/index.js

@@ -1,15 +1,15 @@
-import sdk from './index.cjs';
-
-export const {
-	ApickClient,
-	ApickApiError,
-	ApickBinaryResult,
-	SERVICES,
-	TTS_VOICE_IDS,
-	AUTH_PROVIDERS,
-	SKILL_CATEGORIES,
-	SKILL_SORTS,
-	DEFAULT_BASE_URL
-} = sdk;
-
-export default ApickClient;
+import sdk from './index.cjs';
+
+export const {
+	ApickClient,
+	ApickApiError,
+	ApickBinaryResult,
+	SERVICES,
+	TTS_VOICE_IDS,
+	AUTH_PROVIDERS,
+	SKILL_CATEGORIES,
+	SKILL_SORTS,
+	DEFAULT_BASE_URL
+} = sdk;
+
+export default ApickClient;