apick-api 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 4.1.0
+
+- Add YouTube methods: `youtubeSearch`, `youtubeChannel`, `youtubePlaylist`, `youtubeHashtag`, `youtubeFormats`, `youtubeComments`, `downloadYoutubeVideo` and `downloadYoutubeAudio`. Downloads return a download link valid for 1 hour and are billed as a base fee plus 2 points per 10MB.
+- 유튜브 검색·채널·재생목록·해시태그·다운로드 화질·댓글 조회와 영상(MP4)·오디오(MP3·M4A·Opus) 다운로드 메서드를 추가했습니다. 다운로드는 1시간 유효한 링크를 돌려주며 기본요금에 파일 10MB당 2포인트가 더해집니다.
+- Add `googleNewsSearch`, `googleShoppingSearch`, `googleMapsSearch`, `googleRankCheck`, `instagramProfile`, `instagramPost` and `tiktokProfile` with typed results. Failed calls are not charged.
+- `googleRankCheck` returns `complete`, `checked_pages` and `unchecked_ranks`; when some rank ranges could not be checked, only the checked share is charged.
+- `googleSearch` returns up to 10 results per page; `googleImageSearch` pages are 1-5 (20 per page). Search timeouts are 50 seconds.
+- 구글 뉴스·쇼핑·지도 장소 검색, 검색 순위 확인(1~100위), 인스타그램 프로필·게시물/릴스, 틱톡 프로필 메서드와 결과 타입을 추가했습니다. 실패한 호출은 과금되지 않습니다.
+- `googleSearch` 는 페이지당 최대 10건, `googleImageSearch` 의 page 는 1~5(페이지당 20건)입니다.
+
 # 4.0.1 — 2026-10-06
 
 - 이미지 생성·편집에 `quality` 옵션을 추가했습니다: `basic`(기본) 40P · `advanced` 350P · `premium` 1,400P(장당 고정가, 크기 무관).

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 APICK
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 APICK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -69,12 +69,27 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `geolocate(address)` | 도메인·IP 위치 / Domain and IP location | JSON |
 | `whois(address)` | WHOIS 조회 / WHOIS lookup | JSON |
 | `googleSearch(keyword, options)` | 웹 검색 / Web search | JSON |
-| `googleImageSearch(keyword, options)` | 이미지 검색 / Image search | JSON |
+| `googleImageSearch(keyword, options)` | 이미지 검색(page 1~5) / Image search (pages 1-5) | JSON |
+| `googleNewsSearch(keyword, options)` | 구글 뉴스 검색 / Google News search | JSON |
+| `googleShoppingSearch(keyword, options)` | 구글 쇼핑 검색 / Google Shopping search | JSON |
+| `googleMapsSearch(keyword)` | 구글 지도 장소 검색 / Google Maps place search | JSON |
+| `googleRankCheck(keyword, domain)` | 구글 검색 순위 확인(1~100위) / Google rank check (top 100) | JSON |
 | `screenshot(url)` | 웹페이지 화면캡처 / Web screenshot | Binary |
 | `youtubeMetadata(url)` | 유튜브 영상 정보 / YouTube video metadata | JSON |
 | `youtubeThumbnail(url)` | 유튜브 썸네일 / YouTube thumbnail | JPG |
 | `youtubeSubtitleList(url)` | 유튜브 자막 언어 목록 / YouTube subtitle languages | JSON |
 | `youtubeSubtitle(url, lang, options)` | 유튜브 자막 다운로드 / YouTube subtitles | VTT·SRT·TXT |
