apick-api 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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자로 확대했습니다.

package/README.md

@@ -72,6 +72,9 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `cancelTtsJob(jobId)` | 대기·생성 중 TTS 작업 취소 / Cancel waiting or processing TTS job | JSON |
 | `downloadTtsResult(jobId)` | TTS 결과 1회 다운로드 / One-time TTS result | MP3 |
 | `downloadTtsSubtitles(jobId)` | TTS 자막 1회 다운로드 / One-time TTS subtitles | ASS |
+| `getTtsQuality(jobId)` | 발화별 검수·후보 이력 / Utterance quality and candidates | JSON |
+| `retryTtsJob(jobId, utteranceIds, idempotencyKey)` | 같은 작업의 국소 복구 / Idempotent local recovery | JSON |
+| `downloadTtsCandidate(jobId, candidateId)` | 검수 후보 청취 / Candidate audio | WAV |
 | `htmlToPdf(html, options)` | HTML→PDF | Binary |
 | `jsonToExcel(data, options)` | JSON→Excel | Binary |
 | `summarize(text)` | 텍스트 요약 / Text summarization | JSON |
@@ -261,3 +264,36 @@ Error codes are one of `APICK_AUTH_ERROR`, `APICK_TIMEOUT`, `APICK_NETWORK_ERROR
 ## License
 
 MIT — see [LICENSE](LICENSE). Use of the APICK service is governed by the [APICK terms](https://apick.app/terms).
+
+## Video model versions
+
+Omitting `version` preserves Seedance 2.5, Veo 3.1 and Kling 3.0. Set `version` and `tier` explicitly to select a generation; jobs are never silently switched to another version. Submission and status responses include `version`.
+
+Available generations: Seedance 1.0/1.5/2.0/2.5, including Seedance 2.0 Standard/Fast/Mini; Veo 3.1 (Standard/Fast/Lite); Kling 1.6/2.0/2.1/2.5/2.6/3.0/O1/O3. Veo 3.0 is unavailable. Modes, tiers, resolutions, durations, audio, file limits and prices vary by combination. See the [Seedance](https://apick.app/dev_guide/seedancejobs), [Veo](https://apick.app/dev_guide/veojobs) and [Kling](https://apick.app/dev_guide/klingjobs) version tables. Unsupported combinations are rejected before submission.
+
+Seedance reference mode accepts `referenceImages`, `referenceVideos`, and `referenceAudios` (MP3/WAV) when supported by the selected version.
+
+## 영상 모델 버전 선택
+
+`version`을 생략하면 Seedance 2.5, Veo 3.1, Kling 3.0을 사용합니다. 버전과 등급을 명시하면 해당 조합으로 생성하며 다른 모델로 자동 대체하지 않습니다. 생성과 상태 응답의 `version`으로 확인할 수 있습니다.
+
+| 제품 | 제공 버전 | 제약과 요금 |
+|---|---|---|
+| Seedance | 2.5, 2.0(Standard·Fast·Mini), 1.5, 1.0 | [버전별 지원표](https://apick.app/dev_guide/seedancejobs) |
+| Veo | 3.1 (Standard, Fast, Lite) | [버전별 지원표](https://apick.app/dev_guide/veojobs) |
+| Kling | 3.0, O3, O1, 2.6, 2.5, 2.1, 2.0, 1.6 | [버전별 지원표](https://apick.app/dev_guide/klingjobs) |
+
+등급·해상도·길이·오디오·파일 개수와 초당 포인트는 선택 조합별로 다릅니다. Seedance 2.0은 Standard·Fast·Mini를 제공하며 Mini는 480p·720p와 4~15초를 지원합니다. 무음 전용 모델은 `audio=false`, 오디오 필수 모델은 `audio=true`만 허용합니다. Veo 3.0은 현재 제공하지 않습니다. 지원하지 않는 조합은 접수 전에 거절됩니다.
+
+Seedance 참조 소재 모드는 지원 버전에서 `referenceImages`, `referenceVideos`, `referenceAudios`(MP3·WAV)를 함께 사용할 수 있습니다.
+
+```js
+const job = await client.createVideoJob("kling", "A boat crossing the sea", {
+  version: "1.6", tier: "std", mode: "text", duration: 5, audio: false,
+  idempotencyKey: "boat-video-0001"
+});
+const status = await client.getVideoJob("kling", job.data.job_id);
+if (status.data.status === "completed") {
+  await (await client.downloadVideoResult("kling", job.data.job_id)).save("boat.mp4");
+}
+```

package/docs/guide.en.md

@@ -180,3 +180,27 @@ The document-specific methods are `maskResidenceCard`, `maskPassport`, `maskIdCa
 ## Errors and retries
 
 `ApickApiError` includes public error information: `code`, optional `serviceCode`, `status`, and `message`. The SDK does not retry automatically because a retry could duplicate an API call and its charge. If your application needs retries, decide explicitly after checking the error code and whether the operation is safe to repeat.
