apick-api 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 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 +27,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/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

@@ -164,14 +164,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/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

@@ -145,12 +145,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

@@ -145,14 +145,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "4.0.0",
+  "version": "4.0.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/index.cjs

@@ -6,6 +6,8 @@ const MAX_OCR_BYTES = 50 * 1024 * 1024;
 const MAX_IMAGE_AI_BYTES = 50 * 1024 * 1024;
 const IMAGE_AI_SIZES = Object.freeze(['1024x1024', '1536x1024', '1024x1536', '1152x864', '864x1152']);
 const IMAGE_AI_SIZE_SET = new Set(IMAGE_AI_SIZES);
+// 품질별 장당 고정가: basic 40P(기본) · advanced 350P · premium 1,400P
+const IMAGE_AI_QUALITIES = Object.freeze(['basic', 'advanced', 'premium']);
 const TTS_VOICE_IDS = Object.freeze([
 	'v2_ann_m_30s_01', 'v2_ann_m_30s_02', 'v2_ann_m_30s_04', 'v2_ann_m_30s_05', '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_young_01', 'v2_f_senior_01'
 ]);
@@ -63,8 +65,8 @@ const SERVICES = Object.freeze(Object.fromEntries(
 	])
 ));
 
-function normalizeSubagentId(value,prefix){if(typeof value!=='string'||!new RegExp('^'+prefix+'_[a-f0-9]{32}$').test(value))throw new TypeError('Invalid subagent identifier.');return value;}
-function redact(value, apiKey) {
+function normalizeSubagentId(value,prefix){if(typeof value!=='string'||!new RegExp('^'+prefix+'_[a-f0-9]{32}$').test(value))throw new TypeError('Invalid subagent identifier.');return value;}
+function redact(value, apiKey) {
 	let text = String(value || '');
 	if (apiKey) text = text.split(apiKey).join('***');
 	return text.replace(/(Authorization\s*:\s*Bearer\s*)\S+/gi, '$1***').replace(/(CL_AUTH_KEY\s*[:=]\s*)\S+/gi, '$1***');
@@ -118,9 +120,9 @@ function normalizeTtsJobId(value) {
 	return jobId;
 }
 
-function normalizeTtsVoice(value) {
-	const voiceId = requiredString('voiceId', value, 160);
-	if (TTS_VOICE_ID_SET.has(voiceId)) throw new RangeError('This voiceId has retired. Select a current Gemini voice with listGeminiTtsVoices().');
+function normalizeTtsVoice(value) {
+	const voiceId = requiredString('voiceId', value, 160);
+	if (TTS_VOICE_ID_SET.has(voiceId)) throw new RangeError('This voiceId has retired. Select a current Gemini voice with listGeminiTtsVoices().');
 	return voiceId;
 }
 
@@ -379,17 +381,17 @@ class ApickClient {
 			Accept: definition.output === 'binary' ? '*/*' : 'application/json',
 			Authorization: `Bearer ${this.#apiKey}`
 		};
-		const method = definition.method || 'POST';
-		if (definition.idempotencyKey) headers['X-Idempotency-Key'] = requiredString('idempotencyKey', definition.idempotencyKey, 128);
+		const method = definition.method || 'POST';
+		if (definition.idempotencyKey) headers['X-Idempotency-Key'] = requiredString('idempotencyKey', definition.idempotencyKey, 128);
 		const request = {
 			method,
 			headers,
 			signal: controller.signal,
 			redirect: 'error'
 		};
-		if (method !== 'GET') {
-			if (definition.json) { headers['Content-Type']='application/json'; request.body=JSON.stringify(payload||{}); }
-			else request.body = formData || require('./form.cjs').createForm(payload || {}, definition.endpoint);
+		if (method !== 'GET') {
+			if (definition.json) { headers['Content-Type']='application/json'; request.body=JSON.stringify(payload||{}); }
+			else request.body = formData || require('./form.cjs').createForm(payload || {}, definition.endpoint);
 		}
 
 		let response;
@@ -630,31 +632,31 @@ class ApickClient {
 		return this._call('createVideoJob', null, null, { endpoint:'/rest/'+model+'/jobs/'+jobId+'/result', method:'GET', output:'binary', filename:jobId+'.mp4', timeoutMs:60_000 });
 	}
 
-	createTtsJob(text, options) {
-		const config = options || {};
-		const payload = typeof text==='object' && text!==null ? {...text} : {
-			voice_id: normalizeTtsVoice(config.voiceId || 'Kore'),
-			text: requiredString('text', text, config.normalizeText === false ? 8000 : 2000)
-		};
-		if(config.normalizeText!==undefined)payload.normalize_text=config.normalizeText;
-		if(config.fallbackPolicy!==undefined||config.fallbackOptions!==undefined||payload.fallback_policy!==undefined||payload.fallback_options!==undefined)throw new TypeError('TTS fallback has retired. Use createGeminiTtsJob or createOpenAiTtsJob.');
-		if(payload.normalize_text!==undefined&&typeof payload.normalize_text!=='boolean')throw new TypeError('normalizeText must be boolean.');
-		if(payload.voice_id!==undefined)normalizeTtsVoice(payload.voice_id);
-		return this._call('createTtsJob',payload,null,{json:true,idempotencyKey:config.idempotencyKey});
-	}
-
-	createGeminiTtsJob(input, options) {
-		if(!input||typeof input!=='object'||Array.isArray(input))throw new TypeError('Gemini TTS input is required.');
-		return this._call('createTtsJob', input, null, {endpoint:'/rest/tts/gemini/jobs',json:true,idempotencyKey:options?.idempotencyKey});
-	}
-	listGeminiTtsVoices() { return this._call('createTtsJob',null,null,{endpoint:'/rest/tts/gemini/voices',method:'GET'}); }
-	createOpenAiTtsJob(input, options) {
-		if(!input||typeof input!=='object'||Array.isArray(input))throw new TypeError('OpenAI TTS input is required.');
-		return this._call('createTtsJob',input,null,{endpoint:'/rest/tts/openai/jobs',json:true,idempotencyKey:options?.idempotencyKey});
-	}
-	listOpenAiTtsVoices() { return this._call('createTtsJob',null,null,{endpoint:'/rest/tts/openai/voices',method:'GET'}); }
-	getTtsOptions() { return this._call('createTtsJob',null,null,{endpoint:'/rest/tts/options',method:'GET'}); }
-	quoteTts(input) { return this._call('createTtsJob',input,null,{endpoint:'/rest/tts/quote',json:true}); }
+	createTtsJob(text, options) {
+		const config = options || {};
+		const payload = typeof text==='object' && text!==null ? {...text} : {
+			voice_id: normalizeTtsVoice(config.voiceId || 'Kore'),
+			text: requiredString('text', text, config.normalizeText === false ? 8000 : 2000)
+		};
+		if(config.normalizeText!==undefined)payload.normalize_text=config.normalizeText;
+		if(config.fallbackPolicy!==undefined||config.fallbackOptions!==undefined||payload.fallback_policy!==undefined||payload.fallback_options!==undefined)throw new TypeError('TTS fallback has retired. Use createGeminiTtsJob or createOpenAiTtsJob.');
+		if(payload.normalize_text!==undefined&&typeof payload.normalize_text!=='boolean')throw new TypeError('normalizeText must be boolean.');
+		if(payload.voice_id!==undefined)normalizeTtsVoice(payload.voice_id);
+		return this._call('createTtsJob',payload,null,{json:true,idempotencyKey:config.idempotencyKey});
+	}
+
+	createGeminiTtsJob(input, options) {
+		if(!input||typeof input!=='object'||Array.isArray(input))throw new TypeError('Gemini TTS input is required.');
+		return this._call('createTtsJob', input, null, {endpoint:'/rest/tts/gemini/jobs',json:true,idempotencyKey:options?.idempotencyKey});
+	}
+	listGeminiTtsVoices() { return this._call('createTtsJob',null,null,{endpoint:'/rest/tts/gemini/voices',method:'GET'}); }
+	createOpenAiTtsJob(input, options) {
+		if(!input||typeof input!=='object'||Array.isArray(input))throw new TypeError('OpenAI TTS input is required.');
+		return this._call('createTtsJob',input,null,{endpoint:'/rest/tts/openai/jobs',json:true,idempotencyKey:options?.idempotencyKey});
+	}
+	listOpenAiTtsVoices() { return this._call('createTtsJob',null,null,{endpoint:'/rest/tts/openai/voices',method:'GET'}); }
+	getTtsOptions() { return this._call('createTtsJob',null,null,{endpoint:'/rest/tts/options',method:'GET'}); }
+	quoteTts(input) { return this._call('createTtsJob',input,null,{endpoint:'/rest/tts/quote',json:true}); }
 
 	getTtsJob(jobId) {
 		const id = normalizeTtsJobId(jobId);
@@ -736,7 +738,7 @@ class ApickClient {
 
 	_imageOptions(prompt, options, maxCount) {
 		const config = options || {};
-		for (const key of ['model', 'quality', 'count', 'n', 'outputCompression', 'input_fidelity', 'moderation', 'mask', 'maskFilename', 'maskContentType']) {
+		for (const key of ['model', 'count', 'n', 'outputCompression', 'input_fidelity', 'moderation', 'mask', 'maskFilename', 'maskContentType']) {
 			if (Object.prototype.hasOwnProperty.call(config, key)) throw new TypeError(`${key} is not a supported image option.`);
 		}
 		const imageCount = positiveInteger('imageCount', config.imageCount, 1);
@@ -748,10 +750,11 @@ class ApickClient {
 			size, output_format: config.outputFormat || 'png',
 			background: config.background || 'auto'
 		};
-		if (config.idempotencyKey !== undefined) {
-			payload.idempotency_key = requiredString('idempotencyKey', config.idempotencyKey, 128);
-			if (!/^[A-Za-z0-9_-]{8,128}$/.test(payload.idempotency_key)) throw new TypeError('idempotencyKey must use 8-128 letters, numbers, underscores, or hyphens.');
+		if (config.quality !== undefined) {
+			if (!IMAGE_AI_QUALITIES.includes(config.quality)) throw new TypeError(`quality must be one of: ${IMAGE_AI_QUALITIES.join(', ')}.`);
+			payload.quality = config.quality;
 		}
+		// 서버가 같은 요청도 매번 새로 생성·과금하므로 idempotencyKey 는 보내지 않는다(예전 코드 호환을 위해 받기만 한다).
 		return payload;
 	}
 
@@ -969,24 +972,24 @@ class ApickClient {
 		return this._skills('GET', '/rest/skills', { query });
 	}
 
-	getSkillPerformance() {
+	getSkillPerformance() {
 		return this._skills('GET', '/skills/performance/data.json');
-	}
-
-	_subagent(method, route, options) { return this._skills(method, '/rest/subagent/v1' + route, options); }
-	subagentStatus() { return this._subagent('GET', '/status'); }
-	subagentUsage() { return this._subagent('GET', '/usage'); }
-	createSubagentFile(input) { return this._subagent('POST', '/files', {body: input}); }
-	getSubagentFile(fileId) { return this._subagent('GET', '/files/' + normalizeSubagentId(fileId,'saf')); }
-	uploadSubagentPart(fileId, partNo, data) { if(!Number.isSafeInteger(partNo)||partNo<0||typeof data!=='string')throw new TypeError('Invalid upload part.');return this._subagent('POST','/files/'+normalizeSubagentId(fileId,'saf')+'/parts',{body:{part_no:partNo,data}}); }
-	completeSubagentFile(fileId) { return this._subagent('POST','/files/'+normalizeSubagentId(fileId,'saf')+'/complete',{body:{}}); }
-	deleteSubagentFile(fileId) { return this._subagent('DELETE','/files/'+normalizeSubagentId(fileId,'saf')); }
-	dispatchSubagent(input, options) { const key=requiredString('idempotencyKey',options?.idempotencyKey,200);if(key.length<8)throw new TypeError('idempotencyKey must contain at least 8 characters.');return this._subagent('POST','/jobs',{body:input,idempotencyKey:key}); }
-	collectSubagent(jobId, options) { return this._subagent('GET','/jobs/'+normalizeSubagentId(jobId,'saj'),{query:options?.cursor?{cursor:String(options.cursor)}:{}}); }
-	subagentEvidence(jobId,evidenceIds) { return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/evidence',{body:{evidence_ids:evidenceIds}}); }
-	reviewSubagent(jobId,resultHash,decision) { if(!['accepted','rejected'].includes(decision)||!/^[a-f0-9]{64}$/.test(resultHash))throw new TypeError('Invalid review.');return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/review',{body:{result_hash:resultHash,decision}}); }
-	cancelSubagent(jobId) { return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/cancel',{body:{}}); }
-	deleteSubagentJob(jobId) { return this._subagent('DELETE','/jobs/'+normalizeSubagentId(jobId,'saj')); }
+	}
+
+	_subagent(method, route, options) { return this._skills(method, '/rest/subagent/v1' + route, options); }
+	subagentStatus() { return this._subagent('GET', '/status'); }
+	subagentUsage() { return this._subagent('GET', '/usage'); }
+	createSubagentFile(input) { return this._subagent('POST', '/files', {body: input}); }
+	getSubagentFile(fileId) { return this._subagent('GET', '/files/' + normalizeSubagentId(fileId,'saf')); }
+	uploadSubagentPart(fileId, partNo, data) { if(!Number.isSafeInteger(partNo)||partNo<0||typeof data!=='string')throw new TypeError('Invalid upload part.');return this._subagent('POST','/files/'+normalizeSubagentId(fileId,'saf')+'/parts',{body:{part_no:partNo,data}}); }
+	completeSubagentFile(fileId) { return this._subagent('POST','/files/'+normalizeSubagentId(fileId,'saf')+'/complete',{body:{}}); }
+	deleteSubagentFile(fileId) { return this._subagent('DELETE','/files/'+normalizeSubagentId(fileId,'saf')); }
+	dispatchSubagent(input, options) { const key=requiredString('idempotencyKey',options?.idempotencyKey,200);if(key.length<8)throw new TypeError('idempotencyKey must contain at least 8 characters.');return this._subagent('POST','/jobs',{body:input,idempotencyKey:key}); }
+	collectSubagent(jobId, options) { return this._subagent('GET','/jobs/'+normalizeSubagentId(jobId,'saj'),{query:options?.cursor?{cursor:String(options.cursor)}:{}}); }
+	subagentEvidence(jobId,evidenceIds) { return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/evidence',{body:{evidence_ids:evidenceIds}}); }
+	reviewSubagent(jobId,resultHash,decision) { if(!['accepted','rejected'].includes(decision)||!/^[a-f0-9]{64}$/.test(resultHash))throw new TypeError('Invalid review.');return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/review',{body:{result_hash:resultHash,decision}}); }
+	cancelSubagent(jobId) { return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/cancel',{body:{}}); }
+	deleteSubagentJob(jobId) { return this._subagent('DELETE','/jobs/'+normalizeSubagentId(jobId,'saj')); }
 
 	getSkill(skillId) {
 		return this._skills('GET', '/rest/skills/' + normalizeSkillId(skillId));

package/src/index.d.ts

@@ -31,14 +31,18 @@ export interface OcrOptions {
 export type ImageAiFormat = 'png' | 'jpeg' | 'webp';
 export type ImageAiBackground = 'auto' | 'opaque' | 'transparent';
 export type ImageAiSize = '1024x1024' | '1536x1024' | '1024x1536' | '1152x864' | '864x1152';
+/** basic 40P(default) · advanced 350P · premium 1,400P per image */
+export type ImageAiQuality = 'basic' | 'advanced' | 'premium';
 export type ImageAiStatus = 'waiting' | 'processing' | 'completed' | 'completed_partial' | 'failed';
 export type ApickImageErrorCode = `APICK_IMAGE_${string}`;
-export interface ImageAiOptions { imageCount?: number; size?: ImageAiSize; outputFormat?: ImageAiFormat; background?: ImageAiBackground; idempotencyKey?: string; }
+export interface ImageAiOptions { imageCount?: number; size?: ImageAiSize; outputFormat?: ImageAiFormat; background?: ImageAiBackground; quality?: ImageAiQuality;
+	/** @deprecated Ignored. Every image request is generated and charged as a new request. */
+	idempotencyKey?: string; }
 export interface ImageAiGenerateOptions extends ImageAiOptions { referenceImage?: string|BinaryInput|ArrayBuffer|ArrayBufferView; referenceFilename?: string; referenceContentType?: 'image/png'|'image/jpeg'|'image/webp'; }
 export interface ImageAiEditOptions extends ImageAiOptions { filename?: string; contentType?: 'image/png'|'image/jpeg'|'image/webp'; }
 export interface ImageAiResultImage { index:number; b64_json:string; mime_type:'image/png'|'image/jpeg'|'image/webp'; width:number; height:number; }
-export interface ImageAiResultData { request_id:string; image_count:number; images:ImageAiResultImage[]; idempotent_replay?:boolean; }
-export interface ImageAiPendingData {request_id:string;job_id:string;status:'processing';billing_status:'pending';reserved_point:number;}
+export interface ImageAiResultData { request_id:string; image_count:number; images:ImageAiResultImage[]; idempotent_replay?:boolean; }
+export interface ImageAiPendingData {request_id:string;job_id:string;status:'processing';billing_status:'pending';reserved_point:number;}
 export interface ImageAiJobData { job_id:string; status:ImageAiStatus; requested_count:number; completed_count?:number; failed_count?:number; prepaid_point?:number; charged_point?:number; refunded_point?:number; result_available?:boolean; expires_at?:string|null; error_code?:ApickImageErrorCode|null; }
 
 export interface MaskResidentNumberOptions extends OcrOptions {
@@ -200,33 +204,33 @@ export interface YoutubeSubtitleList {
 }
 export interface YoutubeSubtitleOptions { format?: 'vtt' | 'srt' | 'txt'; type?: 'any' | 'manual' | 'auto'; }
 
-/** @deprecated Retired APICK voice IDs. Query listGeminiTtsVoices or listOpenAiTtsVoices. */
-export const TTS_VOICE_IDS: readonly [
+/** @deprecated Retired APICK voice IDs. Query listGeminiTtsVoices or listOpenAiTtsVoices. */
+export const TTS_VOICE_IDS: readonly [
 	'v2_ann_m_30s_01', 'v2_ann_m_30s_02', 'v2_ann_m_30s_04', 'v2_ann_m_30s_05', '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_young_01', 'v2_f_senior_01'
 ];
-export type TtsVoiceId = string;
-/** @deprecated Automatic fallback is no longer supported. */
-export type TtsFallbackPolicy = 'never' | 'queue_full' | 'busy';
-export interface TtsFallbackOptions { voice_id?: string; style?: string; }
-/** @deprecated Retired APICK request shape. Use GeminiTtsInput or OpenAiTtsInput. */
-export interface ApickTtsInput { voice_id: TtsVoiceId; text?: string; utterances?: Array<{text:string;emotion?:string;speed?:number;pause_after_ms?:number}>; normalize_text?:boolean; fallback_policy?:TtsFallbackPolicy; fallback_options?:TtsFallbackOptions; }
-export interface TtsStyleOptions { style?:string; emotion?:'neutral'|'calm'|'cheerful'|'excited'|'sad'|'serious'|'friendly'|'empathetic'|'confident'|'gentle'|'whisper'|'narration'; tone?:'narration'|'news'|'audiobook'|'documentary'|'ad'|'conversation'|'announcement'|'tutorial'|'storytelling'; accent?:'standard'|'seoul'|'gyeongsang'|'jeolla'|'chungcheong'; pace?:number; pitch?:number; volume_gain_db?:number; }
-export interface TtsSpeakerOptions extends TtsStyleOptions { voice_id?:string; }
-export interface TtsUtterance extends TtsSpeakerOptions { text:string; speaker?:string; }
-export interface GeminiTtsInput extends TtsStyleOptions { voice_id?:string; text?:string; utterances?:TtsUtterance[]; speakers?:Record<string,TtsSpeakerOptions>; multi_speaker?:boolean; normalize_text?:boolean; language_code?:'ko'|'ko-KR'; }
-export interface OpenAiTtsInput extends GeminiTtsInput {}
-export interface TtsOptions { voiceId?:TtsVoiceId; normalizeText?:boolean; idempotencyKey?:string; }
-export interface GeminiTtsVoice { voice_id:string; name:string; gender:string|null; tone:string; age_band:string|null; age_years?:number|null; age_verified?:boolean; age_basis?:'catalog_description'|'reviewed'; age_source?:string; description?:string; language_code?:string|null; reviewed_at?:string; library:string; }
-export interface TtsQuote { synthesis:number; normalization:number; estimated_total:number; maximum:number; synthesis_maximum:number; normalization_maximum:number; estimated_only:true; currency:'POINT'; fallback_price_may_change:boolean; }
+export type TtsVoiceId = string;
+/** @deprecated Automatic fallback is no longer supported. */
+export type TtsFallbackPolicy = 'never' | 'queue_full' | 'busy';
+export interface TtsFallbackOptions { voice_id?: string; style?: string; }
+/** @deprecated Retired APICK request shape. Use GeminiTtsInput or OpenAiTtsInput. */
+export interface ApickTtsInput { voice_id: TtsVoiceId; text?: string; utterances?: Array<{text:string;emotion?:string;speed?:number;pause_after_ms?:number}>; normalize_text?:boolean; fallback_policy?:TtsFallbackPolicy; fallback_options?:TtsFallbackOptions; }
+export interface TtsStyleOptions { style?:string; emotion?:'neutral'|'calm'|'cheerful'|'excited'|'sad'|'serious'|'friendly'|'empathetic'|'confident'|'gentle'|'whisper'|'narration'; tone?:'narration'|'news'|'audiobook'|'documentary'|'ad'|'conversation'|'announcement'|'tutorial'|'storytelling'; accent?:'standard'|'seoul'|'gyeongsang'|'jeolla'|'chungcheong'; pace?:number; pitch?:number; volume_gain_db?:number; }
+export interface TtsSpeakerOptions extends TtsStyleOptions { voice_id?:string; }
+export interface TtsUtterance extends TtsSpeakerOptions { text:string; speaker?:string; }
+export interface GeminiTtsInput extends TtsStyleOptions { voice_id?:string; text?:string; utterances?:TtsUtterance[]; speakers?:Record<string,TtsSpeakerOptions>; multi_speaker?:boolean; normalize_text?:boolean; language_code?:'ko'|'ko-KR'; }
+export interface OpenAiTtsInput extends GeminiTtsInput {}
+export interface TtsOptions { voiceId?:TtsVoiceId; normalizeText?:boolean; idempotencyKey?:string; }
+export interface GeminiTtsVoice { voice_id:string; name:string; gender:string|null; tone:string; age_band:string|null; age_years?:number|null; age_verified?:boolean; age_basis?:'catalog_description'|'reviewed'; age_source?:string; description?:string; language_code?:string|null; reviewed_at?:string; library:string; }
+export interface TtsQuote { synthesis:number; normalization:number; estimated_total:number; maximum:number; synthesis_maximum:number; normalization_maximum:number; estimated_only:true; currency:'POINT'; fallback_price_may_change:boolean; }
 
 export interface TtsJobData {
 	job_id: string;
 	status: 'waiting' | 'processing' | 'completed' | 'cancelled' | 'failed';
-	voice_id?: string;
-	synthesis?: {engine:'apick'|'gemini'|'openai';model:string;voice_id:string;fallback_reason:string|null;age_verified:boolean;notice:string|null};
-	normalization?: {enabled:boolean;run_id:string|null;status:string;skill_id:string|null};
-	billing?: {status:string;synthesis:number;skill:number;total:number;reserved:number;refunded:number;released:number;currency:'POINT'};
-	expires_at?:string|null;
+	voice_id?: string;
+	synthesis?: {engine:'apick'|'gemini'|'openai';model:string;voice_id:string;fallback_reason:string|null;age_verified:boolean;notice:string|null};
+	normalization?: {enabled:boolean;run_id:string|null;status:string;skill_id:string|null};
+	billing?: {status:string;synthesis:number;skill:number;total:number;reserved:number;refunded:number;released:number;currency:'POINT'};
+	expires_at?:string|null;
 	character_count?: number;
 	result_available?: boolean;
 	subtitles_available?: boolean;
@@ -309,29 +313,29 @@ export class ApickClient {
 	youtubeThumbnail(url: string): Promise<ApickBinaryResult>;
 	youtubeSubtitleList(url: string): Promise<ApickResult<YoutubeSubtitleList>>;
 	youtubeSubtitle(url: string, lang: string, options?: YoutubeSubtitleOptions): Promise<ApickBinaryResult>;
-	createTtsJob(text: string | GeminiTtsInput, options?: TtsOptions): Promise<ApickResult<TtsJobData>>;
-	createGeminiTtsJob(input:GeminiTtsInput, options?:{idempotencyKey?:string}):Promise<ApickResult<TtsJobData>>;
-	listGeminiTtsVoices():Promise<ApickResult<{voices:GeminiTtsVoice[];complete:boolean;checked_at:string|null}>>;
-	createOpenAiTtsJob(input:OpenAiTtsInput, options?:{idempotencyKey?:string}):Promise<ApickResult<TtsJobData>>;
-	listOpenAiTtsVoices():Promise<ApickResult<{voices:GeminiTtsVoice[];complete:boolean;checked_at:string|null}>>;
-	getTtsOptions():Promise<ApickResult<{engines:Record<'gemini'|'openai',Record<string,unknown>>}>>;
-	quoteTts(input:GeminiTtsInput&{engine?:'gemini'|'openai'}):Promise<ApickResult<TtsQuote>>;
+	createTtsJob(text: string | GeminiTtsInput, options?: TtsOptions): Promise<ApickResult<TtsJobData>>;
+	createGeminiTtsJob(input:GeminiTtsInput, options?:{idempotencyKey?:string}):Promise<ApickResult<TtsJobData>>;
+	listGeminiTtsVoices():Promise<ApickResult<{voices:GeminiTtsVoice[];complete:boolean;checked_at:string|null}>>;
+	createOpenAiTtsJob(input:OpenAiTtsInput, options?:{idempotencyKey?:string}):Promise<ApickResult<TtsJobData>>;
+	listOpenAiTtsVoices():Promise<ApickResult<{voices:GeminiTtsVoice[];complete:boolean;checked_at:string|null}>>;
+	getTtsOptions():Promise<ApickResult<{engines:Record<'gemini'|'openai',Record<string,unknown>>}>>;
+	quoteTts(input:GeminiTtsInput&{engine?:'gemini'|'openai'}):Promise<ApickResult<TtsQuote>>;
 	getTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
 	cancelTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
 	downloadTtsResult(jobId: string): Promise<ApickBinaryResult>;
 	downloadTtsSubtitles(jobId: string): Promise<ApickBinaryResult>;
-	/** @deprecated Retired endpoint; the service returns HTTP 409. */
-	getTtsQuality(jobId: string): Promise<ApickResult<TtsQualityData>>;
-	/** @deprecated Retired endpoint; the service returns HTTP 409. */
-	retryTtsJob(jobId: string, utteranceIds: string[], idempotencyKey: string): Promise<ApickResult<TtsJobData>>;
-	/** @deprecated Retired endpoint; the service returns HTTP 409. */
+	/** @deprecated Retired endpoint; the service returns HTTP 409. */
+	getTtsQuality(jobId: string): Promise<ApickResult<TtsQualityData>>;
+	/** @deprecated Retired endpoint; the service returns HTTP 409. */
+	retryTtsJob(jobId: string, utteranceIds: string[], idempotencyKey: string): Promise<ApickResult<TtsJobData>>;
+	/** @deprecated Retired endpoint; the service returns HTTP 409. */
 	downloadTtsCandidate(jobId: string, candidateId: string): Promise<ApickBinaryResult>;
 	htmlToPdf(html: string, options?: { pagination?: boolean }): Promise<ApickBinaryResult>;
 	jsonToExcel(data: unknown[], options?: { sheetName?: string }): Promise<ApickBinaryResult>;
 	summarize(text: string): Promise<ApickResult>;
 	polish(text: string): Promise<ApickResult>;
-	generateImages(prompt:string, options?:ImageAiGenerateOptions): Promise<ApickResult<ImageAiResultData|ImageAiPendingData>>;
-	editImages(image:string|BinaryInput|ArrayBuffer|ArrayBufferView, prompt:string, options?:ImageAiEditOptions): Promise<ApickResult<ImageAiResultData|ImageAiPendingData>>;
+	generateImages(prompt:string, options?:ImageAiGenerateOptions): Promise<ApickResult<ImageAiResultData|ImageAiPendingData>>;
+	editImages(image:string|BinaryInput|ArrayBuffer|ArrayBufferView, prompt:string, options?:ImageAiEditOptions): Promise<ApickResult<ImageAiResultData|ImageAiPendingData>>;
 	createImageGenerationJob(prompt:string, options?:ImageAiGenerateOptions): Promise<ApickResult<ImageAiJobData>>;
 	createImageEditJob(image:string|BinaryInput|ArrayBuffer|ArrayBufferView, prompt:string, options?:ImageAiEditOptions): Promise<ApickResult<ImageAiJobData>>;
 	getImageJob(jobId:string): Promise<ApickResult<ImageAiJobData>>;
@@ -353,20 +357,20 @@ export class ApickClient {
 	getTaxReturnHistory(transactionId: string): Promise<ApickResult<DataRequestResult<TaxReturnHistoryResultPayload>>>;
 	searchSkills(options?: SkillSearchOptions): Promise<ApickResult<SkillPage<SkillSummary>>>;
 	/** Public measured results and methods; model scores are not accuracy guarantees. */
-	getSkillPerformance(): Promise<ApickResult<SkillPerformanceReport>>;
-	subagentStatus(): Promise<ApickResult<Record<string, unknown>>>;
-	subagentUsage(): Promise<ApickResult<Record<string, unknown>>>;
-	createSubagentFile(input: {path:string;bytes:number;sha256:string;retention?:'seven_days'|'none'}): Promise<ApickResult<SubagentFile>>;
-	getSubagentFile(fileId:string): Promise<ApickResult<SubagentFile>>;
-	uploadSubagentPart(fileId:string,partNo:number,data:string): Promise<ApickResult<Record<string,unknown>>>;
-	completeSubagentFile(fileId:string): Promise<ApickResult<SubagentFile>>;
-	deleteSubagentFile(fileId:string): Promise<ApickResult<Record<string,unknown>>>;
-	dispatchSubagent(input:SubagentTask,options:{idempotencyKey:string}): Promise<ApickResult<SubagentJob>>;
-	collectSubagent(jobId:string,options?:{cursor?:string}): Promise<ApickResult<SubagentJob>>;
-	subagentEvidence(jobId:string,evidenceIds:string[]): Promise<ApickResult<Record<string,unknown>>>;
-	reviewSubagent(jobId:string,resultHash:string,decision:'accepted'|'rejected'): Promise<ApickResult<Record<string,unknown>>>;
-	cancelSubagent(jobId:string): Promise<ApickResult<SubagentJob>>;
-	deleteSubagentJob(jobId:string): Promise<ApickResult<Record<string,unknown>>>;
+	getSkillPerformance(): Promise<ApickResult<SkillPerformanceReport>>;
+	subagentStatus(): Promise<ApickResult<Record<string, unknown>>>;
+	subagentUsage(): Promise<ApickResult<Record<string, unknown>>>;
+	createSubagentFile(input: {path:string;bytes:number;sha256:string;retention?:'seven_days'|'none'}): Promise<ApickResult<SubagentFile>>;
+	getSubagentFile(fileId:string): Promise<ApickResult<SubagentFile>>;
+	uploadSubagentPart(fileId:string,partNo:number,data:string): Promise<ApickResult<Record<string,unknown>>>;
+	completeSubagentFile(fileId:string): Promise<ApickResult<SubagentFile>>;
+	deleteSubagentFile(fileId:string): Promise<ApickResult<Record<string,unknown>>>;
+	dispatchSubagent(input:SubagentTask,options:{idempotencyKey:string}): Promise<ApickResult<SubagentJob>>;
+	collectSubagent(jobId:string,options?:{cursor?:string}): Promise<ApickResult<SubagentJob>>;
+	subagentEvidence(jobId:string,evidenceIds:string[]): Promise<ApickResult<Record<string,unknown>>>;
+	reviewSubagent(jobId:string,resultHash:string,decision:'accepted'|'rejected'): Promise<ApickResult<Record<string,unknown>>>;
+	cancelSubagent(jobId:string): Promise<ApickResult<SubagentJob>>;
+	deleteSubagentJob(jobId:string): Promise<ApickResult<Record<string,unknown>>>;
 	getSkill(skillId: string): Promise<ApickResult<SkillDetail>>;
 	quoteSkill(skillId: string, input: Record<string, unknown>, options?: { version?: string }): Promise<ApickResult<SkillQuote>>;
 	runSkill<T = Record<string, unknown>>(skillId: string, input: Record<string, unknown>, options: SkillRunOptions): Promise<ApickResult<SkillRun<T>>>;
@@ -461,8 +465,8 @@ export interface SkillSummary {
 	rating_average: number | null;
 }
 export interface SkillDetail extends SkillSummary {
-	description: string; billing_rule: 'validated_result' | 'subagent_usage'; limits: SkillLimits | null;
-	delivery?: 'installed_agent'; installation?: {package:string;command:string;api_key_env:string;guide:string;usage:string};
+	description: string; billing_rule: 'validated_result' | 'subagent_usage'; limits: SkillLimits | null;
+	delivery?: 'installed_agent'; installation?: {package:string;command:string;api_key_env:string;guide:string;usage:string};
 	billing?: {markup_percent:number;installation_points:number;base_points:number;complete_cache_points:number;quota:null};
 	input_schema: Record<string, unknown>; output_schema: Record<string, unknown>;
 	examples: unknown[]; stats: Record<string, unknown> | null; published_at: string | null;
@@ -523,7 +527,7 @@ export interface VideoJobData {
 	result_expires_at?: string | null; idempotent_replay?: boolean;
 	error?: { code: string; message: string };
 }
-
-export interface SubagentTask { kind:'inventory'|'extract'|'summarize'|'compare';goal:string;file_ids:string[];focus?:string[];acceptance?:string[];retention?:'seven_days'|'none'; }
-export interface SubagentFile { file_id:string;path:string;sha256:string;bytes:number;state:string;expires_at:string;part_bytes?:number; }
-export interface SubagentJob { job_id:string;kind:SubagentTask['kind'];state:string;billing_state:string;cache_hit:boolean;reserved_points:number;charged_points:number;accrued_points:string;result_hash?:string;result?:Record<string,unknown>; }
+
+export interface SubagentTask { kind:'inventory'|'extract'|'summarize'|'compare';goal:string;file_ids:string[];focus?:string[];acceptance?:string[];retention?:'seven_days'|'none'; }
+export interface SubagentFile { file_id:string;path:string;sha256:string;bytes:number;state:string;expires_at:string;part_bytes?:number; }
+export interface SubagentJob { job_id:string;kind:SubagentTask['kind'];state:string;billing_state:string;cache_hit:boolean;reserved_points:number;charged_points:number;accrued_points:string;result_hash?:string;result?:Record<string,unknown>; }