개발가이드AI•LLM에이픽 이미지 AI

에이픽 이미지 AI API

명세 내보내기
OpenAPI 3.0.3Postman 컬렉션Markdown

텍스트만으로, 또는 참고 이미지와 설명을 함께 써서 새 이미지를 만듭니다. 원본 이미지 편집과 최대 50장의 대량 작업도 지원합니다. 요금은 품질별 장당 고정가(기본 40P · 고급 350P · 최고급 1,400P)이며 크기와 관계없이 같습니다.

POSThttps://apick.app/rest/image-generation/generate전체 7개 경로
인증
Bearer 키
요청 형식
form-data / GET
응답
JSON · 파일
경로
7개

왜 에이픽 이미지 AI인가

디자이너 대기열 없이 이미지가 쏟아집니다

상품 이미지·배너 하나에 요청서를 쓰고 며칠을 기다리셨나요. 생성·원본 편집·투명 배경 처리와 여러 장 대량 작업까지 API로 바로 끝냅니다.

도입 효과

  • 배너·썸네일 시안을 즉시 확보
  • 누끼 따기 수작업을 투명 배경으로
  • 여러 장 대량 작업을 한 번에 처리

이런 곳에서 많이 씁니다

  • 쇼핑몰 상품 연출 이미지 제작
  • 마케팅 배너·광고 소재 시안
  • 블로그·숏폼 썸네일 자동 생성
  • 앱 사용자 이미지 꾸미기 기능
가입하고 API 키 받기API 키 하나로 바로 호출 · 실패한 요청은 과금되지 않습니다

알아둘 점

연동 순서

  1. 1
    경로 고르기결과를 바로 받으면 동기 경로(1~4장), 많이 만들거나 기다리지 않으려면 작업형 경로(1~50장)를 씁니다.
  2. 2
    요청 보내기프롬프트·장수·품질·크기·출력 형식을 정하고, 필요하면 참고 이미지나 편집 원본을 첨부합니다.
  3. 3
    결과 받기동기 경로는 응답의 images를 저장합니다. 작업형은 job_id로 상태를 조회한 뒤 한 장씩 또는 ZIP으로 내려받습니다.

어떤 경로를 써야 하나요?

방식
경로
이미지 수
사용 시점
POST
/rest/image-generation/generate
1~4장
텍스트만, 또는 참고 이미지 + 텍스트로 새 이미지를 만들고 결과를 바로 받습니다.
POST
/rest/image-generation/edit
1~4장
첨부한 원본의 색상·배경·요소·분위기를 바꾸고 결과를 바로 받습니다.
POST
/rest/image-generation/jobs/generate
1~50장
여러 장을 작업으로 접수하고 완료된 이미지를 나중에 내려받습니다.
POST
/rest/image-generation/jobs/edit
1~50장
원본 한 장에서 여러 편집 결과를 작업으로 만듭니다.
GET
/rest/image-generation/jobs/:job_id
-
작업 상태, 완료·실패 장수, 환급·차감 포인트를 조회합니다. 무료.
GET
/rest/image-generation/jobs/:job_id/images/:index
1장
완료된 결과 중 0부터 시작하는 index번 이미지를 파일로 받습니다. 무료.
GET
/rest/image-generation/jobs/:job_id/result
전체
완료된 결과를 ZIP 파일 하나로 받습니다. 무료.

차감·환급 규칙

접수된 요청은 취소할 수 없습니다.접수 응답을 받은 뒤에는 연결을 끊어도 처리가 계속됩니다. 보내기 전에 장수와 예상 포인트를 확인하세요.
상황
포인트 처리
입력 오류로 접수 전 거절
차감하지 않습니다. 예: 프롬프트 누락, 지원하지 않는 크기, 포인트 부족.
접수
품질별 장당 요금 × 장수를 먼저 차감합니다.
일부 이미지 실패
성공한 장의 요금만 확정하고 실패한 장의 요금은 돌려줍니다.
같은 요청을 다시 보냄
새 요청으로 만들고 다시 차감합니다. 응답을 받지 못했다면 다시 보내기 전에 포인트 사용 내역을 확인하세요.

size 고르기

size 값
비율
추천 용도
1024x1024
1:1 정사각형
상품 이미지, SNS 피드, 아이콘, 정사각형 썸네일
1536x1024
3:2 가로형
아티클 커버, 광고 배너, 웹사이트 대표 이미지, 풍경
1024x1536
2:3 세로형
포스터, 전신 인물, 쇼츠·릴스 배경, 세로 광고
1152x864
4:3 가로형
문서 삽화, 프레젠테이션, 인테리어, 제품 설명 이미지
864x1152
3:4 세로형
문서 표지, 인물 사진, 카드 뉴스, 세로형 삽화

프롬프트 작성법

무엇을 만들지 → 화면 구성 → 배경과 조명 → 색감과 표현 방식 → 반드시 유지하거나 제외할 조건 → 표시할 문구 순서로 적으면 고치기 쉽습니다. 이미지 안에 넣을 문구는 작은따옴표로 감싸고 12단어 이내로 쓰세요. 작은 글자·긴 문장·정밀한 표는 틀릴 수 있으니 결과를 확인하고, 참고 이미지를 써도 인물·제품이 똑같이 유지된다고 가정하지 마세요. 배치가 중요하면 피사체 위치·여백·카메라 각도·잘리면 안 되는 요소를 직접 적습니다.

