apick-api 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2.4.0 - 2026-09-05
+
+- 이미지 장수 옵션을 의미가 분명한 `imageCount`로 바꾸고 압축 조정 옵션을 제거했습니다.
+- 이미지 크기를 5개 표준 크기 중에서만 선택하도록 타입과 런타임 검증을 강화했습니다.
+- 생성 요청에 선택적 `referenceImage`를 더해 참고 이미지와 텍스트를 함께 사용할 수 있습니다.
+
+## 2.3.1 - 2026-09-05
+
+- 이미지 편집 입력에서 마스크 파일을 제거하고 원본 이미지와 프롬프트만 받도록 계약을 단순화했습니다.
+
+## 2.3.0 - 2026-09-05
+
+- 이미지 생성·편집과 최대 50장 비동기 작업 메서드 8종을 추가했습니다.
+- 이미지당 25포인트, 성공분 과금, 멱등 키, 24시간 결과 보관 계약을 문서화했습니다.
+
 ## 2.2.0 - 2026-09-03
 
 - `maskResidenceCard()`의 개인정보 마스킹 대상을 외국인등록증·영주증·외국국적동포 국내거소신고증으로 확대했습니다.

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,38 @@ 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("따뜻한 조명의 미니멀 제품 사진", {
+  imageCount: 2, size: "1024x1024", outputFormat: "webp",
+  idempotencyKey: "catalog-cover-20260905"
+});
+
+const referenced = await apick.generateImages("구도와 제품 형태는 유지하고 여름 해변 분위기로", {
+  referenceImage: "./reference.png",
+  referenceFilename: "reference.png",
+  referenceContentType: "image/png"
+});
+
+const edited = await apick.editImages("./source.png", "컵 색상을 파란색으로 변경", {
+  outputFormat: "png"
+});
+
+const queued = await apick.createImageGenerationJob("여행 포스터 시안", { imageCount: 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), 5개 표준 크기(`1024x1024`, `1536x1024`, `1024x1536`, `1152x864`, `864x1152`)를 지원합니다. 입력 프롬프트는 최대 6,000자입니다. `idempotencyKey`는 네트워크 재전송 때 중복 생성과 중복 과금을 막는 8~128자의 요청 식별자이며, 같은 작업을 다시 보낼 때 같은 값을 사용합니다. 자동 재시도는 하지 않습니다.
+
+PNG, JPEG, and WebP outputs, transparent-background previews for PNG/WebP, and five standard sizes are supported. Prompts are limited to 6,000 characters. `idempotencyKey` identifies the same request during network retransmission to prevent duplicate generation and billing. 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,30 @@ 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', {
+  imageCount: 4, size: '1024x1024', outputFormat: 'webp',
+  idempotencyKey: 'product-draft-001'
+});
+
+const referenceResult = await client.generateImages('Keep the product shape and composition, and change the background to a sunny kitchen', {
+  referenceImage: './reference.png',
+  referenceFilename: 'reference.png',
+  referenceContentType: 'image/png'
+});
+
+const job = await client.createImageGenerationJob('Landscape article cover concepts', { imageCount: 20, size: '1536x1024' });
+const status = await client.getImageJob(job.data.job_id);
+```
+
+`imageCount` is the number of images to make and defaults to one. Synchronous generation and editing support 1–4 images; job methods support 1–50. Add `referenceImage` to generation when the prompt should build from an existing composition, palette, or product shape. Editing accepts one PNG, JPEG, or WebP source up to 50 MB plus a prompt; mask files are not supported. Choose one of five sizes: `1024x1024`, `1536x1024`, `1024x1536`, `1152x864`, or `864x1152`. Each stored successful image costs 25 points, while reservations for failed or cancelled items are released. Results remain available for 24 hours.
+
+`idempotencyKey` is a safety identifier that prevents duplicate generation and billing if a network problem sends the same request twice. Use 8–128 letters, numbers, underscores, or hyphens. Reuse it only for the exact same request and create a new value when the prompt or options change.
+
+Methods: `generateImages`, `editImages`, `createImageGenerationJob`, `createImageEditJob`, `getImageJob`, `cancelImageJob`, `downloadImageJobImage`, and `downloadImageJobArchive`.
+
 ## Response shape
 
 JSON methods resolve to:

package/docs/guide.ko.md

@@ -123,6 +123,32 @@ const polished = await client.polish(draftText);
 
 입력 텍스트는 최대 100,000자입니다.
 
+## 이미지 AI
+
+```js
+const result = await client.generateImages('흰 배경의 제품 사진', {
+  imageCount: 4,
+  size: '1024x1024',
+  outputFormat: 'webp',
+  idempotencyKey: 'product-draft-001'
+});
+
+const referenceResult = await client.generateImages('제품 모양과 구도는 유지하고 배경을 햇살 좋은 주방으로 변경', {
+  referenceImage: './reference.png',
+  referenceFilename: 'reference.png',
+  referenceContentType: 'image/png'
+});
+
+const job = await client.createImageGenerationJob('가로형 커버 시안', { imageCount: 20, size: '1536x1024' });
+const status = await client.getImageJob(job.data.job_id);
+```
+
+`imageCount`는 만들 이미지 장수이며 생략하면 1장입니다. 동기 생성·편집은 1~4장, 작업형 생성·편집은 1~50장입니다. 생성에 `referenceImage`를 함께 전달하면 참고 이미지의 구도·색감·제품 형태 등을 프롬프트와 조합할 수 있습니다. 편집은 50MB 이하의 PNG/JPEG/WebP 원본 이미지 한 장과 프롬프트를 받으며 마스크 파일은 지원하지 않습니다. 크기는 `1024x1024`, `1536x1024`, `1024x1536`, `1152x864`, `864x1152` 중에서 선택합니다. 성공 이미지 한 장당 25포인트가 확정되며 실패·취소 수량의 예약 포인트는 해제됩니다. 결과 보관 기간은 완료 후 24시간입니다.
+
+`idempotencyKey`는 같은 요청이 통신 오류로 두 번 전송됐을 때 중복 생성과 중복 과금을 막는 안전번호입니다. 영문·숫자·밑줄·하이픈으로 8~128자를 만들고, 같은 작업을 다시 보낼 때는 같은 값을 사용하세요. 프롬프트나 옵션이 달라진 새 작업에는 새 값을 사용해야 합니다.
+
+지원 메서드: `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.4.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",
@@ -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,9 @@
 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 IMAGE_AI_SIZES = Object.freeze(['1024x1024', '1536x1024', '1024x1536', '1152x864', '864x1152']);