+| `youtubeSearch(query, options)` | 유튜브 검색(정렬·필터) / YouTube search with sort and filters | JSON |
+| `youtubeChannel(channel, options)` | 유튜브 채널 정보·탭 목록 / YouTube channel and tab items | JSON |
+| `youtubePlaylist(url, options)` | 유튜브 재생목록 / YouTube playlist | JSON |
+| `youtubeHashtag(hashtag, options)` | 유튜브 해시태그 영상 / YouTube hashtag videos | JSON |
+| `youtubeFormats(url)` | 다운로드 화질·예상 요금 / Downloadable formats and estimated cost | JSON |
+| `youtubeComments(url, options)` | 유튜브 댓글 / YouTube comments | JSON |
+| `downloadYoutubeVideo(url, options)` | 유튜브 영상 MP4 다운로드 링크(1시간) / YouTube MP4 download link (1 hour) | JSON |
+| `downloadYoutubeAudio(url, options)` | 유튜브 오디오 MP3·M4A·Opus 다운로드 링크(1시간) / YouTube audio download link (1 hour) | JSON |
+| `instagramProfile(usernameOrUrl)` | 인스타그램 공개 프로필 / Instagram public profile | JSON |
+| `instagramPost(url)` | 인스타그램 게시물·릴스 / Instagram post or reel | JSON |
+| `tiktokProfile(usernameOrUrl)` | 틱톡 공개 프로필 / TikTok public profile | JSON |
 | `createTtsJob(text, options)` | 한국어 내레이션 작업 접수 / Create TTS job | JSON |
 | `getTtsJob(jobId)` | TTS 작업 상태 / TTS job status | JSON |
 | `cancelTtsJob(jobId)` | 대기·생성 중 TTS 작업 취소 / Cancel waiting or processing TTS job | JSON |

package/SECURITY.md

@@ -1,11 +1,11 @@
-# Security
-
-## API keys
-
-Keep APICK API keys in server-side environment variables. Do not commit keys, include them in client-side browser bundles, place them in URLs, or print them in logs.
-
-If a key may have been exposed, regenerate it from your APICK account immediately.
-
-## Reporting a vulnerability
-
-Please report security issues privately through the contact channel listed at <https://apick.app>. Do not open a public issue containing credentials, personal data, or exploit details.
+# Security
+
+## API keys
+
+Keep APICK API keys in server-side environment variables. Do not commit keys, include them in client-side browser bundles, place them in URLs, or print them in logs.
+
+If a key may have been exposed, regenerate it from your APICK account immediately.
+
+## Reporting a vulnerability
+
+Please report security issues privately through the contact channel listed at <https://apick.app>. Do not open a public issue containing credentials, personal data, or exploit details.

package/docs/guide.en.md

@@ -67,7 +67,21 @@ 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 });
+const images = await client.googleImageSearch('Seoul skyline', { page: 1 }); // pages 1-5
+const news = await client.googleNewsSearch('semiconductor', { page: 1 });
+const shopping = await client.googleShoppingSearch('wireless earbuds');
+const places = await client.googleMapsSearch('Gangnam cafe'); // usually 30-60 seconds
+const rank = await client.googleRankCheck('address search API', 'apick.app'); // top 100
+```
+
+## Public social profiles
+
+Only public information from public accounts is returned. Lookups usually take 20-60 seconds, so allow a request timeout of at least 100 seconds. Failed calls are not charged.
+
+```js
+const instagram = await client.instagramProfile('natgeo');
+const post = await client.instagramPost('https://www.instagram.com/p/DeHufcWDCjf/');
+const tiktok = await client.tiktokProfile('https://www.tiktok.com/@tiktok');
 ```
 
 ## OCR
@@ -106,6 +120,15 @@ const subtitle = await client.youtubeSubtitle(video.data.video_id, 'en', { forma
 await subtitle.save('./' + subtitle.filename);
 await (await client.youtubeThumbnail(video.data.video_id)).save('./thumbnail.jpg');
 
+// Search, channel, comments; check formats, then download (base fee + per-10MB fee, 1-hour link)
+const found = await client.youtubeSearch('파이썬 기초 강좌', { count: 5, sort: 'views' });
+const channel = await client.youtubeChannel('@jocoding', { tab: 'videos', count: 10 });
+const comments = await client.youtubeComments(found.data.results[0].id, { count: 20, sort: 'top' });
+const formats = await client.youtubeFormats(found.data.results[0].id);
+const mp4 = await client.downloadYoutubeVideo(found.data.results[0].id, { quality: '720' });
+console.log(mp4.data.download_url, mp4.data.billing.total);
+const mp3 = await client.downloadYoutubeAudio(found.data.results[0].id, { format: 'mp3', bitrate: 192, start: '0:30', end: '1:30' });
+
 const created = await client.createTtsJob('오늘의 이야기를 시작합니다.', { voiceId: 'Kore' });
 const jobId = created.data.job_id;
 let job = await client.getTtsJob(jobId);

package/docs/guide.ko.md

@@ -67,7 +67,21 @@ 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('에이픽 API', { page: 1 });
-const images = await client.googleImageSearch('서울 야경', { page: 1 });
+const images = await client.googleImageSearch('서울 야경', { page: 1 }); // page 1~5
+const news = await client.googleNewsSearch('반도체', { page: 1 });
+const shopping = await client.googleShoppingSearch('무선 이어폰');
+const places = await client.googleMapsSearch('강남역 카페'); // 보통 30~60초
+const rank = await client.googleRankCheck('주소 검색 API', 'apick.app'); // 1~100위
+```
+
+## SNS 공개 정보
+
+공개 계정의 공개 정보만 제공합니다. 처리에 보통 20~60초가 걸리므로 요청 시간 제한을 100초 이상으로 두세요. 실패한 호출은 과금되지 않습니다.
+
+```js
+const instagram = await client.instagramProfile('natgeo');
+const post = await client.instagramPost('https://www.instagram.com/p/DeHufcWDCjf/');
+const tiktok = await client.tiktokProfile('https://www.tiktok.com/@tiktok');
 ```
 
 ## OCR