용도
프롬프트 예시
상품 사진
투명 유리 향수병 하나를 중앙에 배치한 고급 제품 사진. 베이지 석재 받침, 따뜻한 측면 조명, 부드러운 그림자, 병 전체가 잘리지 않게, 로고나 글자 없음.
한글 포스터
짙은 남색 배경의 현대적인 문화 행사 포스터. 중앙에 큰 달과 물결 실루엣, 금색과 아이보리만 사용. 제목은 정확히 '밤의 발견', 아래에는 '9월 20일 서울', 그 밖의 글자는 넣지 말 것.
아티클 커버
비가 그친 뒤의 미래형 도서관 외관을 넓은 시야로 촬영한 장면. 사람이 없는 이른 아침, 젖은 바닥의 반사, 차분한 청회색, 제목을 넣을 수 있도록 왼쪽 위에 여백 확보, 글자 없음.
투명 스티커
웃는 표정의 작은 우주비행사 고양이 3D 스티커. 둥근 형태, 흰색 테두리, 선명한 보라색 우주복, 물체 하나만, 그림자 없음, 배경은 완전히 투명.
음식 사진
검은 도자기 접시에 담긴 트러플 파스타를 위에서 45도 각도로 촬영. 어두운 원목 테이블, 한쪽에서 들어오는 자연광, 김이 아주 약하게 보이게, 식기 전체가 프레임 안에 보이게.
인테리어
콘크리트와 밝은 참나무로 꾸민 작은 거실. 낮은 소파, 둥근 테이블, 큰 창문, 흐린 날의 부드러운 자연광, 실제 건축 사진처럼, 과도하게 넓어 보이는 왜곡 금지.
앱 삽화
온라인 결제 완료를 설명하는 단순한 3D 아이소메트릭 삽화. 스마트폰, 체크 표시, 작은 영수증만 사용, 파랑과 흰색 중심, UI 주변에 충분한 여백, 글자 없음.
책 표지
안개 낀 새벽 숲과 멀리 보이는 작은 오두막을 그린 문학 소설 표지. 상단 25%는 제목용으로 단순하게 비우고, 인물 없음, 절제된 청록과 회색, 세로 2:3.
여행 배너
초여름 해안도로를 달리는 작은 흰색 자동차, 높은 시점의 넓은 가로 구도, 오른쪽은 문구를 넣을 수 있게 하늘과 바다 여백 확보, 선명하지만 자연스러운 색.
참고 제품 활용
참고 이미지의 신발 디자인과 재질은 유지하고, 비 온 뒤의 도시 횡단보도 위를 달리는 광고 장면으로 새로 만들어줘. 낮은 카메라 위치, 물방울과 네온 반사, 신발 전체가 선명하게.
원본 편집
인물의 얼굴, 자세, 의상은 그대로 유지하고 배경만 늦가을 은행나무 길로 변경해줘. 따뜻한 오후 햇빛, 자연스러운 피사계 심도, 피부색은 바꾸지 말 것.

SDK와 MCP

apick-api 패키지에서는 generateImages의 referenceImage 옵션으로 참고 이미지를 함께 보내고, imageCount로 장수를 정합니다.

const result = await client.generateImages(
  "참고 제품의 형태는 유지하고 숲속 캠페인 사진으로 새로 구성해줘",
  {
    referenceImage: "./product.webp",
    imageCount: 2,
    size: "1536x1024",
    outputFormat: "webp"
  }
);

MCP에서는 image_generate(참고 이미지 주소 reference_image_url, quality 지원)와 image_edit로 한 장씩 만들고, 대량 작업은 image_batch_create로 접수한 뒤 image_batch_status·image_batch_result로 확인합니다. 취소 도구는 없습니다.

요청과 응답

