apick-api 2.3.1 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.4.0 - 2026-09-05
+
+- 이미지 장수 옵션을 의미가 분명한 `imageCount`로 바꾸고 압축 조정 옵션을 제거했습니다.
+- 이미지 크기를 5개 표준 크기 중에서만 선택하도록 타입과 런타임 검증을 강화했습니다.
+- 생성 요청에 선택적 `referenceImage`를 더해 참고 이미지와 텍스트를 함께 사용할 수 있습니다.
+
 ## 2.3.1 - 2026-09-05
 
 - 이미지 편집 입력에서 마스크 파일을 제거하고 원본 이미지와 프롬프트만 받도록 계약을 단순화했습니다.

package/README.md

@@ -107,23 +107,29 @@ Images cost 25 points each. Synchronous calls support 1–4 images and job calls
 
 ```js
 const made = await apick.generateImages("따뜻한 조명의 미니멀 제품 사진", {
-  count: 2, size: "1024x1024", outputFormat: "webp",
+  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("여행 포스터 시안", { count: 20 });
+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), 표준 및 사용자 지정 크기를 지원합니다. 입력 프롬프트는 최대 6,000자입니다. 자동 재시도는 하지 않습니다.
+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 standard or custom sizes are supported. Prompts are limited to 6,000 characters. Requests are never retried automatically.
+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

@@ -127,15 +127,23 @@ Text input is limited to 100,000 characters.
 
 ```js
 const result = await client.generateImages('A clean product photo on white', {
-  count: 4, size: '1024x1024', outputFormat: 'webp',
+  imageCount: 4, size: '1024x1024', outputFormat: 'webp',
   idempotencyKey: 'product-draft-001'
 });
 
-const job = await client.createImageGenerationJob('Landscape article cover concepts', { count: 20, size: '1536x1024' });
+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);
 ```
 
-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.
+`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`.
 

package/docs/guide.ko.md

@@ -127,17 +127,25 @@ const polished = await client.polish(draftText);
 
 ```js
 const result = await client.generateImages('흰 배경의 제품 사진', {
-  count: 4,
+  imageCount: 4,
   size: '1024x1024',
   outputFormat: 'webp',
   idempotencyKey: 'product-draft-001'
 });
 
-const job = await client.createImageGenerationJob('가로형 커버 시안', { count: 20, size: '1536x1024' });
+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);
 ```
 
-동기 생성·편집은 1~4장, 작업형 생성·편집은 1~50장입니다. 편집은 50MB 이하의 PNG/JPEG/WebP 원본 이미지 한 장과 프롬프트를 받으며 마스크 파일은 지원하지 않습니다. 성공 이미지 한 장당 25포인트가 확정되며 실패·취소 수량의 예약 포인트는 해제됩니다. 결과 보관 기간은 완료 후 24시간입니다.
+`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`.
 

package/package.json

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

package/src/index.cjs

@@ -4,6 +4,8 @@ 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',
@@ -529,17 +531,18 @@ class ApickClient {
 
 	_imageOptions(prompt, options, maxCount) {
 		const config = options || {};
-		for (const key of ['model', 'quality', 'n', 'input_fidelity', 'moderation', 'mask', 'maskFilename', 'maskContentType']) {
+		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 count = positiveInteger('count', config.count, 1);
-		if (count > maxCount) throw new RangeError(`count must not exceed ${maxCount}.`);
+		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), count,
-			size: config.size || '1024x1024', output_format: config.outputFormat || 'png',
+			prompt: requiredString('prompt', prompt, 6_000), image_count: imageCount,
+			size, 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.');
@@ -547,8 +550,18 @@ class ApickClient {
 		return payload;
 	}
 
-	generateImages(prompt, options) {
-		return this._call('generateImages', this._imageOptions(prompt, options, 4));
+	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) {
@@ -560,8 +573,18 @@ class ApickClient {
 		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 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) {

package/src/index.d.ts

@@ -29,12 +29,14 @@ export interface OcrOptions {
 
 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 { count?: number; size?: string; outputFormat?: ImageAiFormat; background?: ImageAiBackground; outputCompression?: number; idempotencyKey?: 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; count:number; images:ImageAiResultImage[]; idempotent_replay?:boolean; }
+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 {
@@ -121,9 +123,9 @@ 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>>;
+	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?:ImageAiOptions): Promise<ApickResult<ImageAiJobData>>;
+	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>>;