apick-api 3.9.0 → 3.11.0

package/CHANGELOG.md

@@ -1,9 +1,25 @@
-# Changelog
+# 3.11.0
 
-## 3.9.0 — 2026-10-04
+- TTS voice metadata includes documented preset age evidence; case aliases remain supported without duplicate catalog entries. Reservation reductions are included in `billing.released`.
+- 목소리 목록에 공식 설정 연령 근거를 추가하고 대소문자 별칭 호환을 유지합니다. 예약 감액은 `billing.released`에 누적됩니다.
 
-- `getSkillPerformance()`와 공개 성능표 타입을 추가했습니다. 시험 방식·표본 수·평가일·성공률 구간·미검증 상태를 확인할 수 있습니다.
-- Add `getSkillPerformance()` and report types for methods, sample sizes, evaluation dates, success-rate intervals and untested states.
+- TTS: Gemini direct synthesis, queue fallback, default-on paid normalization, unified MP3/ASS and billing.
+- TTS: Gemini 직접 합성, 대기 상태별 전환, 기본 on 유료 정규화, 공통 MP3·ASS와 정산 내역.
+- 이미지 생성·편집: 사용량 미확정 시 202와 작업 ID를 반환하는 정산 보류 응답 타입을 추가했습니다.
+- Image generation/editing: added the HTTP 202 settlement-pending response type for unconfirmed usage.
+
+# 3.10.0 — 2026-10-04
+
+서브에이전트 전용 REST 메서드와 타입을 추가했습니다. 설치형 스킬의 사용량 과금 정보를 제공합니다.
+
+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
 

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

@@ -101,8 +101,8 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `requestHealthCheckup(input)` / `getHealthCheckup(transactionId)` | 국가 건강검진 결과 조회 / National health checkup results | JSON |
 | `requestCashReceiptDeduction(input)` / `getCashReceiptDeduction(transactionId)` | 현금영수증 소득공제 내역 / Cash receipt income deductions | JSON |
 | `requestTaxReturnHistory(input)` / `getTaxReturnHistory(transactionId)` | 국세 신고내역 조회 / National tax return history | JSON |
-| `searchSkills(options)` / `getSkill(skillId)` | Skill 검색·상세 / Search and inspect Skills | JSON |
-| `getSkillPerformance()` | 시험 방법·표본 수·기계 검사·품질 점수 / Measured results and methods | JSON |
+| `searchSkills(options)` / `getSkill(skillId)` | Skill 검색·상세 / Search and inspect Skills | JSON |
+| `getSkillPerformance()` | 시험 방법·표본 수·기계 검사·품질 점수 / Measured results and methods | JSON |
 | `quoteSkill(skillId, input, options)` | Skill 견적(무료) / Quote a run (free) | JSON |
 | `runSkill(skillId, input, options)` | Skill 실행 / Run a Skill | JSON |
 | `getSkillRun(runId)` / `getSkillRunResult(runId)` / `cancelSkillRun(runId)` | 실행 조회·결과·취소 / Read, fetch result, cancel | JSON |
@@ -116,7 +116,7 @@ Search and run reviewed Skills. Points are charged only when a result in the pro
 ```js
 import { randomUUID } from 'node:crypto';
 
-const found = await apick.searchSkills({ query: '상품명', limit: 5 });
+const found = await apick.searchSkills({ query: '상품명', limit: 5 });
 const skillId = found.data.items[0].skill_id;
 const detail = await apick.getSkill(skillId);          // input_schema, output_schema, price_points, estimated_points
 const input = { product_name: '튼튼한 접이식 우산' };
@@ -131,11 +131,11 @@ while (!['succeeded', 'failed', 'timed_out', 'cancelled'].includes(run.status))
 console.log(run.status, run.billing, run.result);
 ```
 