1API 요청
POST/rest/image-generation/generate
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 7개 · 필수 1
파라미터
설명
promptstring필수
생성·편집할 이미지에 대한 설명입니다. 최대 28,000자까지 보낼 수 있으며, 피사체·배경·구도·화풍을 구체적으로 적을수록 결과가 안정적입니다.
최대 길이
28000자
예시
오프화이트 스튜디오 배경, 무광 세라믹 화병 하나, 창문으로 들어오는 부드러운 오전 햇빛, 자연스러운 그림자, 고급 제품 사진, 이미지 안에 글자 없음
image_countinteger선택
생성할 이미지 수. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50입니다.
기본값
1
예시
2
qualitystring선택
이미지 품질. basic(기본) 40P, advanced(고급) 350P, premium(최고급) 1,400P(장당). 기본 basic 가능한 값은 3가지입니다. basic = 가장 낮은 품질·가장 빠른 처리 등급입니다. 초안·대량 생성에 적합하고 단가가 가장 낮습니다. advanced = 중간 품질 등급입니다. 기본과 프리미엄의 중간 속도·품질·단가를 가집니다. premium = 가장 높은 품질 등급입니다. 해상도·디테일이 좋은 대신 처리 시간과 단가가 가장 높습니다.
허용값
basic advanced premium
예시
advanced
sizestring선택
출력 이미지의 크기입니다. 1024x1024 같은 WxH 형식으로 보내며, 생략하면 1024x1024입니다. 모델별 지원 크기가 다르므로 견적·모델 설명을 확인하세요. 가능한 값은 5가지입니다. 1024x1024 = 가로·세로가 같은 1:1 정사각 이미지입니다. 프로필·썸네일처럼 정방형이 필요할 때 사용합니다. 1536x1024 = 가로 1536·세로 1024의 3:2 가로 이미지입니다. 풍경·배너에 적합합니다. 1024x1536 = 가로 1024·세로 1536의 2:3 세로 이미지입니다. 인물 전신·모바일 화면에 적합합니다. 1152x864 = 가로 1152·세로 864의 4:3 가로 이미지입니다. 일반 사진 비율입니다. 864x1152 = 가로 864·세로 1152의 3:4 세로 이미지입니다. 인쇄 비율에 가깝습니다.
허용값
1024x1024 1536x1024 1024x1536 1152x864 864x1152
예시
1024x1024
output_formatstring선택
생성 결과의 파일 형식입니다. png·jpeg·webp 중 선택하며, 생략하면 서비스 기본값(png)을 사용합니다. 투명 배경이 필요하면 png를 선택하세요. 가능한 값은 3가지입니다. png = 무손실 PNG 형식입니다. 투명 배경이 필요할 때 사용합니다. jpeg = 압축률이 높은 JPG 형식입니다. 사진·배경이 있는 이미지에 적합합니다. webp = 용량이 작은 WEBP 형식입니다. 웹 표시에 적합하며 일부 구형 뷰어는 지원하지 않습니다.
허용값
png jpeg webp
예시
webp
backgroundstring선택
이미지 배경을 투명·불투명 중 어떻게 처리할지 정합니다. transparent는 배경 제거, opaque는 원본 배경 유지이며, 지원 여부는 모델·출력 형식에 따라 다릅니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. opaque = 배경을 불투명하게 채우는 값입니다. JPG처럼 알파 채널이 없는 형식과 호환됩니다. transparent = 배경을 투명하게 남기는 값입니다. PNG처럼 알파 채널을 지원하는 형식과 함께 써야 합니다.
허용값
auto opaque transparent
예시
opaque
reference_imagefile선택
생성 경로 전용. 제품·인물·색감·구도를 참고할 이미지 1장. 원본을 고치지 않고 프롬프트에 맞는 새 장면을 만듭니다.
응답 필드 14개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.request_idstring
이미지 생성 요청의 고유 ID입니다. 같은 요청을 추적하거나 문의할 때 사용합니다.
data.image_countinteger
이번 응답에 포함된 생성 이미지 수입니다. 요청 이미지 수와 다를 수 있습니다.
data.idempotent_replayboolean
호환용 필드입니다. 같은 요청도 매번 새로 생성하므로 true가 되지 않습니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.
data.imagesarray
이미지 목록입니다. 상품 조회에서는 이미지 주소 문자열이, 이미지 생성에서는 이미지 데이터·MIME·크기를 담은 객체가 들어갑니다. 값이 없으면 빈 배열입니다.
data.images[].indexinteger
0부터 시작하는 이미지 번호. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.images[].b64_jsonstring
이미지 바이트의 Base64 문자열. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.images[].mime_typestring
이미지 MIME. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. 가능한 값은 3가지입니다. image/png = PNG 이미지 MIME입니다. 알파 채널(투명 배경)을 보존합니다. image/jpeg = JPEG 이미지 MIME입니다. 압축 손실이 있으며 알파 채널은 없습니다. image/webp = WEBP 이미지 MIME입니다. 같은 화질에서 용량이 작습니다.
허용값
image/png image/jpeg image/webp
data.images[].widthinteger
이미지 너비(픽셀). 이미지·영상의 가로 크기(픽셀)입니다. 화면 배치 전에 원본 비율을 확인하세요.
data.images[].heightinteger
이미지 높이(픽셀). 이미지·영상의 세로 크기(픽셀)입니다. width와 함께 원본 비율을 계산할 수 있습니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costnumber
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
2API 요청
POST/rest/image-generation/edit
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 7개 · 필수 2
파라미터
설명
promptstring필수
생성·편집할 이미지에 대한 설명입니다. 최대 28,000자까지 보낼 수 있으며, 피사체·배경·구도·화풍을 구체적으로 적을수록 결과가 안정적입니다.
최대 길이
28000자
예시
잔잔한 바닷가를 표현해 주세요.
image_countinteger선택
생성할 이미지 수. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50입니다.
기본값
1
qualitystring선택
이미지 품질. basic(기본) 40P, advanced(고급) 350P, premium(최고급) 1,400P(장당). 기본 basic 가능한 값은 3가지입니다. basic = 가장 낮은 품질·가장 빠른 처리 등급입니다. 초안·대량 생성에 적합하고 단가가 가장 낮습니다. advanced = 중간 품질 등급입니다. 기본과 프리미엄의 중간 속도·품질·단가를 가집니다. premium = 가장 높은 품질 등급입니다. 해상도·디테일이 좋은 대신 처리 시간과 단가가 가장 높습니다.
허용값
basic advanced premium
sizestring선택
출력 이미지의 크기입니다. 1024x1024 같은 WxH 형식으로 보내며, 생략하면 1024x1024입니다. 모델별 지원 크기가 다르므로 견적·모델 설명을 확인하세요. 가능한 값은 5가지입니다. 1024x1024 = 가로·세로가 같은 1:1 정사각 이미지입니다. 프로필·썸네일처럼 정방형이 필요할 때 사용합니다. 1536x1024 = 가로 1536·세로 1024의 3:2 가로 이미지입니다. 풍경·배너에 적합합니다. 1024x1536 = 가로 1024·세로 1536의 2:3 세로 이미지입니다. 인물 전신·모바일 화면에 적합합니다. 1152x864 = 가로 1152·세로 864의 4:3 가로 이미지입니다. 일반 사진 비율입니다. 864x1152 = 가로 864·세로 1152의 3:4 세로 이미지입니다. 인쇄 비율에 가깝습니다.
허용값
1024x1024 1536x1024 1024x1536 1152x864 864x1152
output_formatstring선택
생성 결과의 파일 형식입니다. png·jpeg·webp 중 선택하며, 생략하면 서비스 기본값(png)을 사용합니다. 투명 배경이 필요하면 png를 선택하세요. 가능한 값은 3가지입니다. png = 무손실 PNG 형식입니다. 투명 배경이 필요할 때 사용합니다. jpeg = 압축률이 높은 JPG 형식입니다. 사진·배경이 있는 이미지에 적합합니다. webp = 용량이 작은 WEBP 형식입니다. 웹 표시에 적합하며 일부 구형 뷰어는 지원하지 않습니다.
허용값
png jpeg webp
backgroundstring선택
이미지 배경을 투명·불투명 중 어떻게 처리할지 정합니다. transparent는 배경 제거, opaque는 원본 배경 유지이며, 지원 여부는 모델·출력 형식에 따라 다릅니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. opaque = 배경을 불투명하게 채우는 값입니다. JPG처럼 알파 채널이 없는 형식과 호환됩니다. transparent = 배경을 투명하게 남기는 값입니다. PNG처럼 알파 채널을 지원하는 형식과 함께 써야 합니다.
허용값
auto opaque transparent
imagefile필수
편집 경로 전용이며 필수. 바꿀 원본 이미지 1장. 유지할 부분과 바꿀 부분을 프롬프트에 함께 적으세요.
응답 필드 14개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.request_idstring
이미지 생성 요청의 고유 ID입니다. 같은 요청을 추적하거나 문의할 때 사용합니다.
data.image_countinteger
이번 응답에 포함된 생성 이미지 수입니다. 요청 이미지 수와 다를 수 있습니다.
data.idempotent_replayboolean
호환용 필드입니다. 같은 요청도 매번 새로 생성하므로 true가 되지 않습니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.
data.imagesarray
이미지 목록입니다. 상품 조회에서는 이미지 주소 문자열이, 이미지 생성에서는 이미지 데이터·MIME·크기를 담은 객체가 들어갑니다. 값이 없으면 빈 배열입니다.
data.images[].indexinteger
0부터 시작하는 이미지 번호. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.images[].b64_jsonstring
이미지 바이트의 Base64 문자열. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.images[].mime_typestring
이미지 MIME. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. 가능한 값은 3가지입니다. image/png = PNG 이미지 MIME입니다. 알파 채널(투명 배경)을 보존합니다. image/jpeg = JPEG 이미지 MIME입니다. 압축 손실이 있으며 알파 채널은 없습니다. image/webp = WEBP 이미지 MIME입니다. 같은 화질에서 용량이 작습니다.
허용값
image/png image/jpeg image/webp
data.images[].widthinteger
이미지 너비(픽셀). 이미지·영상의 가로 크기(픽셀)입니다. 화면 배치 전에 원본 비율을 확인하세요.
data.images[].heightinteger
이미지 높이(픽셀). 이미지·영상의 세로 크기(픽셀)입니다. width와 함께 원본 비율을 계산할 수 있습니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costnumber
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
3API 요청
POST/rest/image-generation/jobs/generate
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 7개 · 필수 1
파라미터
설명
promptstring필수
생성·편집할 이미지에 대한 설명입니다. 최대 28,000자까지 보낼 수 있으며, 피사체·배경·구도·화풍을 구체적으로 적을수록 결과가 안정적입니다.
최대 길이
28000자
예시
잔잔한 바닷가를 표현해 주세요.
image_countinteger선택
생성할 이미지 수. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50입니다.
기본값
1
qualitystring선택
이미지 품질. basic(기본) 40P, advanced(고급) 350P, premium(최고급) 1,400P(장당). 기본 basic 가능한 값은 3가지입니다. basic = 가장 낮은 품질·가장 빠른 처리 등급입니다. 초안·대량 생성에 적합하고 단가가 가장 낮습니다. advanced = 중간 품질 등급입니다. 기본과 프리미엄의 중간 속도·품질·단가를 가집니다. premium = 가장 높은 품질 등급입니다. 해상도·디테일이 좋은 대신 처리 시간과 단가가 가장 높습니다.
허용값
basic advanced premium
sizestring선택
출력 이미지의 크기입니다. 1024x1024 같은 WxH 형식으로 보내며, 생략하면 1024x1024입니다. 모델별 지원 크기가 다르므로 견적·모델 설명을 확인하세요. 가능한 값은 5가지입니다. 1024x1024 = 가로·세로가 같은 1:1 정사각 이미지입니다. 프로필·썸네일처럼 정방형이 필요할 때 사용합니다. 1536x1024 = 가로 1536·세로 1024의 3:2 가로 이미지입니다. 풍경·배너에 적합합니다. 1024x1536 = 가로 1024·세로 1536의 2:3 세로 이미지입니다. 인물 전신·모바일 화면에 적합합니다. 1152x864 = 가로 1152·세로 864의 4:3 가로 이미지입니다. 일반 사진 비율입니다. 864x1152 = 가로 864·세로 1152의 3:4 세로 이미지입니다. 인쇄 비율에 가깝습니다.
허용값
1024x1024 1536x1024 1024x1536 1152x864 864x1152
output_formatstring선택
생성 결과의 파일 형식입니다. png·jpeg·webp 중 선택하며, 생략하면 서비스 기본값(png)을 사용합니다. 투명 배경이 필요하면 png를 선택하세요. 가능한 값은 3가지입니다. png = 무손실 PNG 형식입니다. 투명 배경이 필요할 때 사용합니다. jpeg = 압축률이 높은 JPG 형식입니다. 사진·배경이 있는 이미지에 적합합니다. webp = 용량이 작은 WEBP 형식입니다. 웹 표시에 적합하며 일부 구형 뷰어는 지원하지 않습니다.
허용값
png jpeg webp
backgroundstring선택
이미지 배경을 투명·불투명 중 어떻게 처리할지 정합니다. transparent는 배경 제거, opaque는 원본 배경 유지이며, 지원 여부는 모델·출력 형식에 따라 다릅니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. opaque = 배경을 불투명하게 채우는 값입니다. JPG처럼 알파 채널이 없는 형식과 호환됩니다. transparent = 배경을 투명하게 남기는 값입니다. PNG처럼 알파 채널을 지원하는 형식과 함께 써야 합니다.
허용값
auto opaque transparent
reference_imagefile선택
생성 경로 전용. 제품·인물·색감·구도를 참고할 이미지 1장. 원본을 고치지 않고 프롬프트에 맞는 새 장면을 만듭니다.
응답 필드 11개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.job_idstring
접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.
data.statusstring
현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다.
data.requested_countinteger
요청한 이미지 수입니다. 실제 생성 수와 비교해 실패 여부를 확인하세요.
data.cost_per_imagenumber
이미지 1장당 접수 시 단가(포인트). 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.prepaid_pointnumber
선결제 포인트. 접수 시 미리 차감한 포인트입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.idempotent_replayboolean
호환용 필드로 항상 false입니다. 같은 요청도 매번 새 작업으로 접수합니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costnumber
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
4API 요청
POST/rest/image-generation/jobs/edit
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 7개 · 필수 2
파라미터
설명
promptstring필수
생성·편집할 이미지에 대한 설명입니다. 최대 28,000자까지 보낼 수 있으며, 피사체·배경·구도·화풍을 구체적으로 적을수록 결과가 안정적입니다.
최대 길이
28000자
예시
잔잔한 바닷가를 표현해 주세요.
image_countinteger선택
생성할 이미지 수. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50입니다.
기본값
1
qualitystring선택
이미지 품질. basic(기본) 40P, advanced(고급) 350P, premium(최고급) 1,400P(장당). 기본 basic 가능한 값은 3가지입니다. basic = 가장 낮은 품질·가장 빠른 처리 등급입니다. 초안·대량 생성에 적합하고 단가가 가장 낮습니다. advanced = 중간 품질 등급입니다. 기본과 프리미엄의 중간 속도·품질·단가를 가집니다. premium = 가장 높은 품질 등급입니다. 해상도·디테일이 좋은 대신 처리 시간과 단가가 가장 높습니다.
허용값
basic advanced premium
sizestring선택
출력 이미지의 크기입니다. 1024x1024 같은 WxH 형식으로 보내며, 생략하면 1024x1024입니다. 모델별 지원 크기가 다르므로 견적·모델 설명을 확인하세요. 가능한 값은 5가지입니다. 1024x1024 = 가로·세로가 같은 1:1 정사각 이미지입니다. 프로필·썸네일처럼 정방형이 필요할 때 사용합니다. 1536x1024 = 가로 1536·세로 1024의 3:2 가로 이미지입니다. 풍경·배너에 적합합니다. 1024x1536 = 가로 1024·세로 1536의 2:3 세로 이미지입니다. 인물 전신·모바일 화면에 적합합니다. 1152x864 = 가로 1152·세로 864의 4:3 가로 이미지입니다. 일반 사진 비율입니다. 864x1152 = 가로 864·세로 1152의 3:4 세로 이미지입니다. 인쇄 비율에 가깝습니다.
허용값
1024x1024 1536x1024 1024x1536 1152x864 864x1152
output_formatstring선택
생성 결과의 파일 형식입니다. png·jpeg·webp 중 선택하며, 생략하면 서비스 기본값(png)을 사용합니다. 투명 배경이 필요하면 png를 선택하세요. 가능한 값은 3가지입니다. png = 무손실 PNG 형식입니다. 투명 배경이 필요할 때 사용합니다. jpeg = 압축률이 높은 JPG 형식입니다. 사진·배경이 있는 이미지에 적합합니다. webp = 용량이 작은 WEBP 형식입니다. 웹 표시에 적합하며 일부 구형 뷰어는 지원하지 않습니다.
허용값
png jpeg webp
backgroundstring선택
이미지 배경을 투명·불투명 중 어떻게 처리할지 정합니다. transparent는 배경 제거, opaque는 원본 배경 유지이며, 지원 여부는 모델·출력 형식에 따라 다릅니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. opaque = 배경을 불투명하게 채우는 값입니다. JPG처럼 알파 채널이 없는 형식과 호환됩니다. transparent = 배경을 투명하게 남기는 값입니다. PNG처럼 알파 채널을 지원하는 형식과 함께 써야 합니다.
허용값
auto opaque transparent
imagefile필수
편집 경로 전용이며 필수. 바꿀 원본 이미지 1장. 유지할 부분과 바꿀 부분을 프롬프트에 함께 적으세요.
응답 필드 11개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.job_idstring
접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.
data.statusstring
현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다.
data.requested_countinteger
요청한 이미지 수입니다. 실제 생성 수와 비교해 실패 여부를 확인하세요.
data.cost_per_imagenumber
이미지 1장당 접수 시 단가(포인트). 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.prepaid_pointnumber
선결제 포인트. 접수 시 미리 차감한 포인트입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.idempotent_replayboolean
호환용 필드로 항상 false입니다. 같은 요청도 매번 새 작업으로 접수합니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costnumber
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
5상태·목록 조회
GET/rest/image-generation/jobs/:job_id
  • Bearer 인증
  • 요청 본문 없음
  • JSON 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 16개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.job_idstring
