apick-api 2.3.1 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.0.0 - 2026-09-05
+
+- 이미지 프롬프트 허용 길이를 최대 28,000자로 확대했습니다.
+- 작업 접수 시 전체 포인트를 먼저 차감하고 실패한 이미지의 포인트를 즉시 환급하는 계약을 반영했습니다.
+- 접수된 이미지 작업은 취소할 수 없도록 `cancelImageJob` 메서드와 `cancelled` 상태를 제거했습니다.
+
+## 2.4.0 - 2026-09-05
+
+- 이미지 장수 옵션을 의미가 분명한 `imageCount`로 바꾸고 압축 조정 옵션을 제거했습니다.
+- 이미지 크기를 5개 표준 크기 중에서만 선택하도록 타입과 런타임 검증을 강화했습니다.
+- 생성 요청에 선택적 `referenceImage`를 더해 참고 이미지와 텍스트를 함께 사용할 수 있습니다.
+
 ## 2.3.1 - 2026-09-05
 
 - 이미지 편집 입력에서 마스크 파일을 제거하고 원본 이미지와 프롬프트만 받도록 계약을 단순화했습니다.

package/README.md

@@ -80,7 +80,7 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `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 |
+| `getImageJob(jobId)` | 이미지 작업 상태 조회 / Job status | JSON |
 | `downloadImageJobImage(jobId, index)` | 개별 결과 / Individual result | Binary |
 | `downloadImageJobArchive(jobId)` | ZIP 결과 / ZIP archive | Binary |
 
@@ -101,29 +101,35 @@ console.log(result.meta);
 
 ## 이미지 생성·편집 / Image generation and editing
 
-이미지는 장당 25포인트이며 동기는 1~4장, 작업형 API는 최대 50장까지 지원합니다. 성공적으로 저장된 이미지에 대해서만 과금되며 결과는 완료 후 24시간 동안 반복 다운로드할 수 있습니다.
+이미지는 장당 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.
+Images cost 25 points each. Synchronous calls support 1–4 images and job calls support up to 50. The full amount is deducted when a request is accepted, and failed images are refunded immediately. Accepted jobs cannot be cancelled. Completed results remain downloadable for 24 hours.
 
 ```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`)를 지원합니다. 입력 프롬프트는 최대 28,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 28,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,17 +127,25 @@ 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`; prompts may contain up to 28,000 characters. The full image count × 25 points is deducted when accepted, and 25 points are refunded immediately for every failed image. Accepted jobs cannot be cancelled. 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`.
+Methods: `generateImages`, `editImages`, `createImageGenerationJob`, `createImageEditJob`, `getImageJob`, `downloadImageJobImage`, and `downloadImageJobArchive`.
 
 ## Response shape
 

package/docs/guide.ko.md

@@ -127,19 +127,27 @@ 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` 중에서 선택하고 프롬프트는 최대 28,000자까지 입력할 수 있습니다. 접수 시 이미지 장수×25포인트를 먼저 차감하며 실패한 이미지의 25포인트는 즉시 환급합니다. 접수된 작업은 취소할 수 없습니다. 결과 보관 기간은 완료 후 24시간입니다.
+
+`idempotencyKey`는 같은 요청이 통신 오류로 두 번 전송됐을 때 중복 생성과 중복 과금을 막는 안전번호입니다. 영문·숫자·밑줄·하이픈으로 8~128자를 만들고, 같은 작업을 다시 보낼 때는 같은 값을 사용하세요. 프롬프트나 옵션이 달라진 새 작업에는 새 값을 사용해야 합니다.
 
-지원 메서드: `generateImages`, `editImages`, `createImageGenerationJob`, `createImageEditJob`, `getImageJob`, `cancelImageJob`, `downloadImageJobImage`, `downloadImageJobArchive`.
+지원 메서드: `generateImages`, `editImages`, `createImageGenerationJob`, `createImageEditJob`, `getImageJob`, `downloadImageJobImage`, `downloadImageJobArchive`.
 
 ## 응답 구조
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "2.3.1",
+  "version": "3.0.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, 28_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) {
@@ -578,11 +601,6 @@ class ApickClient {
 		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.');

package/src/index.d.ts

@@ -29,13 +29,15 @@ export interface OcrOptions {
 
 export type ImageAiFormat = 'png' | 'jpeg' | 'webp';
 export type ImageAiBackground = 'auto' | 'opaque' | 'transparent';
-export type ImageAiStatus = 'waiting' | 'processing' | 'completed' | 'completed_partial' | 'cancelled' | 'failed';
+export type ImageAiSize = '1024x1024' | '1536x1024' | '1024x1536' | '1152x864' | '864x1152';
+export type ImageAiStatus = 'waiting' | 'processing' | 'completed' | 'completed_partial' | '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 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 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; 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 {
 	type: 1 | 2 | 3;
@@ -121,12 +123,11 @@ 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>>;
 	downloadImageJobImage(jobId:string,index:number): Promise<ApickBinaryResult>;
 	downloadImageJobArchive(jobId:string): Promise<ApickBinaryResult>;
 }