apick-api 2.2.0 → 2.3.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.3.1 - 2026-09-05
+
+- 이미지 편집 입력에서 마스크 파일을 제거하고 원본 이미지와 프롬프트만 받도록 계약을 단순화했습니다.
+
+## 2.3.0 - 2026-09-05
+
+- 이미지 생성·편집과 최대 50장 비동기 작업 메서드 8종을 추가했습니다.
+- 이미지당 25포인트, 성공분 과금, 멱등 키, 24시간 결과 보관 계약을 문서화했습니다.
+
 ## 2.2.0 - 2026-09-03
 
 - `maskResidenceCard()`의 개인정보 마스킹 대상을 외국인등록증·영주증·외국국적동포 국내거소신고증으로 확대했습니다.

package/README.md

@@ -2,9 +2,9 @@
 
 # APICK API for Node.js
 
-**에이픽 주요 API 25개를 API 키 하나로 간편하게 호출하는 공식 Node.js SDK**
+**에이픽 데이터·AI·이미지 API를 API 키 하나로 호출하는 공식 Node.js SDK**
 
-**Official zero-dependency Node.js SDK for 25 popular APICK Korean data and AI APIs**
+**Official zero-dependency Node.js SDK for APICK data, AI, and image APIs**
 
 [![npm](https://img.shields.io/npm/v/apick-api?color=%230a7cff&label=npm%20apick-api)](https://www.npmjs.com/package/apick-api)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933)](https://nodejs.org/)
@@ -76,6 +76,13 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `jsonToExcel(data, options)` | JSON→Excel | Binary |
 | `summarize(text)` | 텍스트 요약 / Text summarization | JSON |
 | `polish(text)` | 텍스트 다듬기 / Text polishing | JSON |
+| `generateImages(prompt, options)` | 이미지 생성 / Image generation | JSON |
+| `editImages(image, prompt, options)` | 이미지 편집 / Image editing | JSON |
+| `createImageGenerationJob(prompt, options)` | 대량 이미지 생성 작업 / Batch generation job | JSON |
+| `createImageEditJob(image, prompt, options)` | 대량 이미지 편집 작업 / Batch edit job | JSON |
+| `getImageJob(jobId)` · `cancelImageJob(jobId)` | 이미지 작업 조회·취소 / Job status and cancellation | JSON |
+| `downloadImageJobImage(jobId, index)` | 개별 결과 / Individual result | Binary |
+| `downloadImageJobArchive(jobId)` | ZIP 결과 / ZIP archive | Binary |
 
 ## JSON 결과 / JSON results
 
@@ -92,6 +99,32 @@ console.log(result.meta);
 
 ## 파일 입력 / File input
 
+## 이미지 생성·편집 / Image generation and editing
+
+이미지는 장당 25포인트이며 동기는 1~4장, 작업형 API는 최대 50장까지 지원합니다. 성공적으로 저장된 이미지에 대해서만 과금되며 결과는 완료 후 24시간 동안 반복 다운로드할 수 있습니다.
+
+Images cost 25 points each. Synchronous calls support 1–4 images and job calls support up to 50. Only stored successful results are charged, and completed job results remain downloadable for 24 hours.
+
+```js
+const made = await apick.generateImages("따뜻한 조명의 미니멀 제품 사진", {
+  count: 2, size: "1024x1024", outputFormat: "webp",
+  idempotencyKey: "catalog-cover-20260905"
+});
+
+const edited = await apick.editImages("./source.png", "컵 색상을 파란색으로 변경", {
+  outputFormat: "png"
+});
+
+const queued = await apick.createImageGenerationJob("여행 포스터 시안", { count: 20 });
+const job = await apick.getImageJob(queued.data.job_id);
+const image = await apick.downloadImageJobImage(job.data.job_id, 0);
+await image.save("./result.png");
+```
+
+PNG·JPEG·WebP 출력, 투명 배경 미리보기(PNG/WebP), 표준 및 사용자 지정 크기를 지원합니다. 입력 프롬프트는 최대 6,000자입니다. 자동 재시도는 하지 않습니다.
+
+PNG, JPEG, and WebP outputs, transparent-background previews for PNG/WebP, and standard or custom sizes are supported. Prompts are limited to 6,000 characters. Requests are never retried automatically.
+
 OCR은 PNG/JPEG 파일 경로, `Blob`, `ArrayBuffer`, `Uint8Array`를 받습니다. 최대 크기는 50MB입니다.
 OCR accepts a PNG/JPEG file path, `Blob`, `ArrayBuffer`, or `Uint8Array`, up to 50MB.
 

package/docs/guide.en.md

@@ -123,6 +123,22 @@ const polished = await client.polish(draftText);
 
 Text input is limited to 100,000 characters.
 
+## Image AI
+
+```js
+const result = await client.generateImages('A clean product photo on white', {
+  count: 4, size: '1024x1024', outputFormat: 'webp',
+  idempotencyKey: 'product-draft-001'
+});
+
+const job = await client.createImageGenerationJob('Landscape article cover concepts', { count: 20, size: '1536x1024' });
+const status = await client.getImageJob(job.data.job_id);
+```
+
+Synchronous generation and editing support 1–4 images; job methods support 1–50. Editing accepts one PNG, JPEG, or WebP source up to 50 MB plus a prompt; mask files are not supported. Each stored successful image costs 25 points, while reservations for failed or cancelled items are released. Results remain available for 24 hours.
+
+Methods: `generateImages`, `editImages`, `createImageGenerationJob`, `createImageEditJob`, `getImageJob`, `cancelImageJob`, `downloadImageJobImage`, and `downloadImageJobArchive`.
+
 ## Response shape
 
 JSON methods resolve to:

package/docs/guide.ko.md

@@ -123,6 +123,24 @@ const polished = await client.polish(draftText);
 
 입력 텍스트는 최대 100,000자입니다.
 
+## 이미지 AI
+
+```js
+const result = await client.generateImages('흰 배경의 제품 사진', {
+  count: 4,
+  size: '1024x1024',
+  outputFormat: 'webp',
+  idempotencyKey: 'product-draft-001'
+});
+
+const job = await client.createImageGenerationJob('가로형 커버 시안', { count: 20, size: '1536x1024' });
+const status = await client.getImageJob(job.data.job_id);
+```
+
+동기 생성·편집은 1~4장, 작업형 생성·편집은 1~50장입니다. 편집은 50MB 이하의 PNG/JPEG/WebP 원본 이미지 한 장과 프롬프트를 받으며 마스크 파일은 지원하지 않습니다. 성공 이미지 한 장당 25포인트가 확정되며 실패·취소 수량의 예약 포인트는 해제됩니다. 결과 보관 기간은 완료 후 24시간입니다.
+
+지원 메서드: `generateImages`, `editImages`, `createImageGenerationJob`, `createImageEditJob`, `getImageJob`, `cancelImageJob`, `downloadImageJobImage`, `downloadImageJobArchive`.
+
 ## 응답 구조
 
 JSON 메서드:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apick-api",
-  "version": "2.2.0",
-  "description": "Official zero-dependency Node.js client for 25 APICK APIs. 에이픽 주요 API 25개를 간편하게 호출하는 공식 Node.js SDK.",
+  "version": "2.3.1",
+  "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
   "type": "module",
   "main": "./src/index.cjs",
   "module": "./src/index.js",
@@ -27,14 +27,14 @@
     "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"
+    "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"
   },
-	"devDependencies": {
-		"typescript": "^7.0.2"
-	},
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lead788/apick-api.git"
@@ -65,6 +65,7 @@
     "pdf",
     "excel",
     "tts-jobs",
-    "text-summary"
+    "text-summary",
+    "image-generation"
   ]
 }