접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.
data.statusstring
현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 5가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. completed_partial = 일부만 완료된 상태입니다. 요청 수·완료 수·실패 수를 비교해 실패분만 다시 요청할지 판단합니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다.
허용값
waiting processing completed completed_partial failed
data.requested_countinteger
요청한 이미지 수입니다. 실제 생성 수와 비교해 실패 여부를 확인하세요.
data.completed_countinteger
정상 생성된 이미지 수입니다. requested_count보다 작으면 일부 실패입니다.
data.failed_countinteger
생성에 실패한 이미지 수입니다. 0이 아니면 error_code를 확인하세요.
data.prepaid_pointnumber
선결제 포인트. 접수 시 미리 차감한 포인트입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.refunded_pointnumber
환급 포인트. 작업 실패·취소로 돌려받은 포인트입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.charged_pointnumber
최종 차감된 포인트입니다. 실패·부분 성공 시 환급이 반영된 값입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.result_availableboolean
결과 파일을 지금 내려받을 수 있는지 여부입니다. false면 아직 처리 중이거나 결과가 만료·삭제된 상태입니다. true = 결과 파일을 지금 내려받을 수 있는 경우, false = 처리 중이거나 실패·만료된 경우입니다.
data.expires_atstring
결과 만료 일시. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
data.error_codestring
작업 실패 코드. 오류가 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costnumber
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
하위 필드 0개 더 보기

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

