
텍스트만으로 이미지를 만들거나 참고 이미지와 설명을 함께 사용해 새로운 결과를 만들 수 있습니다. 원본 이미지 편집과 최대 50장의 대량 작업도 지원합니다. 요청이 접수되면 이미지 수 × 25포인트가 먼저 차감되고, 처리에 실패한 이미지의 포인트는 즉시 환급됩니다.
애플리케이션은 생성 요청을 한 번 보내고, 동기 요청이면 응답 이미지를 바로 저장합니다. 대량 작업이면 받은 job_id로 완료 여부를 조회한 뒤 결과를 내려받습니다.
CL_AUTH_KEY와 필드 규격을 확인합니다. 검사 단계에서 거절되면 포인트는 차감되지 않습니다.job_id로 상태를 조회합니다.동기 1~4장요청 → 응답의 images 저장
작업형 1~50장접수 → 상태 조회 → 개별 또는 ZIP 다운로드
결과를 바로 받아야 하면 동기 API를, 5장 이상 만들거나 요청을 접수한 뒤 다른 작업을 계속하려면 작업형 API를 사용하세요. 작업형 API는 1장부터 사용할 수 있습니다.
/rest/image-generation/generate/rest/image-generation/edit/rest/image-generation/jobs/generate/rest/image-generation/jobs/editpromptimage_countsize1024x1024, 1536x1024, 1024x1536, 1152x864, 864x1152 중 하나를 선택합니다. 생략하면 1024x1024입니다. 임의 크기는 받지 않습니다.output_formatpng, jpeg, webp 중 하나입니다. 생략하면 png입니다. 투명 배경이 필요하면 PNG 또는 WebP를 사용하세요.backgroundauto는 장면에 맞게 결정하고, opaque는 불투명 배경을 요청하며, transparent는 배경이 없는 에셋을 요청합니다. 투명 배경은 PNG·WebP에서만 사용할 수 있는 미리보기 기능입니다.idempotency_key문서에 없는 조정 옵션은 무시하지 않고 APICK_IMAGE_OPTION_NOT_SUPPORTED로 거절합니다.
idempotency_key와 같은 내용이면 기존 작업을 반환하며 새로 차감하지 않습니다.작업 상태의 prepaid_point는 처음 선차감한 금액, refunded_point는 실패로 되돌린 금액, charged_point는 현재 실제 차감 상태입니다.
1024x10241536x10241024x15361152x864864x1152reference_image · 선택image · 필수첨부 파일은 50MB 이하 PNG, JPEG, WebP 한 장을 지원합니다. 마스크 파일은 받지 않습니다. 파일을 첨부하는 요청은 multipart/form-data로 보내야 합니다.
결제 버튼을 눌렀는데 응답이 늦으면 사용자는 같은 버튼을 다시 누를 수 있습니다. 이때 두 요청에 같은 idempotency_key를 넣으면 두 번째 호출을 새 작업으로 처리하지 않고 첫 번째 결과나 작업을 다시 돌려줍니다.
APICK_IMAGE_IDEMPOTENCY_CONFLICT를 반환합니다. 새 작업이라면 새 키를 만드세요.키는 8~128자의 영문, 숫자, 밑줄, 하이픈만 사용합니다. 예: catalog_20260905_000184. 비밀번호, 인증키, 주민번호 같은 민감정보는 넣지 마세요.
아래 예시는 8장을 접수하고 1.5초마다 상태를 확인한 뒤 결과를 확인하는 흐름입니다. 네트워크 오류 시 같은 idempotency_key로 접수 요청을 다시 보내면 중복 차감을 막을 수 있습니다.
const headers = {
"CL_AUTH_KEY": process.env.APICK_API_KEY,
"Content-Type": "application/json"
};
const submitted = await fetch("https://apick.app/rest/image-generation/jobs/generate", {
method: "POST",
headers,
body: JSON.stringify({
prompt: "햇살이 비치는 밝은 주방, 흰색 텀블러 제품 광고, 서로 다른 자연스러운 카메라 각도, 제품 전체가 프레임 안에 보이게, 글자 없음",
image_count: 8,
size: "1536x1024",
output_format: "webp",
background: "opaque",
idempotency_key: "kitchen_campaign_0008"
})
}).then(response => response.json());
const jobId = submitted.data.job_id;
let job;
do {
await new Promise(resolve => setTimeout(resolve, 1500));
job = await fetch(`https://apick.app/rest/image-generation/jobs/${jobId}`, {
headers: { "CL_AUTH_KEY": process.env.APICK_API_KEY }
}).then(response => response.json());
} while (["waiting", "processing"].includes(job.data.status));
console.log(job.data.completed_count, job.data.failed_count, job.data.charged_point);
// 완료 결과: /rest/image-generation/jobs/{job_id}/resultcurl -X POST https://apick.app/rest/image-generation/generate \
-H "CL_AUTH_KEY: 발급받은_인증키" \
-H "Content-Type: application/json" \
-d '{
"prompt": "오프화이트 스튜디오 배경, 무광 세라믹 화병 하나, 창문으로 들어오는 부드러운 오전 햇빛, 자연스러운 그림자, 고급 제품 사진, 이미지 안에 글자 없음",
"image_count": 2,
"size": "1024x1024",
"output_format": "webp",
"background": "opaque",
"idempotency_key": "vase_catalog_20260905_01"
}'reference_image의 제품 형태는 참고하되 새로운 배경과 촬영 구도를 만들도록 요청하는 예시입니다.
curl -X POST https://apick.app/rest/image-generation/generate \
-H "CL_AUTH_KEY: 발급받은_인증키" \
-F "reference_image=@product.webp" \
-F "prompt=참고 이미지의 제품 형태와 라벨 색상을 유지하고, 젖은 현무암 위에 놓인 프리미엄 광고 사진으로 새롭게 구성해줘. 새벽 안개, 측면 조명, 제품 전체가 프레임 안에 보이게, 이미지 안에 글자 없음" \
-F "image_count=1" \
-F "size=1536x1024" \
-F "output_format=png" \
-F "background=opaque" \
-F "idempotency_key=product_reference_0001"curl -X POST https://apick.app/rest/image-generation/edit \
-H "CL_AUTH_KEY: 발급받은_인증키" \
-F "image=@source.png" \
-F "prompt=제품과 로고의 모양은 유지하고 컵의 손잡이만 짙은 코발트블루로 바꿔줘. 배경과 그림자는 변경하지 마" \
-F "image_count=1" \
-F "size=1024x1024" \
-F "output_format=png" \
-F "idempotency_key=cup_edit_0001"무엇을 만들지 → 화면 구성 → 배경과 조명 → 색감과 표현 방식 → 반드시 유지하거나 제외할 조건 → 표시할 문구 순서로 적으면 수정하기 쉽습니다. 정확한 문구는 작은따옴표로 감싸고 가능하면 12단어 이내로 작성하세요.
'밤의 발견', 아래에는 '9월 20일 서울', 그 밖의 글자는 넣지 말 것.'春日茶房'만 크게 표시, 다른 글자 없음, 따뜻한 실내 조명과 젖은 골목 반사, 간판이 정면으로 선명하게.images 배열의 b64_json은 Base64로 인코딩된 이미지 데이터입니다. 성공 응답의 api.cost는 요청 시 선차감되어 확정된 포인트입니다.
{
"data": {
"request_id": "요청 식별자",
"image_count": 1,
"images": [
{"index": 0, "b64_json": "...", "mime_type": "image/png", "width": 1024, "height": 1024}
]
},
"api": {"success": true, "cost": 25, "pl_id": 1234}
}curl -X POST https://apick.app/rest/image-generation/jobs/generate \
-H "CL_AUTH_KEY: 발급받은_인증키" \
-H "Content-Type: application/json" \
-d '{"prompt":"동일한 제품을 서로 다른 자연광과 카메라 각도로 촬영한 광고 시안","image_count":20,"size":"1536x1024","output_format":"webp","idempotency_key":"campaign_batch_0001"}'새 작업을 접수하면 HTTP 202와 함께 api.cost: 500, prepaid_point: 500이 반환됩니다. 동일 요청을 같은 키로 재전송한 응답은 기존 작업을 돌려주므로 api.cost가 0입니다.
/rest/image-generation/jobs/:job_idwaiting, processing, completed, completed_partial, failed 중 현재 상태와 완료·실패·환급 수치를 확인합니다./rest/image-generation/jobs/:job_id/images/:indexindex의 이미지를 내려받습니다./rest/image-generation/jobs/:job_id/result{
"data": {
"job_id": "작업 식별자",
"status": "completed_partial",
"requested_count": 20,
"completed_count": 18,
"failed_count": 2,
"prepaid_point": 500,
"refunded_point": 50,
"charged_point": 450,
"result_available": true,
"expires_at": "완료 후 24시간 만료시각"
},
"api": {"success": true, "cost": 0}
}결과는 완료 후 24시간 동안 반복 다운로드할 수 있습니다. completed_partial은 일부 이미지만 성공한 상태입니다.
APICK_IMAGE_INVALID_REQUEST, APICK_IMAGE_PROMPT_REQUIRED, APICK_IMAGE_PROMPT_TOO_LONG, APICK_IMAGE_SIZE_INVALID, APICK_IMAGE_OPTION_NOT_SUPPORTED — 프롬프트가 28,000자 이하인지, 표준 크기와 공개 필드만 사용했는지 확인하세요.APICK_IMAGE_SOURCE_REQUIRED, APICK_IMAGE_SOURCE_INVALID — 파일이 50MB 이하 PNG·JPEG·WebP인지, 참고 생성은 reference_image, 편집은 image 필드인지 확인하세요.APICK_IMAGE_IDEMPOTENCY_CONFLICT — 같은 idempotency_key에 이전과 다른 프롬프트·파일·옵션을 사용했습니다. 새 작업이라면 새 키를 만드세요.APICK_IMAGE_POINTS_INSUFFICIENT, APICK_IMAGE_BILLING_FAILED — 사용 가능한 포인트와 결제 상태를 확인하세요.APICK_IMAGE_CONTENT_REJECTED, APICK_IMAGE_TIMEOUT, APICK_IMAGE_RATE_LIMITED, APICK_IMAGE_TEMPORARILY_UNAVAILABLE — 실패 이미지의 포인트가 환급됩니다. 새 요청은 새 키로 보내고, 응답을 잃은 동일 요청만 기존 키로 다시 보내세요.APICK_IMAGE_JOB_NOT_FOUND, APICK_IMAGE_JOB_CONFLICT, APICK_IMAGE_RESULT_EXPIRED — 작업 소유권, 현재 상태, 결과 만료시각과 이미지 번호를 확인하세요.apick-api에서는 generateImages의 referenceImage 옵션으로 참고 이미지를 함께 보낼 수 있습니다. imageCount는 만들 이미지 장수이며, idempotencyKey는 중복 생성과 이중 차감을 막는 요청 번호입니다.
const result = await client.generateImages(
"참고 제품의 형태는 유지하고 숲속 캠페인 사진으로 새로 구성해줘",
{
referenceImage: "./product.webp",
imageCount: 2,
size: "1536x1024",
outputFormat: "webp",
idempotencyKey: "forest_campaign_0001"
}
);MCP에서는 image_generate에 선택적 reference_image_url을 전달할 수 있습니다. 대량 작업은 image_batch_create로 접수하고 image_batch_status와 image_batch_result로 결과를 확인합니다. 취소 도구는 제공하지 않습니다.
짧은 문구는 비교적 잘 표현하지만 작은 글자, 긴 문장, 반복 패턴, 정밀한 표 구성은 틀릴 수 있으므로 결과를 확인해야 합니다. 참고 이미지가 있어도 인물·제품·브랜드 요소가 픽셀 단위로 똑같이 유지된다고 보장하지 않습니다. 원하는 배치가 중요하면 피사체 위치, 여백, 카메라 각도와 잘리면 안 되는 요소를 프롬프트에 직접 적어 주세요.