+# TTS quality and recovery
+
+Use `getTtsQuality(jobId)` to inspect utterance speed, rejection reasons, and candidate history. Candidates remain available for 72 hours after the job terminates. `downloadTtsCandidate(jobId, candidateId)` does not consume the final MP3 or ASS download.
+
+`retryTtsJob(jobId, ['u002'], idempotencyKey)` requests technical recovery within the same job without an additional charge. Reuse the same key and utterance list after a lost response. Check `resume_revision` to identify the current revision. Required quality checks must pass before a job completes.
+
+## Video model versions
+
+Omitting `version` preserves Seedance 2.5, Veo 3.1 and Kling 3.0. Set `version` and `tier` explicitly to select a generation; jobs are never silently switched to another version. Submission and status responses include `version`.
+
+Available generations: Seedance 1.0/1.5/2.0/2.5, including Seedance 2.0 Standard/Fast/Mini; Veo 3.1 (Standard/Fast/Lite); Kling 1.6/2.0/2.1/2.5/2.6/3.0/O1/O3. Veo 3.0 is unavailable. Seedance 2.0 Mini supports 480p/720p and 4–15 seconds. Modes, tiers, resolutions, durations, audio, file limits and prices vary by combination. See the [Seedance](https://apick.app/dev_guide/seedancejobs), [Veo](https://apick.app/dev_guide/veojobs) and [Kling](https://apick.app/dev_guide/klingjobs) version tables. Unsupported combinations are rejected before submission.
+
+Seedance reference mode accepts `referenceImages`, `referenceVideos`, and `referenceAudios` (MP3/WAV) when supported by the selected version.
+
+```js
+const job = await client.createVideoJob("kling", "A boat crossing the sea", {
+  version: "1.6", tier: "std", mode: "text", duration: 5, audio: false,
+  idempotencyKey: "boat-video-0001"
+});
+const status = await client.getVideoJob("kling", job.data.job_id);
+if (status.data.status === "completed") {
+  await (await client.downloadVideoResult("kling", job.data.job_id)).save("boat.mp4");
+}
+```

package/docs/guide.ko.md

@@ -182,3 +182,33 @@ console.log(result.data.result.fields);
 ## 오류와 재시도
 
 `ApickApiError`에는 공개 오류 정보인 `code`, `serviceCode`, `status`, `message`가 포함됩니다. SDK는 중복 호출과 중복 과금을 방지하기 위해 자동 재시도를 하지 않습니다. 재시도가 필요하면 작업의 멱등성과 오류 코드를 확인한 뒤 애플리케이션에서 명시적으로 결정하세요.
+# TTS 검수와 재개
+
+`getTtsQuality(jobId)`로 발화별 속도·실패 이유와 후보 목록을 조회합니다. 후보는 작업 종료 후 72시간 보존되며 `downloadTtsCandidate(jobId, candidateId)` 호출은 최종 MP3·ASS의 1회 다운로드를 소비하지 않습니다.
+
+`retryTtsJob(jobId, ['u002'], idempotencyKey)`는 해당 발화의 기술적 복구를 같은 작업에서 요청합니다. 응답이 끊겨도 같은 키와 발화 목록을 사용하세요. 기술적 복구는 추가 과금하지 않으며, 재개 회차는 `resume_revision`으로 확인합니다. 필수 검수를 통과하지 못한 작업은 완료되지 않습니다.
+
+## 영상 모델 버전 선택
+
+`version`을 생략하면 Seedance 2.5, Veo 3.1, Kling 3.0을 사용합니다. 버전과 등급을 명시하면 해당 조합으로 생성하며 다른 모델로 자동 대체하지 않습니다. 생성과 상태 응답의 `version`으로 확인할 수 있습니다.
+
+| 제품 | 제공 버전 | 제약과 요금 |
+|---|---|---|
+| Seedance | 2.5, 2.0(Standard·Fast·Mini), 1.5, 1.0 | [버전별 지원표](https://apick.app/dev_guide/seedancejobs) |
+| Veo | 3.1 (Standard, Fast, Lite) | [버전별 지원표](https://apick.app/dev_guide/veojobs) |
+| Kling | 3.0, O3, O1, 2.6, 2.5, 2.1, 2.0, 1.6 | [버전별 지원표](https://apick.app/dev_guide/klingjobs) |
+
+등급·해상도·길이·오디오·파일 개수와 초당 포인트는 선택 조합별로 다릅니다. Seedance 2.0은 Standard·Fast·Mini를 제공하며 Mini는 480p·720p와 4~15초를 지원합니다. 무음 전용 모델은 `audio=false`, 오디오 필수 모델은 `audio=true`만 허용합니다. Veo 3.0은 현재 제공하지 않습니다. 지원하지 않는 조합은 접수 전에 거절됩니다.
+
+Seedance 참조 소재 모드는 지원 버전에서 `referenceImages`, `referenceVideos`, `referenceAudios`(MP3·WAV)를 함께 사용할 수 있습니다.
+
+```js
+const job = await client.createVideoJob("kling", "A boat crossing the sea", {
+  version: "1.6", tier: "std", mode: "text", duration: 5, audio: false,
+  idempotencyKey: "boat-video-0001"
+});
+const status = await client.getVideoJob("kling", job.data.job_id);
+if (status.data.status === "completed") {
+  await (await client.downloadVideoResult("kling", job.data.job_id)).save("boat.mp4");
+}
+```

package/package.json

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

@@ -37,6 +37,7 @@ const SERVICE_DEFINITIONS = Object.freeze({
 	googleImageSearch: { endpoint: '/rest/google_image_search', timeoutMs: 35_000, output: 'json' },
 	screenshot: { endpoint: '/rest/url_screenshot', timeoutMs: 75_000, output: 'binary', filename: 'screenshot.jpeg' },
 	createTtsJob: { endpoint: '/rest/tts/jobs', timeoutMs: 35_000, output: 'json' },
+	createVideoJob: { endpoint: '/rest/seedance/jobs', timeoutMs: 60_000, output: 'json' },
 	htmlToPdf: { endpoint: '/rest/html_to_pdf', timeoutMs: 25_000, output: 'binary', filename: 'document.pdf' },
 	jsonToExcel: { endpoint: '/rest/json_to_excel', timeoutMs: 45_000, output: 'binary', filename: 'data.xlsx' },
 	summarize: { endpoint: '/rest/llm/text_summary', timeoutMs: 75_000, output: 'json' },
@@ -467,6 +468,52 @@ class ApickClient {
 		return this._call('screenshot', { url: normalizeUrl(url) });
 	}
 
+	async createVideoJob(model, prompt, options) {
+		if (!['seedance', 'veo', 'kling'].includes(model)) throw new RangeError('model must be seedance, veo or kling.');
+		const config = options || {};
+		const payload = { prompt: config.mode === 'reference' && prompt === '' ? '' : requiredString('prompt', prompt, 2000) };
+		for (const [key, field] of Object.entries({ version:'version', tier:'tier', mode:'mode', duration:'duration', aspectRatio:'aspect_ratio', resolution:'resolution', audio:'audio', negativePrompt:'negative_prompt', seed:'seed', cfgScale:'cfg_scale', idempotencyKey:'idempotency_key' })) {
+			if (config[key] !== undefined) payload[field] = config[key];
+		}
+		const files = [['image', config.image], ['last_image', config.lastImage]];
+		for (const input of config.referenceImages || []) files.push(['reference_image', input]);
+		for (const input of config.referenceVideos || []) files.push(['reference_video', input]);
+		for (const input of config.referenceAudios || []) files.push(['reference_audio', input]);
+		const present = files.filter(([, input]) => input !== undefined);
+		const request = { endpoint: '/rest/' + model + '/jobs' };
+		if (!present.length) return this._call('createVideoJob', payload, null, request);
+		const form = new FormData();
+		for (const [key, value] of Object.entries(payload)) form.append(key, String(value));
+		for (const [field, input] of present) {
+			if (field !== 'reference_video' && field !== 'reference_audio') {
+				const upload = await normalizeImage(input);
+				form.append(field, upload.blob, upload.filename);
+			} else {
+				let bytes, filename, contentType;
+				if (typeof input === 'string') {
+					bytes = await require('node:fs/promises').readFile(input);
+					filename = require('node:path').basename(input);
+					contentType = field === 'reference_audio' ? (/\.wav$/i.test(filename) ? 'audio/wav' : 'audio/mpeg') : /\.webm$/i.test(filename) ? 'video/webm' : /\.mov$/i.test(filename) ? 'video/quicktime' : 'video/mp4';
+				} else { bytes = await input.arrayBuffer(); filename = input.name || (field === 'reference_audio' ? 'reference.mp3' : 'reference.mp4'); contentType = input.type || (field === 'reference_audio' ? 'audio/mpeg' : 'video/mp4'); }
+				const allowed = field === 'reference_audio' ? ['audio/mpeg', 'audio/wav', 'audio/x-wav'] : ['video/mp4', 'video/quicktime', 'video/webm'];
+				const maxBytes = field === 'reference_audio' ? 15 * 1024 * 1024 : 100 * 1024 * 1024;
+				if (!allowed.includes(contentType) || bytes.byteLength < 1 || bytes.byteLength > maxBytes) throw new RangeError(field === 'reference_audio' ? 'Invalid reference audio.' : 'Invalid reference video.');
+				form.append(field, new Blob([bytes], { type: contentType }), filename);
+			}
+		}
+		return this._call('createVideoJob', null, form, request);
+	}
+
+	getVideoJob(model, jobId) {
+		if (!['seedance', 'veo', 'kling'].includes(model) || !/^[a-f0-9]{32}$/.test(jobId)) throw new RangeError('Invalid video model or job ID.');
+		return this._call('createVideoJob', null, null, { endpoint:'/rest/'+model+'/jobs/'+jobId, method:'GET', timeoutMs:30_000 });
+	}
+
+	downloadVideoResult(model, jobId) {
+		if (!['seedance', 'veo', 'kling'].includes(model) || !/^[a-f0-9]{32}$/.test(jobId)) throw new RangeError('Invalid video model or job ID.');
+		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', {
@@ -485,6 +532,30 @@ class ApickClient {
 		return this._call('createTtsJob', null, null, { endpoint: '/rest/tts/jobs/' + id + '/cancel' });
 	}
 
+	getTtsQuality(jobId) {
+		const id = normalizeTtsJobId(jobId);
+		return this._call('createTtsJob', null, null, { endpoint: '/rest/tts/jobs/' + id + '/quality', method: 'GET' });
+	}
+
+	retryTtsJob(jobId, utteranceIds, idempotencyKey) {
+		const id = normalizeTtsJobId(jobId);
+		if (!Array.isArray(utteranceIds) || utteranceIds.length > 100 || utteranceIds.some(value => typeof value !== 'string' || !/^u\d{3}$/.test(value))) {
+			throw new TypeError('utteranceIds must contain up to 100 uNNN identifiers.');
+		}
+		if (typeof idempotencyKey !== 'string' || !/^[A-Za-z0-9_-]{8,128}$/.test(idempotencyKey)) {
+			throw new TypeError('idempotencyKey must contain 8 to 128 letters, digits, underscores or hyphens.');
+		}
+		return this._call('createTtsJob', { utterance_ids: [...new Set(utteranceIds)].sort(), idempotency_key: idempotencyKey }, null,
+			{ endpoint: '/rest/tts/jobs/' + id + '/retry' });
+	}
+
+	downloadTtsCandidate(jobId, candidateId) {
+		const id = normalizeTtsJobId(jobId);
+		if (typeof candidateId !== 'string' || !/^[a-f0-9]{32}$/.test(candidateId)) throw new TypeError('candidateId must be a 32-character hexadecimal identifier.');
+		return this._call('createTtsJob', null, null, { endpoint: '/rest/tts/jobs/' + id + '/candidates/' + candidateId + '/audio',
+			method: 'GET', output: 'binary', filename: candidateId + '.wav' });
+	}
+
 	downloadTtsResult(jobId) {
 		const id = normalizeTtsJobId(jobId);
 		return this._call('createTtsJob', null, null, {

package/src/index.d.ts

@@ -59,6 +59,21 @@ export interface TtsJobData {
 	character_count?: number;
 	result_available?: boolean;
 	subtitles_available?: boolean;
+	resume_revision?: number;
+	operation_revision?: number;
+	quality?: TtsQualityData | null;
+}
+
+export interface TtsQualityData {
+	job_id?: string;
+	resume_revision?: number;
+	phase?: string;
+	accepted_utterances?: number;
+	failed_utterances?: number;
+	total_utterances?: number;
+	utterances?: Array<{ id: string; status: string; attempt?: number; reasons?: string[];
+		speech_rate?: { chars: number; duration_sec: number; cps: number; expected_sec: number; duration_ratio: number | null; status: string } }>;
+	candidates?: Array<{ candidate_id: string; utterance_id: string; status: string; attempt: number; audio_available?: boolean }>;
 }
 
 export class ApickApiError extends Error {
@@ -93,6 +108,9 @@ export const SERVICES: Readonly<Record<string, Readonly<{
 }>>>;
 
 export class ApickClient {
+	createVideoJob(model: VideoModel, prompt: string, options?: VideoJobOptions): Promise<ApickResult<VideoJobData>>;
+	getVideoJob(model: VideoModel, jobId: string): Promise<ApickResult<VideoJobData>>;
+	downloadVideoResult(model: VideoModel, jobId: string): Promise<ApickBinaryResult>;
 	constructor(apiKeyOrOptions: string | ApickClientOptions);
 	businessDetails(businessNumber: string): Promise<ApickResult>;
 	ventureBusiness(businessNumber: string): Promise<ApickResult>;
@@ -119,6 +137,9 @@ export class ApickClient {
 	cancelTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
 	downloadTtsResult(jobId: string): Promise<ApickBinaryResult>;
 	downloadTtsSubtitles(jobId: string): Promise<ApickBinaryResult>;
+	getTtsQuality(jobId: string): Promise<ApickResult<TtsQualityData>>;
+	retryTtsJob(jobId: string, utteranceIds: string[], idempotencyKey: string): Promise<ApickResult<TtsJobData>>;
+	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>;
@@ -133,3 +154,23 @@ export class ApickClient {
 }
 
 export default ApickClient;
+
+export type VideoModel = 'seedance' | 'veo' | 'kling';
+export interface VideoJobOptions {
+	version?: string; tier?: string; mode?: 'text' | 'image' | 'reference'; duration?: number;
+	aspectRatio?: string; resolution?: string; audio?: boolean; negativePrompt?: string;
+	seed?: number; cfgScale?: number; idempotencyKey?: string;
+	image?: string | BinaryInput | ArrayBuffer | ArrayBufferView;
+	lastImage?: string | BinaryInput | ArrayBuffer | ArrayBufferView;
+	referenceImages?: Array<string | BinaryInput | ArrayBuffer | ArrayBufferView>;
+	referenceVideos?: Array<string | BinaryInput>;
+	referenceAudios?: Array<string | BinaryInput>;
+}
+export interface VideoJobData {
+	job_id: string; model: VideoModel; version: string; mode: string; tier: string;
+	status: 'waiting' | 'processing' | 'completed' | 'failed' | 'cancelled';
+	duration: number; resolution?: string; audio?: boolean; point_per_second?: number;
+	charged_point?: number; result_available?: boolean; result_url?: string;
+	result_expires_at?: string | null; idempotent_replay?: boolean;
+	error?: { code: string; message: string };
+}