6결과 받기
GET/rest/image-generation/jobs/:job_id/images/:index
  • Bearer 인증
  • 요청 본문 없음
  • 파일 응답

경로의 job_id, index는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID, APICK_INDEX 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 파일

정상 응답은 파일 본문입니다. 실패 시 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

7결과 받기
GET/rest/image-generation/jobs/:job_id/result
  • Bearer 인증
  • 요청 본문 없음
  • 파일 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 파일

정상 응답은 파일 본문입니다. 실패 시 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

입력 조건·전송 규칙

생성·편집 요청은 form-data로 보내며, 파일은 같은 요청에 첨부합니다. 아래에 없는 조정 옵션을 보내면 APICK_IMAGE_OPTION_NOT_SUPPORTED로 거절됩니다.

첨부 파일은 50MB 이하 PNG·JPEG·WebP 한 장입니다. 마스크 파일은 받지 않습니다. 같은 내용을 다시 보내도 결과를 재사용하지 않고 새로 만들어 다시 차감합니다.

사용 예시

상황별로 보내는 값과 응답에서 확인할 값을 모았습니다. 언어 탭에서 그대로 복사해 쓸 수 있습니다.

예시 1. 텍스트로 2장 바로 만들기

제품 사진 시안 2장을 동기 경로로 만들고 응답에서 바로 저장합니다.

