apick-api 3.10.0 → 3.11.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 3.11.0
+
+- 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`에 누적됩니다.
+
+- 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 메서드와 타입을 추가했습니다. 설치형 스킬의 사용량 과금 정보를 제공합니다.

package/README.md

@@ -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
 
@@ -479,3 +479,6 @@ 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/docs/guide.en.md

@@ -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

@@ -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/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,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "3.10.0",
+  "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",

package/src/index.cjs

@@ -379,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;
@@ -628,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);

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