-검증 결과는 [스킬 성능표](https://apick.app/skills/performance) 또는 `const { data } = await apick.getSkillPerformance()`로 확인합니다. 표본 수·시험일·방법·기계 검사 통과율과 모델 평가 점수를 함께 읽으세요. 미검증 값은 `null`이며, 과거의 다른 조건에서 얻은 점수는 `legacy`로 구분합니다. 모델 점수는 객관적 정확도나 판매 성과 보장이 아닙니다.
-
-See the [Skill performance report](https://apick.app/skills/performance) or call `const { data } = await apick.getSkillPerformance()`. Read sample sizes, dates, methods, machine checks and model scores together. Unmeasured values are `null`; historical results under different conditions are in `legacy`. Model scores are not objective accuracy or sales guarantees.
-
-`searchSkills({ sort })` 로 추천(`recommended`)·인기(`popular`)·많이 사용(`used`)·좋아요순(`likes`)·평점순(`rating`)·최신(`new`) 순서를 고르고, 검색·상세 응답의 `usage_label`(사용 건수 구간)·`like_count`·`review_count`·`rating_average` 로 Skill 을 비교할 수 있습니다.
+검증 결과는 [스킬 성능표](https://apick.app/skills/performance) 또는 `const { data } = await apick.getSkillPerformance()`로 확인합니다. 표본 수·시험일·방법·기계 검사 통과율과 모델 평가 점수를 함께 읽으세요. 미검증 값은 `null`이며, 과거의 다른 조건에서 얻은 점수는 `legacy`로 구분합니다. 모델 점수는 객관적 정확도나 판매 성과 보장이 아닙니다.
+
+See the [Skill performance report](https://apick.app/skills/performance) or call `const { data } = await apick.getSkillPerformance()`. Read sample sizes, dates, methods, machine checks and model scores together. Unmeasured values are `null`; historical results under different conditions are in `legacy`. Model scores are not objective accuracy or sales guarantees.
+
+`searchSkills({ sort })` 로 추천(`recommended`)·인기(`popular`)·많이 사용(`used`)·좋아요순(`likes`)·평점순(`rating`)·최신(`new`) 순서를 고르고, 검색·상세 응답의 `usage_label`(사용 건수 구간)·`like_count`·`review_count`·`rating_average` 로 Skill 을 비교할 수 있습니다.
 Pick an order with `searchSkills({ sort })` (`recommended`, `popular`, `used`, `likes`, `rating`, `new`) and compare Skills with `usage_label` (a usage tier), `like_count`, `review_count` and `rating_average` in search and detail responses.
 
 `searchSkills({ sort })` 로 추천(`recommended`)·인기(`popular`)·많이 사용(`used`)·좋아요순(`likes`)·평점순(`rating`)·최신(`new`) 순서를 고르고, 검색·상세 응답의 `usage_label`(사용 건수 구간)·`like_count`·`review_count`·`rating_average` 로 Skill 을 비교할 수 있습니다.
@@ -266,13 +266,13 @@ if (job.data.status === 'completed') {
 }
 ```
 
-접수 성공 시 과금되며 취소해도 환불되지 않습니다. 취소는 `waiting` 또는 `processing` 상태에서 가능하고, MP3와 ASS 자막은 각각 한 번만 내려받을 수 있습니다. 각 다운로드가 시작되면 해당 서버 원본이 즉시 폐기되므로 전송 중단 시에도 다시 받을 수 없습니다.
+접수 시 최대 요금을 예약하고 완료 후 실제 금액을 확정합니다. 연결 종료는 정상 과금하며 명시 취소는 이미 수행한 유료 처리분을 정산합니다. MP3와 ASS 자막은 각각 한 번 완료 다운로드할 수 있고, 전송 중단 시 다시 시도할 수 있습니다.
 
-The charge is final when the job is accepted. Cancellation is allowed while `waiting` or `processing`. The MP3 and ASS subtitles can each be downloaded once. Starting either download immediately consumes that server copy, so an interrupted transfer cannot be downloaded again.
+Submission reserves an upper bound; successful completion settles actual charges. Disconnects do not cancel billing. Explicit cancellation settles work already performed. MP3 and ASS each allow one completed download; interrupted downloads can be retried.
 
-`createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문은 문맥에 맞는 한글 읽기로 자동 변환한 뒤 음성을 생성합니다(예: `5번 버스` → 오 번 버스, `버튼을 5번` → 다섯 번, `-5℃` → 영하 오 도, `인증번호 105028` → 한 자리씩). 모든 TTS 요청에 자동 적용되므로 추가 옵션이나 별도 Skill 호출이 필요하지 않습니다. 과금 글자 수와 요금은 보낸 원문 기준이며 요청·응답 형식은 그대로입니다. 요금은 100자까지 30포인트이고 이후 100자마다 10포인트가 추가되며, 자동 변환에 따른 추가 요금은 없습니다. 읽는 법을 직접 정하려면 한글로 풀어 써서 보내세요. ASS 자막은 보낸 원문 표기로 제공됩니다. 정규화에 실패하면 원문으로 음성을 생성합니다.
+정규화는 기본 켜짐이며 발음을 다듬는 스킬 요금이 추가됩니다. `normalize_text: false`(SDK `normalizeText: false`)로 실행과 요금을 끕니다. 스킬 최종가는 기본요금(판매자 금액·기본 수수료) + AI 원가 × 환율 × 1.4입니다. 정규화 실패는 제작을 중단하며, 서버·공급자의 최종 제작 실패는 정규화까지 전액 환불합니다. ASS에는 원문을 표시합니다.
 
-Numbers, units, symbols and English text in the text passed to `createTtsJob()` are automatically converted into context-appropriate Korean readings before synthesis (for example, `5번 버스` is read as "오 번 버스", `버튼을 5번` as "다섯 번", `-5℃` as "영하 오 도", and `인증번호 105028` digit by digit). This applies automatically to every TTS request; no extra option or separate Skill call is needed. The billed character count and price are based on the text you send, and the request and response formats are unchanged. The price is 30 points for up to 100 characters plus 10 points for each additional 100 characters, with no extra charge for the automatic conversion. To choose a reading yourself, spell it out in Hangul. ASS subtitles keep the text as you sent it. If normalization fails, speech is generated from the original text.
+Normalization is on by default and adds a skill charge. Set `normalize_text: false` (SDK `normalizeText: false`) to skip execution and billing. The skill price is its base fee (seller amount and base commission) plus actual AI cost × the pinned exchange rate × 1.4. Normalization failure stops synthesis; final server/provider failures refund normalization as well. ASS preserves the original spelling.
 
 ## 신분증 마스킹 / Identity masking
 
@@ -464,3 +464,21 @@ if (status.data.status === "completed") {
 ### 스킬 결과 파일 / Skill result files
 
 `getSkillArtifact(runId, fileId)` returns authenticated binary artifacts. 가격·시간·호출 수 범위와 다운로드 예제: [스킬 파일 가이드 / guide](docs/skill-artifacts.md).
+
+## 서브에이전트 / Subagent
+
+설치형 `apick-agent` 상품은 `apick-subagent` 스킬 패키지와 전용 REST·MCP를 사용합니다. 원가 +40%, 승인된 동일 결과 캐시 무료, 충전 잔액 외 상품 한도 없음. [연동 가이드](https://apick.app/dev_guide/subagent).
+
+The installed `apick-agent` product uses the `apick-subagent` skill package and dedicated REST/MCP interfaces. Confirmed cost plus 40%; approved identical cache reuse is free, with no product quota beyond prepaid balance. [Integration guide](https://apick.app/dev_guide/subagent).
+
+```sh
+npx -y apick-mcp --server subagent
+# Local workspace collection / 로컬 파일 수집
+npm install -g apick-subagent
+apick-subagent install
+```
+
+Set `APICK_API_KEY` in the environment. 원격 MCP는 업로드된 자료를 처리합니다. The remote MCP processes uploaded content; the installed bridge collects local files.
+
+
+TTS: [Gemini · 자동 전환 · 정규화 요금 / fallback and normalization billing](docs/tts.md). `createGeminiTtsJob`, `listGeminiTtsVoices`, `quoteTts`를 지원합니다.

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

@@ -1,9 +1,9 @@
 # apick-api English guide
 
-## Skill performance report
-
-Use `const { data } = await apick.getSkillPerformance()` to read the [public measurements](https://apick.app/skills/performance). Review sample sizes, dates, methods and failure reasons together. Model scores are not objective accuracy; unmeasured values are `null`. Reading the report does not execute a paid Skill.
-
+## Skill performance report
+
+Use `const { data } = await apick.getSkillPerformance()` to read the [public measurements](https://apick.app/skills/performance). Review sample sizes, dates, methods and failure reasons together. Model scores are not objective accuracy; unmeasured values are `null`. Reading the report does not execute a paid Skill.
+
 ## Request and response formats
 
 All SDK requests with a body use `multipart/form-data`. Arrays use separate indexed fields such as `utterance_ids[0]`; let the SDK set the Content-Type boundary. GET requests have no body. The server continues accepting older JSON requests for compatibility.
@@ -94,7 +94,7 @@ TTS supports 14 voice IDs. Use `TTS_VOICE_IDS` and the developer guide for the c
 
 `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`
 
-Numbers, units, symbols and English text in the text passed to `createTtsJob()` are automatically converted into context-appropriate Korean readings before synthesis (for example, `5번 버스` is read as "오 번 버스", `버튼을 5번` as "다섯 번", `-5℃` as "영하 오 도", and `인증번호 105028` digit by digit). This applies automatically to every TTS request; no extra option or separate Skill call is needed. The billed character count and price are based on the text you send, and the request and response formats are unchanged. The price is 30 points for up to 100 characters plus 10 points for each additional 100 characters, with no extra charge for the automatic conversion. To choose a reading yourself, spell it out in Hangul. ASS subtitles keep the text as you sent it. If normalization fails, speech is generated from the original text.
+Normalization is on by default and adds a skill charge. Set `normalize_text: false` (SDK `normalizeText: false`) to skip execution and billing. The skill price is its base fee (seller amount and base commission) plus actual AI cost × the pinned exchange rate × 1.4. Normalization failure stops synthesis; final server/provider failures refund normalization as well. ASS preserves the original spelling.
 
 ```js
 const screenshot = await client.screenshot('https://example.com');
@@ -144,7 +144,9 @@ const polished = await client.polish(draftText);
 
 Text input is limited to 100,000 characters.
 
-## Image AI
+## 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.
 
 ```js
 const result = await client.generateImages('A clean product photo on white', {
@@ -357,3 +359,6 @@ Skill details and quotes provide estimated price and duration ranges and tool ca
 ## Product-specific data guides
 
 Product-specific authenticated-data guides describe returned fields, source institutions, use cases, and FAQs. An authentication request starts access to the selected product and returns a transactionId for result polling. Request and response contracts and authentication are unchanged. See the [shared authentication guide](https://apick.app/dev_guide/data) for the flow and error handling.
+
+
+TTS: [Gemini · 자동 전환 · 정규화 요금 / fallback and normalization billing](tts.md). `createGeminiTtsJob`, `listGeminiTtsVoices`, `quoteTts`를 지원합니다.

package/docs/guide.ko.md

@@ -1,9 +1,9 @@
 # apick-api 한국어 가이드
 
-## 스킬 성능표
-
-`const { data } = await apick.getSkillPerformance()`로 [공개 측정표](https://apick.app/skills/performance)를 조회합니다. 표본 수·시험일·검사 방법·실패 사유를 함께 확인하세요. 모델 점수는 객관적 정확도가 아니며 미검증 값은 `null`입니다. 조회 자체에는 유료 실행이 필요하지 않습니다.
-
+## 스킬 성능표
+
+`const { data } = await apick.getSkillPerformance()`로 [공개 측정표](https://apick.app/skills/performance)를 조회합니다. 표본 수·시험일·검사 방법·실패 사유를 함께 확인하세요. 모델 점수는 객관적 정확도가 아니며 미검증 값은 `null`입니다. 조회 자체에는 유료 실행이 필요하지 않습니다.
+
 ## 요청과 응답 형식
 
 SDK의 본문 요청은 모두 `multipart/form-data`입니다. `utterance_ids[0]`처럼 배열을 개별 필드로 전송하며 `Content-Type` 헤더를 직접 지정할 필요가 없습니다. GET 조회는 본문을 보내지 않습니다. 기존 JSON 요청도 서버에서 호환용으로 계속 처리합니다.
@@ -94,7 +94,7 @@ TTS는 14개 목소리 ID를 지원합니다. 정확한 목록은 `TTS_VOICE_IDS
 
 `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`
 
-`createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문은 문맥에 맞는 한글 읽기로 자동 변환한 뒤 음성을 생성합니다(예: `5번 버스` → 오 번 버스, `버튼을 5번` → 다섯 번, `-5℃` → 영하 오 도, `인증번호 105028` → 한 자리씩). 모든 TTS 요청에 자동 적용되므로 추가 옵션이나 별도 Skill 호출이 필요하지 않습니다. 과금 글자 수와 요금은 보낸 원문 기준이며 요청·응답 형식은 그대로입니다. 요금은 100자까지 30포인트이고 이후 100자마다 10포인트가 추가되며, 자동 변환에 따른 추가 요금은 없습니다. 읽는 법을 직접 정하려면 한글로 풀어 써서 보내세요. ASS 자막은 보낸 원문 표기로 제공됩니다. 정규화에 실패하면 원문으로 음성을 생성합니다.
+정규화는 기본 켜짐이며 발음을 다듬는 스킬 요금이 추가됩니다. `normalize_text: false`(SDK `normalizeText: false`)로 실행과 요금을 끕니다. 스킬 최종가는 기본요금(판매자 금액·기본 수수료) + AI 원가 × 환율 × 1.4입니다. 정규화 실패는 제작을 중단하며, 서버·공급자의 최종 제작 실패는 정규화까지 전액 환불합니다. ASS에는 원문을 표시합니다.
 
 ```js
 const screenshot = await client.screenshot('https://example.com');
@@ -144,7 +144,9 @@ const polished = await client.polish(draftText);
 
 입력 텍스트는 최대 100,000자입니다.
 
-## 이미지 AI
+## 이미지 AI
+
+새 사용량 요금이 적용되면 외부 AI 판매가는 확인된 원가 × 적용 환율 × 1.4입니다. 생성·편집 응답에서 사용량이 미확정이면 HTTP 202와 `job_id`, `billing_status: "pending"`을 반환합니다. 이미 받은 결과는 보관하므로 재생성하지 말고 `getImageJob(job_id)`로 조회합니다. 정산 완료 후 기존 다운로드 메서드를 사용합니다.
 
 ```js
 const result = await client.generateImages('흰 배경의 제품 사진', {
@@ -365,3 +367,6 @@ if (status.data.status === "completed") {
 ## 상품별 조회 가이드
 
 상품별 간편인증 조회 가이드에는 조회 데이터, 출처 기관, 활용 사례와 자주 묻는 질문이 있습니다. 인증 요청은 해당 상품의 자료를 조회하기 위한 단계이며 결과 조회용 transactionId를 반환합니다. 요청·응답 계약과 인증 방식은 동일합니다. [공통 인증 흐름](https://apick.app/dev_guide/data)에서 절차와 오류 처리를 확인하세요.
+
+
+TTS: [Gemini · 자동 전환 · 정규화 요금 / fallback and normalization billing](tts.md). `createGeminiTtsJob`, `listGeminiTtsVoices`, `quoteTts`를 지원합니다.

package/docs/subagent.md

@@ -0,0 +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)

package/docs/tts.md

@@ -0,0 +1,54 @@
+# TTS · 한국어 안내
+
+apick 직접 제작, apick → Gemini 자동 전환, Gemini 직접 제작은 같은 작업 조회·MP3·ASS 다운로드 API를 사용합니다. 파일 구조와 규격은 같으며 음성은 엔진과 목소리에 따라 다릅니다.
+
+```js
+const apick = new ApickClient({ apiKey: process.env.APICK_API_KEY });
+const job = await apick.createTtsJob('기온은 5℃입니다.', {
+  voiceId: 'v2_ann_m_30s_01',
+  normalizeText: true,
+  fallbackPolicy: 'busy',
+  fallbackOptions: { voice_id: 'Charon', style: '차분하게' },
+  idempotencyKey: 'narration-001'
+});
+const direct = await apick.createGeminiTtsJob({
+  voice_id: 'Kore', style: '또렷하게', normalize_text: false,
+  utterances: [{ text: '오늘의 이야기입니다.', speaker: '진행자' }]
+}, { idempotencyKey: 'gemini-001' });
+const voices = await apick.listGeminiTtsVoices();
+const quote = await apick.quoteTts({ engine: 'gemini', text: '본문', voice_id: 'Kore' });
+const status = await apick.getTtsJob(job.data.job_id);
+// completed 이후 기존 downloadTtsResult / downloadTtsSubtitles 사용
+```
+
+| 옵션 | 동작 |
+| --- | --- |
+| `never` | 기본값. apick 대기열 등록, 가득 차면 429 |
+| `queue_full` | 대기열에도 빈자리가 없을 때 Gemini 전환 |
+| `busy` | 즉시 apick 실행이 불가능하면 Gemini 전환 |
+| `fallbackOptions` | 전환할 때만 적용되는 `voice_id`, `style` |
+| `normalizeText` / `normalize_text` | 기본 true. false는 정규화 스킬 실행·과금 생략 |
+
+정규화는 숫자·단위·약어의 문맥에 맞는 발음을 다듬으며, **추가 스킬 요금**이 합산됩니다. 정규화 on 입력 합계(발화 사이 줄바꿈 포함)는 2,000자, Gemini off는 8,000자, apick 기존 입력 한도는 800자입니다. 기본·확장 공개 목소리는 `listGeminiTtsVoices()`로 확인합니다. 자동 선택은 같은 성별의 한국어 목소리를 우선하고 공식 설명 또는 별도 검수로 확인한 연령대와 음색을 비교합니다. `age_basis: catalog_description`은 공식 설명에 적힌 설정 연령이며 실제 화자의 나이를 뜻하지 않습니다. 근거가 없는 목소리는 `age_verified: false`입니다. 대소문자 별칭은 목록에 중복 표시하지 않고 기존 입력도 허용합니다.
+
+Gemini 사용 시 목소리와 가격이 달라질 수 있습니다. 실제 AI 원가 × 호출 직전 적용 환율 × 1.4로 판매하고, 스킬은 기본요금(판매자 금액 + 기본 수수료) + AI 사용료입니다. Gemini 100만 토큰당 입력/출력 공급자 가격은 2026-12-31까지 $0.50/$6.00, 2027-01-01 00:00 UTC부터 $1.00/$12.00입니다. $0.54/시간은 출력 참고값이며 과금 단위가 아닙니다.
+
+`api.cost`는 접수 예약금을 확정액으로 표시하지 않습니다. `data.billing`의 `synthesis`, `skill`, `total`, `reserved`, `released`, `refunded`, `status`를 확인하세요. `voice_id`는 원래 요청을 보존하고 실제 엔진·모델·목소리는 `synthesis`에 표시합니다. 서버·공급자의 최종 제작 실패는 정규화까지 전액 환불합니다. 클라이언트 연결 종료는 정상 과금하고, 명시 취소는 이미 수행된 유료 처리분을 정산합니다.
+
+MP3 24kHz·모노·48kbps와 입력 원문 ASS를 완료 후 24시간 제공합니다. 파일별 한 번 다운로드, 중단 시 재시도가 가능합니다. 동일 요청의 접수 재시도에는 같은 `idempotencyKey`를 사용하세요. 이전 방식 작업의 품질·후보·재개 API는 해당 이전 작업에만 적용됩니다.
+
+[개발가이드](https://apick.app/dev_guide/tts) · [정규화 스킬](https://apick.app/skills/korean-text-normalize) · [공식 가격표](https://ai.google.dev/gemini-api/docs/pricing#gemini-3.8-flash-lite-tts)
+
+# TTS · English
+
+`createTtsJob` supports APICK synthesis and optional Gemini fallback. `createGeminiTtsJob` accepts Gemini voices, style, text or per-speaker utterances. All three paths share `getTtsJob`, `downloadTtsResult`, and `downloadTtsSubtitles`. The MP3/ASS format and response structure match; the generated voices differ.
+
+Fallback policies: `never` (default) queues APICK and returns 429 when its queue is full; `queue_full` uses Gemini only when the waiting queue is full; `busy` uses Gemini whenever immediate APICK execution is unavailable. `fallbackOptions.voice_id/style` apply only after fallback. Unsupported explicit voice IDs are rejected. `listGeminiTtsVoices` returns public basic and extended voices without case-alias duplicates, while existing aliases remain accepted. Automatic matching prioritizes Korean voices of the same gender, then the closest supported age band and vocal traits. `age_basis: catalog_description` refers to an age explicitly stated in the official voice description, not a real speaker's biological age. Voices without age evidence remain unverified.
+
+Text normalization is **on by default and costs extra**. Set `normalizeText: false` on SDK APICK options or `normalize_text: false` in a request body to skip both the skill and its charge. Normalization allows 2,000 characters across utterances including separating newlines. Gemini without normalization allows 8,000 characters; APICK retains its 800-character limit. The original spelling appears in ASS subtitles.
+
+External AI charges equal verified provider cost × the pinned USD/KRW exchange rate × 1.4. A skill adds its base fee once, including seller amount and base commission, without a second markup on AI usage. Gemini provider input/output prices per million tokens are $0.50/$6.00 through December 31, 2026, then $1.00/$12.00 from January 1, 2027, 00:00 UTC. The approximate $0.54/hour figure is informational, not a billing unit. Fallback may change the price and voice.
+
+Read the job's `billing` breakdown for reserved, released, captured, and refunded amounts. Submission `api.cost` does not treat a reservation as a final charge. Top-level `voice_id` preserves the APICK request; `synthesis` reports the actual provider/model/voice. Final server/provider failures refund synthesis and normalization. Disconnecting does not cancel background work or billing; explicit cancellation settles work already performed.
+
+Results are MP3 (24 kHz, mono, 48 kbps) and ASS, retained for 24 hours after completion. Each file permits one completed download; interrupted transfers may be retried. Reuse the same `idempotencyKey` and input after a lost submission response. Legacy quality/candidate/retry methods apply only to legacy jobs.

package/package.json

@@ -1,71 +1,71 @@
-{
-  "name": "apick-api",
-  "version": "3.9.0",
-  "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
-  "type": "module",
-  "main": "./src/index.cjs",
-  "module": "./src/index.js",
-  "types": "./src/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.js",
-      "require": "./src/index.cjs"
-    }
-  },
-  "files": [
-    "src",
-    "docs",
-    "examples",
-    "README.md",
-    "CHANGELOG.md",
-    "SECURITY.md",
-    "LICENSE"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test && npm run test:types",
-    "test:types": "tsc -p tsconfig.json",
-    "test:coverage": "node --test --experimental-test-coverage",
-    "prepublishOnly": "npm test"
-  },
-  "devDependencies": {
-    "typescript": "^7.0.2"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lead788/apick-api.git"
-  },
-  "bugs": {
-    "url": "https://github.com/lead788/apick-api/issues"
-  },
-  "homepage": "https://apick.app/dev_guide",
-  "license": "MIT",
-  "author": "APICK",
-  "publishConfig": {
-    "access": "public",
-    "provenance": false
-  },
-  "keywords": [
-    "apick",
-    "api",
-    "sdk",
-    "korea",
-    "korean-api",
-    "business-registry",
-    "parcel-tracking",
-    "address",
-    "ocr",
-    "whois",
-    "dns",
-    "google-search",
-    "pdf",
-    "excel",
-    "tts-jobs",
-    "text-summary",
-    "image-generation"
-  ]
-}
+{
+  "name": "apick-api",
+  "version": "3.11.0",
+  "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
+  "type": "module",
+  "main": "./src/index.cjs",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    }
+  },
+  "files": [
+    "src",
+    "docs",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test && npm run test:types",
+    "test:types": "tsc -p tsconfig.json",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lead788/apick-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lead788/apick-api/issues"
+  },
+  "homepage": "https://apick.app/dev_guide",
+  "license": "MIT",
+  "author": "APICK",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "keywords": [
+    "apick",
+    "api",
+    "sdk",
+    "korea",
+    "korean-api",
+    "business-registry",
+    "parcel-tracking",
+    "address",
+    "ocr",
+    "whois",
+    "dns",
+    "google-search",
+    "pdf",
+    "excel",
+    "tts-jobs",
+    "text-summary",
+    "image-generation"
+  ]
+}

package/src/index.cjs

@@ -63,7 +63,8 @@ const SERVICES = Object.freeze(Object.fromEntries(
 	])
 ));
 
-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***');
@@ -378,15 +379,17 @@ class ApickClient {
 			Accept: definition.output === 'binary' ? '*/*' : 'application/json',
 			Authorization: `Bearer ${this.#apiKey}`
 		};
-		const method = definition.method || 'POST';
+		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') {
-			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;
@@ -627,13 +630,26 @@ 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 || {};
-		return this._call('createTtsJob', {
-			voice_id: normalizeTtsVoice(config.voiceId || 'v2_ann_m_30s_01'),
-			text: requiredString('text', text, 800)
-		});
-	}
+	createTtsJob(text, options) {
+		const config = options || {};
+		const payload = typeof text==='object' && text!==null ? {...text} : {
+			voice_id: normalizeTtsVoice(config.voiceId || 'v2_ann_m_30s_01'),
+			text: requiredString('text', text, 800)
+		};
+		if(config.normalizeText!==undefined)payload.normalize_text=config.normalizeText;
+		if(config.fallbackPolicy!==undefined)payload.fallback_policy=config.fallbackPolicy;
+		if(config.fallbackOptions!==undefined)payload.fallback_options=config.fallbackOptions;
+		if(payload.normalize_text!==undefined&&typeof payload.normalize_text!=='boolean')throw new TypeError('normalizeText must be boolean.');
+		if(payload.fallback_policy!==undefined&&!['never','queue_full','busy'].includes(payload.fallback_policy))throw new TypeError('Invalid fallbackPolicy.');
+		return this._call('createTtsJob',payload,null,{json:typeof text==='object'||config.normalizeText!==undefined||config.fallbackPolicy!==undefined||config.fallbackOptions!==undefined,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'}); }
+	quoteTts(input) { return this._call('createTtsJob',input,null,{endpoint:'/rest/tts/quote',json:true}); }
 
 	getTtsJob(jobId) {
 		const id = normalizeTtsJobId(jobId);
@@ -949,10 +965,25 @@ class ApickClient {
 	}
 
 	getSkillPerformance() {
-		return this._skills('GET', '/skills/performance/data.json');
+		return this._skills('GET', '/skills/performance/data.json');
 	}
 
-	getSkill(skillId) {
+	_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

@@ -37,7 +37,8 @@ export interface ImageAiOptions { imageCount?: number; size?: ImageAiSize; outpu
 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 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 {
@@ -202,12 +203,23 @@ export interface YoutubeSubtitleOptions { format?: 'vtt' | 'srt' | 'txt'; type?:
 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 = typeof TTS_VOICE_IDS[number];
+export type TtsVoiceId = typeof TTS_VOICE_IDS[number];
+export type TtsFallbackPolicy = 'never' | 'queue_full' | 'busy';
+export interface TtsFallbackOptions { voice_id?: string; style?: string; }
+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 GeminiTtsInput { voice_id?:string; text?:string; style?:string; utterances?:Array<{text:string;voice_id?:string;style?:string;speaker?:string}>; normalize_text?:boolean; language_code?:'ko'|'ko-KR'; }
+export interface TtsOptions { voiceId?:TtsVoiceId; normalizeText?:boolean; fallbackPolicy?:TtsFallbackPolicy; fallbackOptions?:TtsFallbackOptions; 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?: TtsVoiceId;
+	voice_id?: string;
+	synthesis?: {engine:'apick'|'gemini';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;
@@ -290,7 +302,10 @@ 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, options?: { voiceId?: TtsVoiceId }): Promise<ApickResult<TtsJobData>>;
+	createTtsJob(text: string | ApickTtsInput, 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}>>;
+	quoteTts(input:(ApickTtsInput|GeminiTtsInput)&{engine?:'apick'|'gemini'}):Promise<ApickResult<TtsQuote>>;
 	getTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
 	cancelTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
 	downloadTtsResult(jobId: string): Promise<ApickBinaryResult>;
@@ -302,8 +317,8 @@ export class ApickClient {
 	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>>;
-	editImages(image:string|BinaryInput|ArrayBuffer|ArrayBufferView, prompt:string, options?:ImageAiEditOptions): Promise<ApickResult<ImageAiResultData>>;
+	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>>;
@@ -323,9 +338,22 @@ export class ApickClient {
 	getCashReceiptDeduction(transactionId: string): Promise<ApickResult<DataRequestResult<CashReceiptDeductionResultPayload>>>;
 	requestTaxReturnHistory(input: RequestTaxReturnHistoryInput): Promise<ApickResult<DataRequestAcceptedData>>;
 	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. */
+	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>>>;
 	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>>>;
@@ -341,38 +369,38 @@ export const SKILL_CATEGORIES: readonly ['data', 'ai', 'dev', 'document', 'marke
 export type SkillCategory = typeof SKILL_CATEGORIES[number];
 /** 검색 순서. 생략하면 등록 순서 / search order; registration order when omitted */
 export const SKILL_SORTS: readonly ['recommended', 'popular', 'used', 'likes', 'rating', 'new', 'mine', 'liked'];
-export type SkillSort = typeof SKILL_SORTS[number];
-export interface SkillPerformanceRate {
-	passed: number; total: number; percent: number; interval95: [number, number];
-}
-export interface SkillPerformanceReport {
-	schema_version: 1;
-	updated_at: string;
-	inventory_verified: boolean;
-	method: { minimum_cases: number; min_score: number; mean_score: number; min_improvement: number; critical_failures: number; description: string; limitations: string[]; interval_note: string; split: { normal: number; boundary: number; adversarial: number } };
-	calibration: { at: string; cases: number; true_positive: number; false_negative: number; false_positive: number; true_negative: number; automatic_release_allowed: boolean } | null;
-	additional_calibrations: Array<{ label: string; at: string; cases: number; detected: number; missed: number; false_positive: number; uncertain: number; automatic_release_allowed: boolean; scope: string }>;
-	skills: Array<{
-		key: string; title: string; group: string; origin: 'new' | 'existing'; published: boolean | null; url: string | null;
-		current: {
-			state: 'not_tested' | 'partial' | 'held' | 'passed' | 'stale'; at?: string;
-			cases: number; planned_cases: number; score: number | null; baseline_score: number | null;
-			score_samples?: number; evaluation_errors?: number;
-			delivery: SkillPerformanceRate | null; machine: SkillPerformanceRate | null;
-			median_seconds: number | null; p95_seconds: number | null; timing_samples?: number;
-			reasons: string[]; method?: string; sample_type?: string;
-			baseline_format_valid?: boolean;
-			evaluation_stage?: 'preliminary' | 'holdout';
-			dataset_composition?: { normal: number; boundary: number; adversarial: number; misplaced_rejections: number; valid: boolean };
-			min_score?: number | null; critical_cases?: number | null;
-			case_split?: { standard: number; boundary: number; adversarial: number };
-			extra_checks?: Array<{ name: string; passed: number; total: number }>;
-			tool_calls?: Array<{ label: string; samples: number; total: number | null; median: number | null; p95: number | null }>;
-			case_results?: Array<{ index: number; name: string; kind: 'standard' | 'boundary' | 'adversarial'; status: 'tested' | 'evaluation_error' | 'machine_only' | 'not_tested'; expected: 'success' | 'reject' | null; machine_pass: boolean; score: number | null; baseline_score: number | null; failed_checks: string[]; reason: string | null }>;
-		};
-		legacy: { cases: number; score: number; baseline_score: number; method: string; independent_holdout: false; at?: string } | null;
-	}>;
-}
+export type SkillSort = typeof SKILL_SORTS[number];
+export interface SkillPerformanceRate {
+	passed: number; total: number; percent: number; interval95: [number, number];
+}
+export interface SkillPerformanceReport {
+	schema_version: 1;
+	updated_at: string;
+	inventory_verified: boolean;
+	method: { minimum_cases: number; min_score: number; mean_score: number; min_improvement: number; critical_failures: number; description: string; limitations: string[]; interval_note: string; split: { normal: number; boundary: number; adversarial: number } };
+	calibration: { at: string; cases: number; true_positive: number; false_negative: number; false_positive: number; true_negative: number; automatic_release_allowed: boolean } | null;
+	additional_calibrations: Array<{ label: string; at: string; cases: number; detected: number; missed: number; false_positive: number; uncertain: number; automatic_release_allowed: boolean; scope: string }>;
+	skills: Array<{
+		key: string; title: string; group: string; origin: 'new' | 'existing'; published: boolean | null; url: string | null;
+		current: {
+			state: 'not_tested' | 'partial' | 'held' | 'passed' | 'stale'; at?: string;
+			cases: number; planned_cases: number; score: number | null; baseline_score: number | null;
+			score_samples?: number; evaluation_errors?: number;
+			delivery: SkillPerformanceRate | null; machine: SkillPerformanceRate | null;
+			median_seconds: number | null; p95_seconds: number | null; timing_samples?: number;
+			reasons: string[]; method?: string; sample_type?: string;
+			baseline_format_valid?: boolean;
+			evaluation_stage?: 'preliminary' | 'holdout';
+			dataset_composition?: { normal: number; boundary: number; adversarial: number; misplaced_rejections: number; valid: boolean };
+			min_score?: number | null; critical_cases?: number | null;
+			case_split?: { standard: number; boundary: number; adversarial: number };
+			extra_checks?: Array<{ name: string; passed: number; total: number }>;
+			tool_calls?: Array<{ label: string; samples: number; total: number | null; median: number | null; p95: number | null }>;
+			case_results?: Array<{ index: number; name: string; kind: 'standard' | 'boundary' | 'adversarial'; status: 'tested' | 'evaluation_error' | 'machine_only' | 'not_tested'; expected: 'success' | 'reject' | null; machine_pass: boolean; score: number | null; baseline_score: number | null; failed_checks: string[]; reason: string | null }>;
+		};
+		legacy: { cases: number; score: number; baseline_score: number; method: string; independent_holdout: false; at?: string } | null;
+	}>;
+}
 export type SkillRunStatus = 'queued' | 'running' | 'completing' | 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
 export type SkillBillingStatus = 'reserved' | 'captured' | 'released' | 'partially_refunded' | 'refunded';
 export type SkillFailureCode = 'EXECUTION_FAILED' | 'OUTPUT_INVALID' | 'TIMED_OUT' | 'CANCELLED' | 'UPSTREAM_UNAVAILABLE';
@@ -408,7 +436,7 @@ export interface SkillSummary {
 	/** 실행마다 같은 기본 금액 / base amount charged on every run */
 	price_points: number;
 	/** 사용량까지 더한 예상 금액 / estimated amount including usage */
-	estimated_points: number;
+	estimated_points: number | null;
 	/** true 면 실행마다 실제 사용량만큼 금액이 달라집니다 / amount varies per run with actual usage */
 	usage_priced: boolean;
 	seller: { name: string }; uses_generative_ai: boolean;
@@ -420,7 +448,9 @@ export interface SkillSummary {
 	rating_average: number | null;
 }
 export interface SkillDetail extends SkillSummary {
-	description: string; billing_rule: 'validated_result'; limits: SkillLimits;
+	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;
 }
@@ -480,3 +510,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>; }