요청POST/rest/image-generation/generate
curl --fail-with-body --request POST 'https://apick.app/rest/image-generation/generate' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=오프화이트 스튜디오 배경, 무광 세라믹 화병 하나, 창문으로 들어오는 부드러운 오전 햇빛, 자연스러운 그림자, 고급 제품 사진, 이미지 안에 글자 없음' \
  --form-string 'image_count=2' \
  --form-string 'size=1024x1024' \
  --form-string 'output_format=webp' \
  --form-string 'background=opaque' \
  --form-string 'quality=advanced'
  • data.images[].b64_json을 Base64 디코딩해 mime_type에 맞는 확장자로 저장합니다.
  • api.cost는 품질별 장당 요금 × 장수입니다(고급 350P × 2).
예시 2. 참고 이미지로 새 장면 만들기

제품 사진을 참고해 배경과 구도가 다른 광고 이미지를 만듭니다.

요청POST/rest/image-generation/generate
curl --fail-with-body --request POST 'https://apick.app/rest/image-generation/generate' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form 'reference_image=@./product.webp' \
  --form-string 'prompt=참고 이미지의 제품 형태와 라벨 색상을 유지하고, 젖은 현무암 위에 놓인 프리미엄 광고 사진으로 새롭게 구성해 줘. 새벽 안개, 측면 조명, 제품 전체가 프레임 안에, 글자 없음' \
  --form-string 'image_count=1' \
  --form-string 'size=1536x1024' \
  --form-string 'quality=basic'
  • 참고 이미지는 50MB 이하 PNG·JPEG·WebP 한 장입니다. 다르면 data.error_code가 APICK_IMAGE_SOURCE_INVALID입니다.
예시 3. 원본 일부만 바꾸기

원본을 편집 경로에 첨부하고 바꿀 부분과 유지할 부분을 함께 적습니다.

요청POST/rest/image-generation/edit
curl --fail-with-body --request POST 'https://apick.app/rest/image-generation/edit' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form 'image=@./source.png' \
  --form-string 'prompt=제품과 로고의 모양은 유지하고 컵의 손잡이만 짙은 코발트블루로 바꿔 줘. 배경과 그림자는 변경하지 마' \
  --form-string 'quality=premium'
  • 편집 결과도 data.images[]로 받습니다. api.cost는 최고급 1,400P × 장수입니다.
예시 4. 배경이 투명한 스티커