@@ -106,6 +120,15 @@ const subtitle = await client.youtubeSubtitle(video.data.video_id, 'en', { forma
 await subtitle.save('./' + subtitle.filename);
 await (await client.youtubeThumbnail(video.data.video_id)).save('./thumbnail.jpg');
 
+// 검색·채널·댓글, 화질 확인 후 다운로드(기본요금 + 10MB당 요금, 1시간 유효 링크)
+const found = await client.youtubeSearch('파이썬 기초 강좌', { count: 5, sort: 'views' });
+const channel = await client.youtubeChannel('@jocoding', { tab: 'videos', count: 10 });
+const comments = await client.youtubeComments(found.data.results[0].id, { count: 20, sort: 'top' });
+const formats = await client.youtubeFormats(found.data.results[0].id);
+const mp4 = await client.downloadYoutubeVideo(found.data.results[0].id, { quality: '720' });
+console.log(mp4.data.download_url, mp4.data.billing.total);
+const mp3 = await client.downloadYoutubeAudio(found.data.results[0].id, { format: 'mp3', bitrate: 192, start: '0:30', end: '1:30' });
+
 const created = await client.createTtsJob('오늘의 이야기를 시작합니다.', { voiceId: 'Kore' });
 const jobId = created.data.job_id;
 let job = await client.getTtsJob(jobId);

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,39 +1,39 @@
-# 서브에이전트 / Subagent
-
-`apick-agent`는 설치형 상품이며 `quoteSkill`·`runSkill` 대신 전용 API를 사용합니다. 성공 작업의 확인된 원가에 40%를 가산하며 승인된 동일 결과 캐시는 무료입니다. 충전 잔액 외 상품 사용량 한도는 없습니다.
-
-`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.
-
-```js
-import { ApickClient } from 'apick-api';
-import { createHash } from 'node:crypto';
-const api = new ApickClient({ apiKey: process.env.APICK_API_KEY });
-const bytes = Buffer.from('검토할 공개 문서입니다.');
-const file = await api.createSubagentFile({
-  path: 'docs/sample.txt', bytes: bytes.length,
-  sha256: createHash('sha256').update(bytes).digest('hex'), retention: 'seven_days'
-});
-if (file.data.state !== 'ready') {
-  for (let offset = 0; offset < bytes.length; offset += file.data.part_bytes) {
-    await api.uploadSubagentPart(file.data.file_id, offset / file.data.part_bytes,
-      bytes.subarray(offset, offset + file.data.part_bytes).toString('base64'));
-  }
-  await api.completeSubagentFile(file.data.file_id);
-}
-const job = await api.dispatchSubagent({kind:'summarize', goal:'핵심 내용과 근거를 정리하세요',
-  file_ids:[file.data.file_id]}, {idempotencyKey:'sample-summary-20261004-001'});
-const result = await api.collectSubagent(job.data.job_id);
-// 완료 후 evidence_ids를 조회하여 인용·해시를 직접 검토하세요.
-// Once complete, fetch evidence_ids and independently review quotes and hashes.
-console.log(result.data.state);
-```
-
-접수 응답은 작업 ID를 신속히 반환합니다. 같은 멱등 키와 같은 내용은 기존 작업을 반환하며 내용이 다르면 409입니다. 연결 종료는 취소가 아닙니다. `cancelSubagent`로 명시적으로 취소하세요. `retention:'none'`은 검수 완료 후 삭제하고 임시 보관은 최대 1시간입니다.
-
-Submission returns a job ID promptly. Replay the same idempotency key and payload after response loss; a changed payload conflicts with HTTP 409. Disconnecting does not cancel work; use `cancelSubagent`. `retention:'none'` deletes after review, with temporary retention capped at one hour.
-
-`subagentUsage`는 호출·토큰·예약·청구·해제·캐시·전송 지표를 반환합니다. 캐시 예상 회피 비용은 동일 작업의 최초 계산 비용 기준이며 주 모델의 실제 청구 절감액이 아닙니다.
-
-`subagentUsage` returns calls, tokens, reservations, charges, releases, cache and transfer metrics. Estimated avoided cache cost uses the original job's calculated cost and is not a measured reduction in the main model's bill.
-
-[전체 REST·MCP 가이드 / Full guide](https://apick.app/dev_guide/subagent)
+# 서브에이전트 / Subagent
+
+`apick-agent`는 설치형 상품이며 `quoteSkill`·`runSkill` 대신 전용 API를 사용합니다. 성공 작업의 확인된 원가에 40%를 가산하며 승인된 동일 결과 캐시는 무료입니다. 충전 잔액 외 상품 사용량 한도는 없습니다.
+
+`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.
+
+```js
+import { ApickClient } from 'apick-api';
+import { createHash } from 'node:crypto';
+const api = new ApickClient({ apiKey: process.env.APICK_API_KEY });
+const bytes = Buffer.from('검토할 공개 문서입니다.');
+const file = await api.createSubagentFile({
+  path: 'docs/sample.txt', bytes: bytes.length,
+  sha256: createHash('sha256').update(bytes).digest('hex'), retention: 'seven_days'
+});
+if (file.data.state !== 'ready') {
+  for (let offset = 0; offset < bytes.length; offset += file.data.part_bytes) {
+    await api.uploadSubagentPart(file.data.file_id, offset / file.data.part_bytes,
+      bytes.subarray(offset, offset + file.data.part_bytes).toString('base64'));
+  }
+  await api.completeSubagentFile(file.data.file_id);
+}
+const job = await api.dispatchSubagent({kind:'summarize', goal:'핵심 내용과 근거를 정리하세요',
+  file_ids:[file.data.file_id]}, {idempotencyKey:'sample-summary-20261004-001'});
+const result = await api.collectSubagent(job.data.job_id);
+// 완료 후 evidence_ids를 조회하여 인용·해시를 직접 검토하세요.
+// Once complete, fetch evidence_ids and independently review quotes and hashes.
+console.log(result.data.state);
+```
+
+접수 응답은 작업 ID를 신속히 반환합니다. 같은 멱등 키와 같은 내용은 기존 작업을 반환하며 내용이 다르면 409입니다. 연결 종료는 취소가 아닙니다. `cancelSubagent`로 명시적으로 취소하세요. `retention:'none'`은 검수 완료 후 삭제하고 임시 보관은 최대 1시간입니다.
+
+Submission returns a job ID promptly. Replay the same idempotency key and payload after response loss; a changed payload conflicts with HTTP 409. Disconnecting does not cancel work; use `cancelSubagent`. `retention:'none'` deletes after review, with temporary retention capped at one hour.
+
+`subagentUsage`는 호출·토큰·예약·청구·해제·캐시·전송 지표를 반환합니다. 캐시 예상 회피 비용은 동일 작업의 최초 계산 비용 기준이며 주 모델의 실제 청구 절감액이 아닙니다.
+
+`subagentUsage` returns calls, tokens, reservations, charges, releases, cache and transfer metrics. Estimated avoided cache cost uses the original job's calculated cost and is not a measured reduction in the main model's bill.
+
+[전체 REST·MCP 가이드 / Full guide](https://apick.app/dev_guide/subagent)

package/docs/tts.md

@@ -1,34 +1,34 @@
-# Gemini·ChatGPT TTS
-
-기존 APICK 목소리와 자동 전환은 종료되었습니다. `createTtsJob`은 Gemini 기본 목소리 `Kore`를 사용합니다. `getTtsQuality`, `retryTtsJob`, `downloadTtsCandidate`의 기존 경로는 HTTP 409를 반환합니다.
-
-Legacy APICK voices and automatic fallback have retired. `createTtsJob` now defaults to Gemini voice `Kore`. The legacy quality, retry and candidate endpoints return HTTP 409.
-
-```js
-const job = await client.createTtsJob('기온은 오 도입니다.', { voiceId: 'Kore', normalizeText: false, idempotencyKey: 'tts-001' });
-const dialogue = await client.createOpenAiTtsJob({
-  utterances: [{ speaker: '진행', text: '반갑습니다.' }, { speaker: '손님', text: '안녕하세요.' }],
-  speakers: { 진행: { voice_id: 'alloy' }, 손님: { voice_id: 'nova', emotion: 'calm' } },
-  multi_speaker: true, normalize_text: false
-}, { idempotencyKey: 'tts-002' });
-const voices = await client.listGeminiTtsVoices();
-const otherVoices = await client.listOpenAiTtsVoices();
-const options = await client.getTtsOptions();
-const quote = await client.quoteTts({ engine: 'gemini', text: '본문', voice_id: 'Kore' });
-```
-
-`style`, `emotion`, `tone`, `accent`, `pace`(0.5–2), `pitch`(-12–12), `volume_gain_db`(-12–12)는 최상위·화자·발화에 지정할 수 있습니다. `speakers`는 화자 이름별 설정이고 `multi_speaker: true`는 Gemini 최대 2명, ChatGPT 최대 8명입니다. 엔진에 따라 표현 효과가 달라지며 정확한 속도 배율·반음·dB 적용을 보장하지 않습니다. 특히 ChatGPT는 수치의 방향을 낭독 지시로 전달합니다.
-
-Style, emotion, tone, accent, pace, pitch and volume options can be set per request, speaker or utterance. Gemini supports up to two native speakers; ChatGPT supports up to eight speakers across utterances. Numeric acoustic adjustments are not guaranteed: ChatGPT receives directional instructions rather than precise rate, semitone or decibel controls.
-
-정규화는 기본 켜짐이며 추가 스킬 요금이 합산됩니다. `normalize_text: false`(SDK 문자열 호출은 `normalizeText: false`)로 끌 수 있습니다. 정규화 입력은 발화 사이 줄바꿈을 포함해 최대 2,000자, 정규화 없이 최대 8,000자입니다. 견적은 `quoteTts`, 현재 목소리는 엔진별 목록, 옵션은 `getTtsOptions`로 조회합니다.
-
-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 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.
-
-두 엔진은 같은 작업 조회·취소·MP3·원문 ASS 계약을 사용합니다. `billing`의 예약·해제·확정·환불을 확인하세요. MP3는 24kHz 모노 48kbps, 결과는 완료 후 24시간 보관합니다. MP3와 ASS는 각각 완료된 다운로드 1회만 허용하며 전송 중단은 재시도할 수 있습니다. 접수 응답 유실 시 같은 입력과 멱등 키를 재사용하세요. 서버·공급자 최종 실패는 정규화까지 환불하며, 연결 종료는 작업 취소가 아닙니다. 취소 시 이미 수행된 작업분을 정산합니다.
-
-Both engines share job status, cancellation, MP3 and original-text ASS downloads. Check reserved, released, captured and refunded amounts in `billing`. MP3 is 24 kHz mono at 48 kbps. Files are kept for 24 hours; each permits one completed download, and interrupted transfers can be retried. Reuse the same input and idempotency key after a lost response. Final server/provider failures refund synthesis and normalization; disconnecting does not cancel work. Explicit cancellation settles work already performed.
+# Gemini·ChatGPT TTS
+
+기존 APICK 목소리와 자동 전환은 종료되었습니다. `createTtsJob`은 Gemini 기본 목소리 `Kore`를 사용합니다. `getTtsQuality`, `retryTtsJob`, `downloadTtsCandidate`의 기존 경로는 HTTP 409를 반환합니다.
+
+Legacy APICK voices and automatic fallback have retired. `createTtsJob` now defaults to Gemini voice `Kore`. The legacy quality, retry and candidate endpoints return HTTP 409.
+
+```js
+const job = await client.createTtsJob('기온은 오 도입니다.', { voiceId: 'Kore', normalizeText: false, idempotencyKey: 'tts-001' });
+const dialogue = await client.createOpenAiTtsJob({
+  utterances: [{ speaker: '진행', text: '반갑습니다.' }, { speaker: '손님', text: '안녕하세요.' }],
+  speakers: { 진행: { voice_id: 'alloy' }, 손님: { voice_id: 'nova', emotion: 'calm' } },
+  multi_speaker: true, normalize_text: false
+}, { idempotencyKey: 'tts-002' });
+const voices = await client.listGeminiTtsVoices();
+const otherVoices = await client.listOpenAiTtsVoices();
+const options = await client.getTtsOptions();
+const quote = await client.quoteTts({ engine: 'gemini', text: '본문', voice_id: 'Kore' });
+```
+
+`style`, `emotion`, `tone`, `accent`, `pace`(0.5–2), `pitch`(-12–12), `volume_gain_db`(-12–12)는 최상위·화자·발화에 지정할 수 있습니다. `speakers`는 화자 이름별 설정이고 `multi_speaker: true`는 Gemini 최대 2명, ChatGPT 최대 8명입니다. 엔진에 따라 표현 효과가 달라지며 정확한 속도 배율·반음·dB 적용을 보장하지 않습니다. 특히 ChatGPT는 수치의 방향을 낭독 지시로 전달합니다.
+
+Style, emotion, tone, accent, pace, pitch and volume options can be set per request, speaker or utterance. Gemini supports up to two native speakers; ChatGPT supports up to eight speakers across utterances. Numeric acoustic adjustments are not guaranteed: ChatGPT receives directional instructions rather than precise rate, semitone or decibel controls.
+
+정규화는 기본 켜짐이며 추가 스킬 요금이 합산됩니다. `normalize_text: false`(SDK 문자열 호출은 `normalizeText: false`)로 끌 수 있습니다. 정규화 입력은 발화 사이 줄바꿈을 포함해 최대 2,000자, 정규화 없이 최대 8,000자입니다. 견적은 `quoteTts`, 현재 목소리는 엔진별 목록, 옵션은 `getTtsOptions`로 조회합니다.
+
+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 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.
+
+두 엔진은 같은 작업 조회·취소·MP3·원문 ASS 계약을 사용합니다. `billing`의 예약·해제·확정·환불을 확인하세요. MP3는 24kHz 모노 48kbps, 결과는 완료 후 24시간 보관합니다. MP3와 ASS는 각각 완료된 다운로드 1회만 허용하며 전송 중단은 재시도할 수 있습니다. 접수 응답 유실 시 같은 입력과 멱등 키를 재사용하세요. 서버·공급자 최종 실패는 정규화까지 환불하며, 연결 종료는 작업 취소가 아닙니다. 취소 시 이미 수행된 작업분을 정산합니다.
+
+Both engines share job status, cancellation, MP3 and original-text ASS downloads. Check reserved, released, captured and refunded amounts in `billing`. MP3 is 24 kHz mono at 48 kbps. Files are kept for 24 hours; each permits one completed download, and interrupted transfers can be retried. Reuse the same input and idempotency key after a lost response. Final server/provider failures refund synthesis and normalization; disconnecting does not cancel work. Explicit cancellation settles work already performed.

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.0.1",
+  "version": "4.1.0",
   "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 };