+const IMAGE_AI_SIZE_SET = new Set(IMAGE_AI_SIZES);
 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 +40,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 +155,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 +187,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 +528,94 @@ 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', 'count', 'n', 'outputCompression', 'input_fidelity', 'moderation', 'mask', 'maskFilename', 'maskContentType']) {
+			if (Object.prototype.hasOwnProperty.call(config, key)) throw new TypeError(`${key} is not a supported image option.`);
+		}
+		const imageCount = positiveInteger('imageCount', config.imageCount, 1);
+		if (imageCount > maxCount) throw new RangeError(`imageCount must not exceed ${maxCount}.`);
+		const size = config.size || '1024x1024';
+		if (!IMAGE_AI_SIZE_SET.has(size)) throw new TypeError(`size must be one of: ${IMAGE_AI_SIZES.join(', ')}.`);
+		const payload = {
+			prompt: requiredString('prompt', prompt, 6_000), image_count: imageCount,
+			size, output_format: config.outputFormat || 'png',
+			background: config.background || 'auto'
+		};
+		if (config.idempotencyKey !== undefined) {
+			payload.idempotency_key = requiredString('idempotencyKey', config.idempotencyKey, 128);
+			if (!/^[A-Za-z0-9_-]{8,128}$/.test(payload.idempotency_key)) throw new TypeError('idempotencyKey must use 8-128 letters, numbers, underscores, or hyphens.');
+		}
+		return payload;
+	}
+
+	async generateImages(prompt, options) {
+		const config = options || {}, payload = this._imageOptions(prompt, config, 4);
+		if (config.referenceImage === undefined) return this._call('generateImages', payload);
+		const uploadOptions = {
+			filename: config.referenceFilename, contentType: config.referenceContentType,
+			allowedTypes:['image/png','image/jpeg','image/webp'], maxBytes:MAX_IMAGE_AI_BYTES,
+			typeError:'referenceImage must be PNG, JPEG, or WebP.'
+		};
+		const source = await normalizeImage(config.referenceImage, uploadOptions), form = new FormData();
+		Object.entries(payload).forEach(([key,value]) => form.append(key, String(value)));
+		form.append('reference_image', source.blob, source.filename);
+		return this._call('generateImages', null, form);
+	}
+
+	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' });
+	}
+
+	async createImageGenerationJob(prompt, options) {
+		const config = options || {}, payload = this._imageOptions(prompt, config, 50);
+		if (config.referenceImage === undefined) return this._call('generateImages', payload, null, { endpoint:'/rest/image-generation/jobs/generate', timeoutMs:60_000 });
+		const uploadOptions = {
+			filename: config.referenceFilename, contentType: config.referenceContentType,
+			allowedTypes:['image/png','image/jpeg','image/webp'], maxBytes:MAX_IMAGE_AI_BYTES,
+			typeError:'referenceImage must be PNG, JPEG, or WebP.'
+		};
+		const source = await normalizeImage(config.referenceImage, uploadOptions), form = new FormData();
+		Object.entries(payload).forEach(([key,value]) => form.append(key, String(value)));
+		form.append('reference_image', source.blob, source.filename);
+		return this._call('generateImages', null, form, { 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,18 @@ export interface OcrOptions {
 	contentType?: 'image/png' | 'image/jpeg';
 }
 
+export type ImageAiFormat = 'png' | 'jpeg' | 'webp';
+export type ImageAiBackground = 'auto' | 'opaque' | 'transparent';
+export type ImageAiSize = '1024x1024' | '1536x1024' | '1024x1536' | '1152x864' | '864x1152';
+export type ImageAiStatus = 'waiting' | 'processing' | 'completed' | 'completed_partial' | 'cancelled' | 'failed';
+export type ApickImageErrorCode = `APICK_IMAGE_${string}`;
+export interface ImageAiOptions { imageCount?: number; size?: ImageAiSize; outputFormat?: ImageAiFormat; background?: ImageAiBackground; idempotencyKey?: string; }
+export interface ImageAiGenerateOptions extends ImageAiOptions { referenceImage?: string|BinaryInput|ArrayBuffer|ArrayBufferView; referenceFilename?: string; referenceContentType?: 'image/png'|'image/jpeg'|'image/webp'; }
+export interface ImageAiEditOptions extends ImageAiOptions { filename?: string; contentType?: 'image/png'|'image/jpeg'|'image/webp'; }
+export interface ImageAiResultImage { index:number; b64_json:string; mime_type:'image/png'|'image/jpeg'|'image/webp'; width:number; height:number; }
+export interface ImageAiResultData { request_id:string; image_count:number; images:ImageAiResultImage[]; idempotent_replay?:boolean; }
+export interface 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 +123,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?:ImageAiGenerateOptions): Promise<ApickResult<ImageAiResultData>>;
+	editImages(image:string|BinaryInput|ArrayBuffer|ArrayBufferView, prompt:string, options?:ImageAiEditOptions): Promise<ApickResult<ImageAiResultData>>;
+	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>>;
+	cancelImageJob(jobId:string): Promise<ApickResult<ImageAiJobData>>;
+	downloadImageJobImage(jobId:string,index:number): Promise<ApickBinaryResult>;
+	downloadImageJobArchive(jobId:string): Promise<ApickBinaryResult>;
 }
 
 export default ApickClient;