배경 없는 에셋이 필요하면 background=transparent와 PNG 또는 WebP를 함께 보냅니다.

요청POST/rest/image-generation/generate
curl --fail-with-body --request POST 'https://apick.app/rest/image-generation/generate' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'size=1024x1024' \
  --form-string 'prompt=웃는 표정의 작은 우주비행사 고양이 3D 스티커. 둥근 형태, 흰색 테두리, 물체 하나만, 그림자 없음' \
  --form-string 'image_count=1' \
  --form-string 'background=transparent' \
  --form-string 'output_format=png' \
  --form-string 'quality=basic'
  • output_format=jpeg와 함께 보내면 APICK_IMAGE_BACKGROUND_INVALID로 거절되고 과금되지 않습니다.
예시 5. 20장을 작업으로 접수

여러 장은 작업형 경로로 접수하고 진행 상황을 조회합니다.

요청POST/rest/image-generation/jobs/generate
curl --fail-with-body --request POST 'https://apick.app/rest/image-generation/jobs/generate' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=같은 흰색 텀블러를 서로 다른 자연광과 카메라 각도로 촬영한 광고 시안, 제품 전체가 프레임 안에, 글자 없음' \
  --form-string 'image_count=20' \
  --form-string 'size=1536x1024' \
  --form-string 'output_format=webp' \
  --form-string 'quality=basic'
  • HTTP 202와 data.job_id를 받고, data.prepaid_point(40P × 20장 = 800P)가 먼저 차감됩니다.
  • 접수 후에는 취소할 수 없으니 장수와 품질을 보내기 전에 확인합니다.
예시 6. 작업 진행 조회

접수한 job_id로 2~5초 간격으로 조회합니다. 무료입니다.

요청GET/rest/image-generation/jobs/:job_id
curl --fail-with-body --request GET "https://apick.app/rest/image-generation/jobs/${APICK_JOB_ID}" \
  --header "Authorization: Bearer $APICK_API_KEY"
  • data.status가 completed·completed_partial·failed가 되면 멈춥니다.
  • data.refunded_point가 실패한 장의 환급액, 끝난 상태의 data.charged_point가 최종 요금입니다.
  • data.result_available이 true면 /result(ZIP)나 /images/:index로 내려받습니다.

응답 처리

HTTP 성공과 업무 결과를 구분하세요. 경로별 응답 필드와 예시는 위 요청과 응답에 함께 있습니다.

응답 형식 오류코드는 data.error_code입니다. 작업 상태조회는 HTTP 200이어도 실패한 작업의 error_code를 포함할 수 있으므로 data.status를 함께 확인하세요.

응답 — 동기 생성·편집

data.images[]의 b64_json을 Base64 디코딩해 mime_type에 맞는 확장자로 저장합니다. api.cost는 확정된 차감 포인트입니다.

{
  "data": {
    "request_id": "3f2a9c0d8e7b4a61b5c4d3e2f1a09b8c",
    "image_count": 1,
    "images": [
      { "index": 0, "b64_json": "iVBORw0KGgo...", "mime_type": "image/png", "width": 1024, "height": 1024 }
    ]
  },
  "api": { "success": true, "cost": 40, "pl_id": 1234 }
}

드물게 동기 요청이 HTTP 202와 data.job_id, data.status: "processing"을 돌려줄 수 있습니다. 이때는 같은 job_id로 작업 상태를 조회하고 결과를 내려받으세요.

응답 — 작업형 접수와 진행 조회

작업형 경로는 접수 즉시 HTTP 202와 job_id를 돌려주고, 품질별 장당 요금 × 장수를 먼저 차감합니다(api.cost). 이후 GET /rest/image-generation/jobs/:job_id를 2~5초 간격으로 조회해 status가 completed·completed_partial·failed 중 하나가 되면 멈춥니다.

{
  "data": {
    "job_id": "7c1e0a9b8d6f4e3a2b1c0d9e8f7a6b5c",
    "status": "waiting",
    "requested_count": 20,
    "cost_per_image": 40,
    "prepaid_point": 800,
    "idempotent_replay": false
  },
  "api": { "success": true, "cost": 800 }
}
{
  "data": {
    "job_id": "7c1e0a9b8d6f4e3a2b1c0d9e8f7a6b5c",
    "status": "completed_partial",
    "requested_count": 20,
    "completed_count": 18,
    "failed_count": 2,
    "prepaid_point": 800,
    "refunded_point": 80,
    "charged_point": 720,
    "result_available": true,
    "expires_at": "2026-10-21T09:00:00.000Z",
    "error_code": null
  },
  "api": { "success": true, "cost": 0 }
}

결과는 /images/:index로 한 장씩(실패한 번호는 받을 수 없음) 또는 /result로 ZIP 한 번에 받습니다. 성공한 이미지가 없는 작업이나 처리 중인 작업은 APICK_IMAGE_JOB_CONFLICT(409), 보관 기간이 지나면 APICK_IMAGE_RESULT_EXPIRED(410)입니다.

