apick-api 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# 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(장당 고정가, 크기 무관).
+- 같은 요청도 매번 새로 생성·과금하므로 이미지 `idempotencyKey` 는 더 이상 보내지 않습니다(호환을 위해 받기만 하며 폐기 예정입니다).
+- Add the image `quality` option: `basic` (default) 40 points, `advanced` 350 points, `premium` 1,400 points per image regardless of size.
+- Image `idempotencyKey` is deprecated and no longer sent; every image request is generated and charged as a new request.
+
 # 4.0.0
 
 - Breaking migration: `createTtsJob` now defaults to Gemini `Kore`; retired APICK voices and fallback options are rejected. Use engine-specific voice catalogs instead of legacy `TTS_VOICE_IDS`.
@@ -20,162 +37,162 @@
 
 Adds the Subagent integration and usage-based installed-agent contract. Existing API contracts remain supported.
 
-# Changelog
-
-## 3.9.0 — 2026-10-04
-
-- `getSkillPerformance()`와 공개 성능표 타입을 추가했습니다. 시험 방식·표본 수·평가일·성공률 구간·미검증 상태를 확인할 수 있습니다.
-- Add `getSkillPerformance()` and report types for methods, sample sizes, evaluation dates, success-rate intervals and untested states.
-
-## 3.8.1 — 2026-10-03
-
-- 상품별 조회 안내와 공통 인증 가이드 링크를 보강했습니다. API 계약 변경은 없습니다.
-- Document product-specific data guides and shared authentication; API contracts are unchanged.
-
-## 3.8.0 — 2026-10-03
-
-- 스킬 결과 파일 인증 다운로드와 예상 가격·시간·도구 호출 수 타입 추가.
-- Add authenticated Skill artifact downloads and execution estimate types.
-
-## 3.7.0 — 2026-10-02
-
-- `searchSkills()` 에 `sort` 를 추가했습니다: `recommended`(추천)·`popular`(인기)·`used`(많이 사용)·`likes`(좋아요순)·`rating`(평점순)·`new`(최신)·`mine`(내 계정이 많이 실행한 Skill)·`liked`(내 계정이 좋아요한 Skill). 생략하면 예전처럼 등록 순서입니다. 지원하지 않는 값은 요청 전에 `RangeError` 가 발생합니다. `SKILL_SORTS` 상수와 `SkillSort` 타입을 공개했습니다.
-- Add `sort` to `searchSkills()`: `recommended`, `popular`, `used`, `likes`, `rating`, `new`, `mine` and `liked` (the last two are scoped to the API key's account). Omitting it keeps registration order. Unsupported values throw a `RangeError` before the request is sent. Export `SKILL_SORTS` and the `SkillSort` type.
-- 검색·상세 응답 타입(`SkillSummary`·`SkillDetail`)에 `usage_label`(사용 건수 구간: `1,000회 미만`, `1,000+`, `1만+` …)·`like_count`·`review_count`·`rating_average` 를 추가했습니다. 검색어는 Skill 의 이름·요약·설명과 판매자 이름에서 찾습니다.
-- Add `usage_label` (a usage tier, not an exact count), `like_count`, `review_count` and `rating_average` to the search and detail response types (`SkillSummary`, `SkillDetail`). The search query now matches a Skill's name, summary, description and seller name.
-- 기존 메서드와 요청·응답 형식은 그대로입니다. / Existing methods and request/response formats are unchanged.
-
-## 3.6.2 — 2026-10-02
-
-- `TTS_VOICE_IDS`를 현재 지원하는 14개로 갱신했습니다. 제공이 종료된 `v2_ann_f_30s_01`, `v2_f_teen_01`을 상수·타입·문서에서 제거했으며, 이 값을 `voiceId`로 넘기면 요청 전에 `RangeError`가 발생합니다.
-- Update `TTS_VOICE_IDS` to the 14 currently supported voices. The retired `v2_ann_f_30s_01` and `v2_f_teen_01` are removed from the constant, types and docs; passing them as `voiceId` now throws a `RangeError` before the request is sent.
-- TTS 요금이 100자당 10포인트에서 "100자까지 30포인트, 이후 100자당 10포인트"로 바뀌었습니다(100자 30P, 101자 40P, 800자 100P). 한국어 읽기 자동 변환이 이 요금에 포함되며, 과금 기준은 계속 보낸 원문의 글자 수입니다.
-- TTS pricing changed from 10 points per 100 characters to 30 points for up to 100 characters plus 10 points for each additional 100 characters (100 chars 30P, 101 chars 40P, 800 chars 100P). Automatic Korean reading conversion is included, and billing is still based on the character count of the text you send.
-- 모든 TTS 요청에 한국어 읽기 전처리가 자동 적용되어 추가 옵션이나 별도 Skill 호출이 필요하지 않음을 README와 한국어·영어 가이드에 명시했습니다. 원문 기준 요금과 ASS 자막 표기는 유지되며, 정규화에 실패하면 원문으로 합성합니다. 공개 메서드와 요청·응답 형식은 변경하지 않았습니다.
-- Clarify in the README and Korean/English guides that every TTS request automatically applies Korean reading normalization, with no extra option or separate Skill call. Billing and ASS subtitle spelling remain based on the original text; failed normalization falls back to synthesis from that text. No public method or request/response format changes.
-
-## 3.6.1 — 2026-10-02
-
-- `createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문 약어를 문맥에 맞는 한글 읽기로 자동 변환해 합성한다는 안내를 README와 한국어·영어 가이드에 추가했습니다. 과금 글자 수와 요금은 보낸 원문 기준이고 요청·응답 형식은 그대로이며, ASS 자막은 보낸 원문 표기로 제공됩니다. 문서만 바뀌었습니다.
-- Document in the README and Korean/English guides that text passed to `createTtsJob()` has its numbers, units, symbols and English abbreviations automatically converted into context-appropriate Korean readings before synthesis. Billing is based on the text you send, request and response formats are unchanged, and ASS subtitles keep the text as you sent it. Documentation only.
-
-## 3.6.0 — 2026-10-02
-
-- Skills 메서드 8종을 추가했습니다: `searchSkills()`, `getSkill()`, `quoteSkill()`, `runSkill()`, `getSkillRun()`, `getSkillRunResult()`, `cancelSkillRun()`, `skillUsage()`. 요청·응답이 JSON 이며 응답은 봉투 없이 `data` 에 담깁니다.
-- Add eight Skills methods to search, inspect, quote, run, read, fetch the result of, cancel and list Skill runs. Requests and responses are JSON; responses are returned as-is in `data`.
-- `runSkill()` 은 `idempotencyKey` 가 필수이며 `Idempotency-Key` 헤더로 보냅니다. 결과가 약속한 형식으로 반환된 실행만 차감됩니다.
-- 생성형 AI 를 쓰는 Skill 은 실행마다 실제 사용량만큼 금액이 달라집니다. `quoteSkill()` 이 예상 금액(`estimated_points`)과 최대 금액(`max_points`)을 돌려주며, `maxCostPoints` 에는 `max_points` 를 넘기세요.
-- For Skills that use generative AI the charge varies per run with actual usage. `quoteSkill()` returns `estimated_points` and `max_points`; pass `max_points` as `maxCostPoints`.
-- `runSkill()` requires `idempotencyKey`, sent as the `Idempotency-Key` header. Only runs that return a result in the promised format are charged.
-- `ApickApiError` 에 선택적 `details` 를 추가했습니다. Skills 오류 코드는 `serviceCode` 로 전달됩니다. `SKILL_CATEGORIES` 상수와 Skills 타입(`SkillSummary`, `SkillDetail`, `SkillQuote`, `SkillRun` 등)을 공개했습니다.
-- Add optional `details` to `ApickApiError`; Skills error codes are surfaced through `serviceCode`. Export `SKILL_CATEGORIES` and the Skills types.
-
-## 3.5.0 — 2026-09-30
-
-- 간편인증 조회 상품 2종을 추가했습니다. `requestCashReceiptDeduction()`/`getCashReceiptDeduction()`은 현금영수증 소득공제 내역을 `incomeYears`(1~3)로, `requestTaxReturnHistory()`/`getTaxReturnHistory()`는 국세 신고내역을 `years`(1~10)로 조회합니다.
-- Add two simple-auth data products: cash receipt income deductions (`incomeYears` 1-3) and national tax return history (`years` 1-10), each with a `request*()`/`get*()` pair and result payload types.
-- 유튜브 공개 영상 API 4종을 추가했습니다: `youtubeMetadata()`, `youtubeThumbnail()`(JPG), `youtubeSubtitleList()`, `youtubeSubtitle()`(VTT·SRT·TXT).
-- Add four public YouTube video methods: metadata, thumbnail (JPG), subtitle language list, and subtitle download (VTT/SRT/TXT).
-
-## 3.4.1 — 2026-09-28
-
-- README와 한국어·영어 가이드의 간편인증 5종 예제에 모든 진행 상태와 `resultAvailable` 종료 기준을 적용했습니다. 전체·부분 성공, 인증 거부·만료·실패와 `RESULT_EXPIRED`를 구분합니다.
-- Align all five simple-auth polling examples in the README and Korean/English guides with every progress state and the `resultAvailable` completion criterion. Distinguish full/partial success, rejected/expired authentication, failure, and `RESULT_EXPIRED`.
-- 순차 폴링 간격을 5→10→20→30초로 늘린 뒤 30초를 유지하며, 인증·전체 대기시간 제한과 자동 재접수 방지를 안내합니다. 문서 코드를 직접 실행하는 회귀 테스트를 추가했습니다.
-- Document sequential polling at 5→10→20→30 seconds, capped at 30 seconds, with authentication/overall waiting limits and no automatic resubmission. Add regression tests that execute the documentation examples.
-
-## 3.4.0 — 2026-09-27
-
-- 간편인증 기반 조회 상품 5종(재직·보험료 확인, 금융소득 조회, 국민연금 가입내역, 운전면허 조회, 국가 건강검진 결과)을 추가했습니다. 각 상품은 `request*()`로 본인 간편인증을 접수하고 `get*()`로 상태·결과를 폴링합니다.
-- Add five simple-auth-based data lookup products (employment/insurance premium check, financial income, National Pension join history, driver's license, national health checkup). Each product accepts a `request*()` call for identity verification and polls status/result with `get*()`.
-- `AUTH_PROVIDERS`(13종 간편인증 수단)와 `AuthProvider`, `DataRequestAcceptedData`, `DataRequestResult<T>` 타입, 상품별 결과 타입(`EmploymentResultPayload` 등)을 공개했습니다.
-- Export `AUTH_PROVIDERS` (13 supported simple-auth providers), the `AuthProvider` type, `DataRequestAcceptedData`/`DataRequestResult<T>` envelopes, and per-product result payload types (e.g. `EmploymentResultPayload`).
-- 재조회 만료(`RESULT_EXPIRED`)·인증 만료·거절·수집 실패는 `data.errorCode`로 구분됩니다.
-- `RESULT_EXPIRED`, `AUTH_EXPIRED`, `AUTH_REJECTED`, and `COLLECT_FAILED` are surfaced through `data.errorCode`.
-
-## 3.3.0 — 2026-09-21
-
-- 모든 REST 요청의 인증 헤더를 `CL_AUTH_KEY` 에서 표준 `Authorization: Bearer <API 키>` 로 전환했습니다. 서버가 전환 기간 동안 두 헤더를 모두 받으므로 기존 호출도 계속 동작합니다.
-- Send REST requests with the standard `Authorization: Bearer <API key>` header instead of `CL_AUTH_KEY`. Both headers are accepted during the migration window.
-- Mask bearer tokens in error output alongside the legacy header.
-- Synchronize all 16 current TTS voice IDs and masking type 4 with the public REST contract.
-
-- Send all REST request bodies as multipart/form-data, including flattened nested arrays and objects. Keep existing method signatures and JSON/file responses.
-- REST 요청을 multipart/form-data로 통일하고 중첩 입력·파일·불리언의 호환 테스트를 추가했습니다. 기존 메서드와 응답 타입은 유지합니다.
-- Document OpenAPI/Postman downloads and compatibility with older JSON callers.
-
-## 3.2.0 — 2026-09-14
-
-- Seedance 참조 영상 작업에 `referenceAudios`(MP3·WAV) 입력을 추가했습니다.
-- Add video generation version selection documentation and compatibility tests.
-- 영상 생성 버전 선택, 버전별 옵션·요금 안내와 호환 검증을 추가했습니다.
-- Add createVideoJob, getVideoJob, downloadVideoResult and public TypeScript types.
-- Document and verify Seedance 2.0 Fast and Mini tier pass-through.
-
-## 3.1.0 - 2026-09-08
-
-- TTS 발화별 검수 이력, 후보 WAV 조회, 멱등 키를 사용하는 같은 작업 재개 메서드를 추가했습니다.
-- Added TTS quality history, candidate WAV downloads, and idempotent job recovery methods.
-
-## 3.0.0 - 2026-09-05
-
-- 이미지 프롬프트 허용 길이를 최대 28,000자로 확대했습니다.
-- 작업 접수 시 전체 포인트를 먼저 차감하고 실패한 이미지의 포인트를 즉시 환급하는 계약을 반영했습니다.
-- 접수된 이미지 작업은 취소할 수 없도록 `cancelImageJob` 메서드와 `cancelled` 상태를 제거했습니다.
-
-## 2.4.0 - 2026-09-05
-
-- 이미지 장수 옵션을 의미가 분명한 `imageCount`로 바꾸고 압축 조정 옵션을 제거했습니다.
-- 이미지 크기를 5개 표준 크기 중에서만 선택하도록 타입과 런타임 검증을 강화했습니다.
-- 생성 요청에 선택적 `referenceImage`를 더해 참고 이미지와 텍스트를 함께 사용할 수 있습니다.
-
-## 2.3.1 - 2026-09-05
-
-- 이미지 편집 입력에서 마스크 파일을 제거하고 원본 이미지와 프롬프트만 받도록 계약을 단순화했습니다.
-
-## 2.3.0 - 2026-09-05
-
-- 이미지 생성·편집과 최대 50장 비동기 작업 메서드 8종을 추가했습니다.
-- 이미지당 25포인트, 성공분 과금, 멱등 키, 24시간 결과 보관 계약을 문서화했습니다.
-
-## 2.2.0 - 2026-09-03
-
-- `maskResidenceCard()`의 개인정보 마스킹 대상을 외국인등록증·영주증·외국국적동포 국내거소신고증으로 확대했습니다.
-- 요청·응답 형식과 `document_type: residence_card` 계약은 유지합니다.
-- 진위확인 API의 지원 범위는 기존 외국인등록증으로 유지됩니다.
-
-## 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 계약에 종료 대상 이미지 생성 기능이 포함되지 않았음을 재검증했습니다.
-- 기능 및 메서드 호환성 변경 없이 릴리스 메타데이터를 갱신했습니다.
-
-## 1.1.0 - 2026-08-29
-
-- 주민등록번호, 외국인등록증, 여권, 주민등록증, 운전면허증 마스킹 메서드 5종을 추가했습니다.
-- 신분증 처리 오류 코드를 `ApickApiError.serviceCode`로 제공합니다.
-
-## 1.0.0
-
-- Initial public release.
-- Added 20 focused APICK service methods.
-- Added JSON, multipart image upload, and binary file response support.
-- Added ESM, CommonJS, and TypeScript declarations.
+# Changelog
+
+## 3.9.0 — 2026-10-04
+
+- `getSkillPerformance()`와 공개 성능표 타입을 추가했습니다. 시험 방식·표본 수·평가일·성공률 구간·미검증 상태를 확인할 수 있습니다.
+- Add `getSkillPerformance()` and report types for methods, sample sizes, evaluation dates, success-rate intervals and untested states.
+
+## 3.8.1 — 2026-10-03
+
+- 상품별 조회 안내와 공통 인증 가이드 링크를 보강했습니다. API 계약 변경은 없습니다.
+- Document product-specific data guides and shared authentication; API contracts are unchanged.
+
+## 3.8.0 — 2026-10-03
+
+- 스킬 결과 파일 인증 다운로드와 예상 가격·시간·도구 호출 수 타입 추가.
+- Add authenticated Skill artifact downloads and execution estimate types.
+
+## 3.7.0 — 2026-10-02
+
+- `searchSkills()` 에 `sort` 를 추가했습니다: `recommended`(추천)·`popular`(인기)·`used`(많이 사용)·`likes`(좋아요순)·`rating`(평점순)·`new`(최신)·`mine`(내 계정이 많이 실행한 Skill)·`liked`(내 계정이 좋아요한 Skill). 생략하면 예전처럼 등록 순서입니다. 지원하지 않는 값은 요청 전에 `RangeError` 가 발생합니다. `SKILL_SORTS` 상수와 `SkillSort` 타입을 공개했습니다.
+- Add `sort` to `searchSkills()`: `recommended`, `popular`, `used`, `likes`, `rating`, `new`, `mine` and `liked` (the last two are scoped to the API key's account). Omitting it keeps registration order. Unsupported values throw a `RangeError` before the request is sent. Export `SKILL_SORTS` and the `SkillSort` type.
+- 검색·상세 응답 타입(`SkillSummary`·`SkillDetail`)에 `usage_label`(사용 건수 구간: `1,000회 미만`, `1,000+`, `1만+` …)·`like_count`·`review_count`·`rating_average` 를 추가했습니다. 검색어는 Skill 의 이름·요약·설명과 판매자 이름에서 찾습니다.
+- Add `usage_label` (a usage tier, not an exact count), `like_count`, `review_count` and `rating_average` to the search and detail response types (`SkillSummary`, `SkillDetail`). The search query now matches a Skill's name, summary, description and seller name.
+- 기존 메서드와 요청·응답 형식은 그대로입니다. / Existing methods and request/response formats are unchanged.
+
+## 3.6.2 — 2026-10-02
+
+- `TTS_VOICE_IDS`를 현재 지원하는 14개로 갱신했습니다. 제공이 종료된 `v2_ann_f_30s_01`, `v2_f_teen_01`을 상수·타입·문서에서 제거했으며, 이 값을 `voiceId`로 넘기면 요청 전에 `RangeError`가 발생합니다.
+- Update `TTS_VOICE_IDS` to the 14 currently supported voices. The retired `v2_ann_f_30s_01` and `v2_f_teen_01` are removed from the constant, types and docs; passing them as `voiceId` now throws a `RangeError` before the request is sent.
+- TTS 요금이 100자당 10포인트에서 "100자까지 30포인트, 이후 100자당 10포인트"로 바뀌었습니다(100자 30P, 101자 40P, 800자 100P). 한국어 읽기 자동 변환이 이 요금에 포함되며, 과금 기준은 계속 보낸 원문의 글자 수입니다.
+- TTS pricing changed from 10 points per 100 characters to 30 points for up to 100 characters plus 10 points for each additional 100 characters (100 chars 30P, 101 chars 40P, 800 chars 100P). Automatic Korean reading conversion is included, and billing is still based on the character count of the text you send.
+- 모든 TTS 요청에 한국어 읽기 전처리가 자동 적용되어 추가 옵션이나 별도 Skill 호출이 필요하지 않음을 README와 한국어·영어 가이드에 명시했습니다. 원문 기준 요금과 ASS 자막 표기는 유지되며, 정규화에 실패하면 원문으로 합성합니다. 공개 메서드와 요청·응답 형식은 변경하지 않았습니다.
+- Clarify in the README and Korean/English guides that every TTS request automatically applies Korean reading normalization, with no extra option or separate Skill call. Billing and ASS subtitle spelling remain based on the original text; failed normalization falls back to synthesis from that text. No public method or request/response format changes.
+
+## 3.6.1 — 2026-10-02
+
+- `createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문 약어를 문맥에 맞는 한글 읽기로 자동 변환해 합성한다는 안내를 README와 한국어·영어 가이드에 추가했습니다. 과금 글자 수와 요금은 보낸 원문 기준이고 요청·응답 형식은 그대로이며, ASS 자막은 보낸 원문 표기로 제공됩니다. 문서만 바뀌었습니다.
+- Document in the README and Korean/English guides that text passed to `createTtsJob()` has its numbers, units, symbols and English abbreviations automatically converted into context-appropriate Korean readings before synthesis. Billing is based on the text you send, request and response formats are unchanged, and ASS subtitles keep the text as you sent it. Documentation only.
+
+## 3.6.0 — 2026-10-02
+
+- Skills 메서드 8종을 추가했습니다: `searchSkills()`, `getSkill()`, `quoteSkill()`, `runSkill()`, `getSkillRun()`, `getSkillRunResult()`, `cancelSkillRun()`, `skillUsage()`. 요청·응답이 JSON 이며 응답은 봉투 없이 `data` 에 담깁니다.
+- Add eight Skills methods to search, inspect, quote, run, read, fetch the result of, cancel and list Skill runs. Requests and responses are JSON; responses are returned as-is in `data`.
+- `runSkill()` 은 `idempotencyKey` 가 필수이며 `Idempotency-Key` 헤더로 보냅니다. 결과가 약속한 형식으로 반환된 실행만 차감됩니다.
+- 생성형 AI 를 쓰는 Skill 은 실행마다 실제 사용량만큼 금액이 달라집니다. `quoteSkill()` 이 예상 금액(`estimated_points`)과 최대 금액(`max_points`)을 돌려주며, `maxCostPoints` 에는 `max_points` 를 넘기세요.
+- For Skills that use generative AI the charge varies per run with actual usage. `quoteSkill()` returns `estimated_points` and `max_points`; pass `max_points` as `maxCostPoints`.
+- `runSkill()` requires `idempotencyKey`, sent as the `Idempotency-Key` header. Only runs that return a result in the promised format are charged.
+- `ApickApiError` 에 선택적 `details` 를 추가했습니다. Skills 오류 코드는 `serviceCode` 로 전달됩니다. `SKILL_CATEGORIES` 상수와 Skills 타입(`SkillSummary`, `SkillDetail`, `SkillQuote`, `SkillRun` 등)을 공개했습니다.
+- Add optional `details` to `ApickApiError`; Skills error codes are surfaced through `serviceCode`. Export `SKILL_CATEGORIES` and the Skills types.
+
+## 3.5.0 — 2026-09-30
+
+- 간편인증 조회 상품 2종을 추가했습니다. `requestCashReceiptDeduction()`/`getCashReceiptDeduction()`은 현금영수증 소득공제 내역을 `incomeYears`(1~3)로, `requestTaxReturnHistory()`/`getTaxReturnHistory()`는 국세 신고내역을 `years`(1~10)로 조회합니다.
+- Add two simple-auth data products: cash receipt income deductions (`incomeYears` 1-3) and national tax return history (`years` 1-10), each with a `request*()`/`get*()` pair and result payload types.
+- 유튜브 공개 영상 API 4종을 추가했습니다: `youtubeMetadata()`, `youtubeThumbnail()`(JPG), `youtubeSubtitleList()`, `youtubeSubtitle()`(VTT·SRT·TXT).
+- Add four public YouTube video methods: metadata, thumbnail (JPG), subtitle language list, and subtitle download (VTT/SRT/TXT).
+
+## 3.4.1 — 2026-09-28
+
+- README와 한국어·영어 가이드의 간편인증 5종 예제에 모든 진행 상태와 `resultAvailable` 종료 기준을 적용했습니다. 전체·부분 성공, 인증 거부·만료·실패와 `RESULT_EXPIRED`를 구분합니다.
+- Align all five simple-auth polling examples in the README and Korean/English guides with every progress state and the `resultAvailable` completion criterion. Distinguish full/partial success, rejected/expired authentication, failure, and `RESULT_EXPIRED`.
+- 순차 폴링 간격을 5→10→20→30초로 늘린 뒤 30초를 유지하며, 인증·전체 대기시간 제한과 자동 재접수 방지를 안내합니다. 문서 코드를 직접 실행하는 회귀 테스트를 추가했습니다.
+- Document sequential polling at 5→10→20→30 seconds, capped at 30 seconds, with authentication/overall waiting limits and no automatic resubmission. Add regression tests that execute the documentation examples.
+
+## 3.4.0 — 2026-09-27
+
+- 간편인증 기반 조회 상품 5종(재직·보험료 확인, 금융소득 조회, 국민연금 가입내역, 운전면허 조회, 국가 건강검진 결과)을 추가했습니다. 각 상품은 `request*()`로 본인 간편인증을 접수하고 `get*()`로 상태·결과를 폴링합니다.
+- Add five simple-auth-based data lookup products (employment/insurance premium check, financial income, National Pension join history, driver's license, national health checkup). Each product accepts a `request*()` call for identity verification and polls status/result with `get*()`.
+- `AUTH_PROVIDERS`(13종 간편인증 수단)와 `AuthProvider`, `DataRequestAcceptedData`, `DataRequestResult<T>` 타입, 상품별 결과 타입(`EmploymentResultPayload` 등)을 공개했습니다.
+- Export `AUTH_PROVIDERS` (13 supported simple-auth providers), the `AuthProvider` type, `DataRequestAcceptedData`/`DataRequestResult<T>` envelopes, and per-product result payload types (e.g. `EmploymentResultPayload`).
+- 재조회 만료(`RESULT_EXPIRED`)·인증 만료·거절·수집 실패는 `data.errorCode`로 구분됩니다.
+- `RESULT_EXPIRED`, `AUTH_EXPIRED`, `AUTH_REJECTED`, and `COLLECT_FAILED` are surfaced through `data.errorCode`.
+
+## 3.3.0 — 2026-09-21
+
+- 모든 REST 요청의 인증 헤더를 `CL_AUTH_KEY` 에서 표준 `Authorization: Bearer <API 키>` 로 전환했습니다. 서버가 전환 기간 동안 두 헤더를 모두 받으므로 기존 호출도 계속 동작합니다.
+- Send REST requests with the standard `Authorization: Bearer <API key>` header instead of `CL_AUTH_KEY`. Both headers are accepted during the migration window.
+- Mask bearer tokens in error output alongside the legacy header.
+- Synchronize all 16 current TTS voice IDs and masking type 4 with the public REST contract.
+
+- Send all REST request bodies as multipart/form-data, including flattened nested arrays and objects. Keep existing method signatures and JSON/file responses.
+- REST 요청을 multipart/form-data로 통일하고 중첩 입력·파일·불리언의 호환 테스트를 추가했습니다. 기존 메서드와 응답 타입은 유지합니다.
+- Document OpenAPI/Postman downloads and compatibility with older JSON callers.
+
+## 3.2.0 — 2026-09-14
+
+- Seedance 참조 영상 작업에 `referenceAudios`(MP3·WAV) 입력을 추가했습니다.
+- Add video generation version selection documentation and compatibility tests.
+- 영상 생성 버전 선택, 버전별 옵션·요금 안내와 호환 검증을 추가했습니다.
+- Add createVideoJob, getVideoJob, downloadVideoResult and public TypeScript types.
+- Document and verify Seedance 2.0 Fast and Mini tier pass-through.
+
+## 3.1.0 - 2026-09-08
+
+- TTS 발화별 검수 이력, 후보 WAV 조회, 멱등 키를 사용하는 같은 작업 재개 메서드를 추가했습니다.
+- Added TTS quality history, candidate WAV downloads, and idempotent job recovery methods.
+
+## 3.0.0 - 2026-09-05
+
+- 이미지 프롬프트 허용 길이를 최대 28,000자로 확대했습니다.
+- 작업 접수 시 전체 포인트를 먼저 차감하고 실패한 이미지의 포인트를 즉시 환급하는 계약을 반영했습니다.
+- 접수된 이미지 작업은 취소할 수 없도록 `cancelImageJob` 메서드와 `cancelled` 상태를 제거했습니다.
+
+## 2.4.0 - 2026-09-05
+
+- 이미지 장수 옵션을 의미가 분명한 `imageCount`로 바꾸고 압축 조정 옵션을 제거했습니다.
+- 이미지 크기를 5개 표준 크기 중에서만 선택하도록 타입과 런타임 검증을 강화했습니다.
+- 생성 요청에 선택적 `referenceImage`를 더해 참고 이미지와 텍스트를 함께 사용할 수 있습니다.
+
+## 2.3.1 - 2026-09-05
+
+- 이미지 편집 입력에서 마스크 파일을 제거하고 원본 이미지와 프롬프트만 받도록 계약을 단순화했습니다.
+
+## 2.3.0 - 2026-09-05
+
+- 이미지 생성·편집과 최대 50장 비동기 작업 메서드 8종을 추가했습니다.
+- 이미지당 25포인트, 성공분 과금, 멱등 키, 24시간 결과 보관 계약을 문서화했습니다.
+
+## 2.2.0 - 2026-09-03
+
+- `maskResidenceCard()`의 개인정보 마스킹 대상을 외국인등록증·영주증·외국국적동포 국내거소신고증으로 확대했습니다.
+- 요청·응답 형식과 `document_type: residence_card` 계약은 유지합니다.
+- 진위확인 API의 지원 범위는 기존 외국인등록증으로 유지됩니다.
+
+## 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 계약에 종료 대상 이미지 생성 기능이 포함되지 않았음을 재검증했습니다.
+- 기능 및 메서드 호환성 변경 없이 릴리스 메타데이터를 갱신했습니다.
+
+## 1.1.0 - 2026-08-29
+
+- 주민등록번호, 외국인등록증, 여권, 주민등록증, 운전면허증 마스킹 메서드 5종을 추가했습니다.
+- 신분증 처리 오류 코드를 `ApickApiError.serviceCode`로 제공합니다.
+
+## 1.0.0
+
+- Initial public release.
+- Added 20 focused APICK service methods.
+- Added JSON, multipart image upload, and binary file response support.
+- Added ESM, CommonJS, and TypeScript declarations.

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 |
@@ -164,14 +179,13 @@ console.log(result.meta);
 
 ## 이미지 생성·편집 / Image generation and editing
 
-이미지는 장당 25포인트이며 동기는 1~4장, 작업형 API는 최대 50장까지 지원합니다. 요청이 접수되면 전체 금액을 먼저 차감하고, 생성에 실패한 이미지가 있으면 해당 장수만큼 즉시 환급합니다. 접수된 작업은 취소할 수 없으며 결과는 완료 후 24시간 동안 반복 다운로드할 수 있습니다.
+품질(`quality`)별 장당 고정가입니다. `basic`(기본) 40P, `advanced`(고급) 350P, `premium`(최고급) 1,400P이며 크기와 관계없이 같습니다. 같은 요청을 다시 보내도 결과를 재사용하지 않고 매번 새로 생성·과금합니다. 동기는 1~4장, 작업형 API는 최대 50장까지 지원합니다. 요청이 접수되면 전체 금액을 먼저 차감하고, 생성에 실패한 이미지가 있으면 해당 장수만큼 즉시 환급합니다. 접수된 작업은 취소할 수 없으며 결과는 완료 후 24시간 동안 반복 다운로드할 수 있습니다.
 
-Images cost 25 points each. Synchronous calls support 1–4 images and job calls support up to 50. The full amount is deducted when a request is accepted, and failed images are refunded immediately. Accepted jobs cannot be cancelled. Completed results remain downloadable for 24 hours.
+Images use a fixed per-image price by `quality`: `basic` (default) 40 points, `advanced` 350 points and `premium` 1,400 points, regardless of size. Repeated requests are never reused; each request is generated and charged again. Synchronous calls support 1–4 images and job calls support up to 50. The full amount is deducted when a request is accepted, and failed images are refunded immediately. Accepted jobs cannot be cancelled. Completed results remain downloadable for 24 hours.
 
 ```js
 const made = await apick.generateImages("따뜻한 조명의 미니멀 제품 사진", {
-  imageCount: 2, size: "1024x1024", outputFormat: "webp",
-  idempotencyKey: "catalog-cover-20260905"
+  imageCount: 2, size: "1024x1024", outputFormat: "webp", quality: "advanced"
 });
 
 const referenced = await apick.generateImages("구도와 제품 형태는 유지하고 여름 해변 분위기로", {

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);
@@ -145,12 +168,11 @@ Text input is limited to 100,000 characters.
 
 ## Image AI
 
-Under usage billing, external AI costs use confirmed vendor cost × the applicable exchange rate × 1.4. If generation/editing usage cannot be confirmed, HTTP 202 returns `job_id` and `billing_status: "pending"`. The generated output is retained: poll `getImageJob(job_id)` without submitting another generation, then use the existing download methods after settlement.
+Images use a fixed per-image price by `quality`: `basic` (default) 40 points, `advanced` 350 points and `premium` 1,400 points, regardless of size. Repeated requests are never reused; each request is generated and charged again. The total is deducted when a request is accepted and failed images are refunded. If a job accepted under the previous pricing returns a settlement-pending response (HTTP 202, `billing_status: "pending"`), poll `getImageJob(job_id)`.
 
 ```js
 const result = await client.generateImages('A clean product photo on white', {
-  imageCount: 4, size: '1024x1024', outputFormat: 'webp',
-  idempotencyKey: 'product-draft-001'
+  imageCount: 4, size: '1024x1024', outputFormat: 'webp', quality: 'advanced'
 });
 
 const referenceResult = await client.generateImages('Keep the product shape and composition, and change the background to a sunny kitchen', {

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);
@@ -145,14 +168,14 @@ const polished = await client.polish(draftText);
 
 ## 이미지 AI
 
-새 사용량 요금이 적용되면 외부 AI 판매가는 확인된 원가 × 적용 환율 × 1.4입니다. 생성·편집 응답에서 사용량이 미확정이면 HTTP 202와 `job_id`, `billing_status: "pending"`을 반환합니다. 이미 받은 결과는 보관하므로 재생성하지 말고 `getImageJob(job_id)`로 조회합니다. 정산 완료 후 기존 다운로드 메서드를 사용합니다.
+품질(`quality`)별 장당 고정가입니다. `basic`(기본) 40P, `advanced`(고급) 350P, `premium`(최고급) 1,400P이며 크기와 관계없이 같습니다. 같은 요청을 다시 보내도 결과를 재사용하지 않고 매번 새로 생성·과금합니다. 접수 시 장수만큼 먼저 차감하고 실패한 장은 환급합니다. 이전 요금 정책으로 접수된 작업이 정산 보류(HTTP 202, `billing_status: "pending"`)로 응답하면 `getImageJob(job_id)`로 조회합니다.
 
 ```js
 const result = await client.generateImages('흰 배경의 제품 사진', {
   imageCount: 4,
   size: '1024x1024',
   outputFormat: 'webp',
-  idempotencyKey: 'product-draft-001'
+  quality: 'advanced'
 });
 
 const referenceResult = await client.generateImages('제품 모양과 구도는 유지하고 배경을 햇살 좋은 주방으로 변경', {

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/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);