package/src/index.cjs

@@ -3,6 +3,7 @@
 const DEFAULT_BASE_URL = 'https://apick.app';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_OCR_BYTES = 50 * 1024 * 1024;
+const MAX_IMAGE_AI_BYTES = 50 * 1024 * 1024;
 const TTS_VOICE_IDS = Object.freeze([
 	'narrator_m_01', 'narrator_m_02', 'narrator_m_03', 'narrator_m_04', 'narrator_m_05',
 	'narrator_f_10s_01', 'narrator_f_10s_02', 'narrator_f_10s_03',
@@ -37,7 +38,8 @@ const SERVICE_DEFINITIONS = Object.freeze({
 	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' },
-	polish: { endpoint: '/rest/llm/text_polish', timeoutMs: 105_000, output: 'json' }
+	polish: { endpoint: '/rest/llm/text_polish', timeoutMs: 105_000, output: 'json' },
+	generateImages: { endpoint: '/rest/image-generation/generate', timeoutMs: 190_000, output: 'json' }
 });
 
 const SERVICES = Object.freeze(Object.fromEntries(
@@ -151,6 +153,7 @@ function inferImageType(filename) {
 	const lower = String(filename || '').toLowerCase();
 	if (lower.endsWith('.png')) return 'image/png';
 	if (lower.endsWith('.jpg') || lower.endsWith('.jpeg')) return 'image/jpeg';
+	if (lower.endsWith('.webp')) return 'image/webp';
 	return '';
 }
 
@@ -182,10 +185,11 @@ async function normalizeImage(image, options) {
 	}
 
 	const contentType = config.contentType || blob.type || inferImageType(filename);
-	if (contentType !== 'image/png' && contentType !== 'image/jpeg') {
-		throw new TypeError('OCR supports PNG and JPEG images only.');
+	const allowedTypes = config.allowedTypes || ['image/png', 'image/jpeg'];
+	if (!allowedTypes.includes(contentType)) {
+		throw new TypeError(config.typeError || 'OCR supports PNG and JPEG images only.');
 	}
-	if (blob.size > MAX_OCR_BYTES) {
+	if (blob.size > (config.maxBytes || MAX_OCR_BYTES)) {
 		throw new RangeError('image must not exceed 50 MB.');
 	}
 	return { blob, filename, contentType };
@@ -522,6 +526,73 @@ class ApickClient {
 	polish(text) {
 		return this._call('polish', { text: requiredString('text', text, 100_000) });
 	}
+
+	_imageOptions(prompt, options, maxCount) {
+		const config = options || {};
+		for (const key of ['model', 'quality', 'n', 'input_fidelity', 'moderation', 'mask', 'maskFilename', 'maskContentType']) {
+			if (Object.prototype.hasOwnProperty.call(config, key)) throw new TypeError(`${key} is not a supported image option.`);
+		}
+		const count = positiveInteger('count', config.count, 1);
+		if (count > maxCount) throw new RangeError(`count must not exceed ${maxCount}.`);
+		const payload = {
+			prompt: requiredString('prompt', prompt, 6_000), count,
+			size: config.size || '1024x1024', output_format: config.outputFormat || 'png',
+			background: config.background || 'auto'
+		};
+		if (config.outputCompression !== undefined) payload.output_compression = config.outputCompression;
+		if (config.idempotencyKey !== undefined) {
+			payload.idempotency_key = requiredString('idempotencyKey', config.idempotencyKey, 128);
+			if (!/^[A-Za-z0-9_-]{8,128}$/.test(payload.idempotency_key)) throw new TypeError('idempotencyKey must use 8-128 letters, numbers, underscores, or hyphens.');
+		}
+		return payload;
+	}
+
+	generateImages(prompt, options) {
+		return this._call('generateImages', this._imageOptions(prompt, options, 4));
+	}
+
+	async editImages(image, prompt, options) {
+		const config = options || {}, payload = this._imageOptions(prompt, config, 4);
+		const uploadOptions = Object.assign({}, config, { allowedTypes:['image/png','image/jpeg','image/webp'], maxBytes:MAX_IMAGE_AI_BYTES, typeError:'image must be PNG, JPEG, or WebP.' });
+		const source = await normalizeImage(image, uploadOptions), form = new FormData();
+		Object.entries(payload).forEach(([key,value]) => form.append(key, String(value)));
+		form.append('image', source.blob, source.filename);
+		return this._call('generateImages', null, form, { endpoint:'/rest/image-generation/edit' });
+	}
+
+	createImageGenerationJob(prompt, options) {
+		return this._call('generateImages', this._imageOptions(prompt, options, 50), null, { endpoint:'/rest/image-generation/jobs/generate', timeoutMs:60_000 });
+	}
+
+	async createImageEditJob(image, prompt, options) {
+		const config = options || {}, payload = this._imageOptions(prompt, config, 50);
+		const uploadOptions = Object.assign({}, config, { allowedTypes:['image/png','image/jpeg','image/webp'], maxBytes:MAX_IMAGE_AI_BYTES, typeError:'image must be PNG, JPEG, or WebP.' });
+		const source = await normalizeImage(image, uploadOptions), form = new FormData();
+		Object.entries(payload).forEach(([key,value]) => form.append(key, String(value)));
+		form.append('image', source.blob, source.filename);
+		return this._call('generateImages', null, form, { endpoint:'/rest/image-generation/jobs/edit', timeoutMs:60_000 });
+	}
+
+	getImageJob(jobId) {
+		const id = normalizeTtsJobId(jobId);
+		return this._call('generateImages', null, null, { endpoint:'/rest/image-generation/jobs/'+id, method:'GET', timeoutMs:30_000 });
+	}
+
+	cancelImageJob(jobId) {
+		const id = normalizeTtsJobId(jobId);
+		return this._call('generateImages', null, null, { endpoint:'/rest/image-generation/jobs/'+id+'/cancel', timeoutMs:30_000 });
+	}
+
+	downloadImageJobImage(jobId, index) {
+		const id=normalizeTtsJobId(jobId), value=Number(index);
+		if(!Number.isInteger(value)||value<0||value>49) throw new RangeError('index must be an integer from 0 through 49.');
+		return this._call('generateImages', null, null, { endpoint:'/rest/image-generation/jobs/'+id+'/images/'+value, method:'GET', output:'binary', filename:id+'-'+value+'.bin', timeoutMs:60_000 });
+	}
+
+	downloadImageJobArchive(jobId) {
+		const id=normalizeTtsJobId(jobId);
+		return this._call('generateImages', null, null, { endpoint:'/rest/image-generation/jobs/'+id+'/result', method:'GET', output:'binary', filename:id+'.zip', timeoutMs:60_000 });
+	}
 }
 
 module.exports = {

package/src/index.d.ts

@@ -27,6 +27,16 @@ export interface OcrOptions {
 	contentType?: 'image/png' | 'image/jpeg';
 }
 
+export type ImageAiFormat = 'png' | 'jpeg' | 'webp';
+export type ImageAiBackground = 'auto' | 'opaque' | 'transparent';
+export type ImageAiStatus = 'waiting' | 'processing' | 'completed' | 'completed_partial' | 'cancelled' | 'failed';
+export type ApickImageErrorCode = `APICK_IMAGE_${string}`;
+export interface ImageAiOptions { count?: number; size?: string; outputFormat?: ImageAiFormat; background?: ImageAiBackground; outputCompression?: number; idempotencyKey?: string; }
+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; count:number; images:ImageAiResultImage[]; idempotent_replay?:boolean; }
+export interface ImageAiJobData { job_id:string; status:ImageAiStatus; requested_count:number; completed_count?:number; failed_count?:number; charged_point?:number; result_available?:boolean; expires_at?:string|null; error_code?:ApickImageErrorCode|null; }
+
 export interface MaskResidentNumberOptions extends OcrOptions {
 	type: 1 | 2 | 3;
 }
@@ -111,6 +121,14 @@ 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?:ImageAiOptions): Promise<ApickResult<ImageAiResultData>>;
+	editImages(image:string|BinaryInput|ArrayBuffer|ArrayBufferView, prompt:string, options?:ImageAiEditOptions): Promise<ApickResult<ImageAiResultData>>;
+	createImageGenerationJob(prompt:string, options?:ImageAiOptions): Promise<ApickResult<ImageAiJobData>>;
+	createImageEditJob(image:string|BinaryInput|ArrayBuffer|ArrayBufferView, prompt:string, options?:ImageAiEditOptions): Promise<ApickResult<ImageAiJobData>>;
+	getImageJob(jobId:string): Promise<ApickResult<ImageAiJobData>>;
+	cancelImageJob(jobId:string): Promise<ApickResult<ImageAiJobData>>;
+	downloadImageJobImage(jobId:string,index:number): Promise<ApickBinaryResult>;
+	downloadImageJobArchive(jobId:string): Promise<ApickBinaryResult>;
 }
 
 export default ApickClient;