원문 응답 필드 표 보기
필드
타입
설명
data.request_id
String
요청 ID. 문의할 때 함께 알려 주세요.
data.image_count
Integer
받은 이미지 수
data.images[].index
Integer
0부터 시작하는 번호
data.images[].b64_json
String
이미지 파일의 Base64 문자열
data.images[].mime_type
String
image/png·image/jpeg·image/webp
data.images[].width
Integer
이미지 너비(픽셀)
data.images[].height
Integer
이미지 높이(픽셀)
data.error_code
String
실패했을 때의 오류 코드. 사유는 data.error
필드
타입
설명
data.status
String
waiting(대기)·processing(처리 중)·completed(전부 성공)·completed_partial(일부 성공)·failed(전부 실패)
data.completed_count
Integer
완료한 장수
data.failed_count
Integer
실패한 장수
data.prepaid_point
Number
접수 때 먼저 차감한 포인트
data.refunded_point
Number
실패한 장에 대해 돌려준 포인트
data.charged_point
Number
현재 차감 포인트. 처리 중에는 아직 확정되지 않은 예약분이 포함되므로, 끝난 상태에서 최종 요금으로 확인합니다.
data.result_available
Boolean
내려받을 수 있는 결과가 있으면 true
data.expires_at
String/null
결과 보관 만료 시각. 완료 후 24시간 동안 반복해서 내려받을 수 있습니다.
data.error_code
String/null
작업이 실패했을 때의 오류 코드

오류 코드

응답을 아래 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

  1. HTTP 상태전송·인증·입력 오류
  2. api.successAPI 처리 여부
  3. data · result업무 결과와 오류 문구
  4. api.cost이번 요청의 과금
이 API의 오류 코드 23개
코드
HTTP
의미·조치
APICK_IMAGE_INVALID_REQUEST
400
프롬프트에 사용할 수 없는 문자를 제거하세요.
APICK_IMAGE_PROMPT_REQUIRED
400
비어 있지 않은 prompt를 입력하세요.
APICK_IMAGE_PROMPT_TOO_LONG
400
프롬프트를 28,000자 이하로 줄이세요.
APICK_IMAGE_SIZE_INVALID
400
지원하는 표준 크기를 선택하세요.
APICK_IMAGE_QUALITY_INVALID
400
quality는 basic, advanced, premium 중 하나로 보내세요.
APICK_IMAGE_OPTION_NOT_SUPPORTED
400
지원하지 않는 조정 옵션 또는 파일 필드를 제거하세요.
APICK_IMAGE_COUNT_INVALID
400
동기는 1~4장, 작업형은 1~50장의 정수를 입력하세요.
APICK_IMAGE_FORMAT_INVALID
400
png, jpeg, webp 중 하나를 선택하세요.
APICK_IMAGE_BACKGROUND_INVALID
400
auto, opaque, transparent 중 선택하세요. 투명 배경에는 PNG·WebP를 사용하세요.
APICK_IMAGE_SOURCE_REQUIRED
400
올바른 필드에 단일 이미지 파일을 첨부하세요.
APICK_IMAGE_SOURCE_INVALID
400·413
비어 있지 않은 50MB 이하 PNG·JPEG·WebP를 첨부하세요.
APICK_IMAGE_AUTH_FAILED
401
인증키와 계정을 확인하세요.
APICK_IMAGE_POINTS_INSUFFICIENT
402
필요한 포인트를 충전하세요.
APICK_IMAGE_CONTENT_REJECTED
422
프롬프트 또는 입력 이미지를 변경하세요.
APICK_IMAGE_RATE_LIMITED
429
요청 간격을 늘린 뒤 다시 시도하세요.
APICK_IMAGE_TIMEOUT
408
처리 시간이 초과됐습니다. 작업 상태를 확인하세요.
APICK_IMAGE_TEMPORARILY_UNAVAILABLE
503
잠시 후 다시 시도하세요.
APICK_IMAGE_RESULT_INVALID
502
실패 상태와 환급 내역을 확인하세요.
APICK_IMAGE_BILLING_FAILED
424
결제 처리를 완료하지 못했습니다. 작업과 포인트 상태를 확인하세요.
APICK_IMAGE_JOB_NOT_FOUND
404
작업 소유권·작업 ID·이미지 번호를 확인하세요.
APICK_IMAGE_JOB_CONFLICT
409
다운로드할 이미지의 생성 완료 여부를 확인하세요.
APICK_IMAGE_RESULT_EXPIRED
410
보관 기간이 만료됐거나 결과 파일이 없습니다.
APICK_IMAGE_INTERNAL_ERROR
500
잠시 후 다시 시도하세요.
폼 입력 오류 error.code
코드
HTTP
의미·조치
FORM_DATA_INVALID
400
필드 이름·값의 타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.
FORM_DATA_FIELD_CONFLICT
400
같은 값과 중첩 경로를 동시에 지정하지 마세요.
MULTIPART_LIMIT_OR_PARSE_ERROR
400·413
boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·이용 조건

기본 요금기본 단가 40P · 성공 이미지 수무료 포인트로는 이용할 수 없으며 최소 1회 결제 후 이용할 수 있습니다.

실제 차감 금액은 응답의 api.cost로 확인하세요. 상세 요금은 요금정책에서 볼 수 있습니다.

연동 팁

  • 요청 예제의 오류 처리 포함 모드는 시간 제한과 업무 실패 판정을 함께 보여줍니다.
  • 인증키는 서버 환경변수에 두고 브라우저·앱에 넣지 마세요.
  • HTTP 성공과 업무 결과를 구분하고, 실패 응답의 오류 문구를 그대로 기록하세요.
추가 예제·서비스별 연동 안내

호출 예시

텍스트만으로 생성하는 동기 호출 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다.

JavaScript 예시
Python 예시

개발가이드 검색

API 이름·경로·파라미터·오류 코드로 찾을 수 있습니다.

표시 가격은 기본 단가입니다. 상세 과금 조건은 각 가이드에서 확인하세요.