개발가이드

  • 개발가이드

에이픽 이미지 AI

텍스트만으로 이미지를 만들거나 참고 이미지와 설명을 함께 사용해 새로운 결과를 만들 수 있습니다. 원본 이미지 편집과 최대 50장의 대량 작업도 지원합니다. 요청이 접수되면 이미지 수 × 25포인트가 먼저 차감되고, 처리에 실패한 이미지의 포인트는 즉시 환급됩니다.

연동은 이렇게 진행됩니다

애플리케이션은 생성 요청을 한 번 보내고, 동기 요청이면 응답 이미지를 바로 저장합니다. 대량 작업이면 받은 job_id로 완료 여부를 조회한 뒤 결과를 내려받습니다.

  1. 1
    요청 만들기프롬프트, 이미지 수, 표준 크기, 출력 형식을 정합니다. 필요하면 참고 이미지나 편집 원본을 첨부합니다.
  2. 2
    인증·입력 검사CL_AUTH_KEY와 필드 규격을 확인합니다. 검사 단계에서 거절되면 포인트는 차감되지 않습니다.
  3. 3
    포인트 선차감·접수이미지 수 × 25포인트를 즉시 차감합니다. 접수된 요청은 취소하거나 내용을 바꿀 수 없습니다.
  4. 4
    생성·편집 처리1~4장은 응답을 기다리고, 작업형 요청은 job_id로 상태를 조회합니다.
  5. 5
    결과 또는 환급성공한 이미지는 내려받고, 실패한 이미지마다 25포인트가 즉시 계정에 되돌아옵니다.

동기 1~4장요청 → 응답의 images 저장

작업형 1~50장접수 → 상태 조회 → 개별 또는 ZIP 다운로드

어떤 API를 선택해야 하나요?

결과를 바로 받아야 하면 동기 API를, 5장 이상 만들거나 요청을 접수한 뒤 다른 작업을 계속하려면 작업형 API를 사용하세요. 작업형 API는 1장부터 사용할 수 있습니다.

방식
경로
이미지 수
사용 시점
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장
한 원본에서 여러 편집 결과를 비동기로 만듭니다.

요청 필드

필드
형식
설명
prompt
문자열 · 필수
만들거나 바꿀 내용을 최대 28,000자로 작성합니다. 피사체, 구도, 배경, 조명, 색감, 표현 방식, 유지할 요소, 제외할 요소, 이미지 안의 문구를 구체적으로 적을수록 결과를 조절하기 쉽습니다.
image_count
정수 · 선택
만들 이미지의 장수입니다. 생략하면 1장입니다. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50을 입력합니다. 접수 시 이 값에 25를 곱한 포인트가 먼저 차감됩니다.
size
문자열 · 선택
1024x1024, 1536x1024, 1024x1536, 1152x864, 864x1152 중 하나를 선택합니다. 생략하면 1024x1024입니다. 임의 크기는 받지 않습니다.
output_format
문자열 · 선택
png, jpeg, webp 중 하나입니다. 생략하면 png입니다. 투명 배경이 필요하면 PNG 또는 WebP를 사용하세요.
background
문자열 · 선택
auto는 장면에 맞게 결정하고, opaque는 불투명 배경을 요청하며, transparent는 배경이 없는 에셋을 요청합니다. 투명 배경은 PNG·WebP에서만 사용할 수 있는 미리보기 기능입니다.
idempotency_key
문자열 · 선택
통신 오류나 사용자의 중복 클릭으로 똑같은 요청이 다시 전송돼도 이미지와 결제가 한 번만 발생하게 하는 고유한 요청 번호입니다. 주문번호나 UUID처럼 요청마다 새 값을 사용하세요.

문서에 없는 조정 옵션은 무시하지 않고 APICK_IMAGE_OPTION_NOT_SUPPORTED로 거절합니다.

선차감·환급·취소 정책

접수된 요청은 취소할 수 없습니다.접수 응답을 받은 뒤에는 브라우저를 닫거나 연결을 끊어도 처리가 계속됩니다. 실행 전 이미지 수와 예상 포인트를 확인하세요.
상황
포인트 처리
입력 오류로 접수 전 거절
차감하지 않습니다. 예: 필수 프롬프트 누락, 지원하지 않는 크기, 포인트 부족.
1장 요청 접수
25포인트를 즉시 차감합니다. 성공하면 차감이 유지되고, 실패하면 25포인트를 즉시 환급합니다.
20장 요청 접수
500포인트를 먼저 차감합니다. 18장 성공·2장 실패라면 실패분 50포인트를 환급해 최종 차감은 450포인트입니다.
같은 요청 재전송
같은 idempotency_key와 같은 내용이면 기존 작업을 반환하며 새로 차감하지 않습니다.

작업 상태의 prepaid_point는 처음 선차감한 금액, refunded_point는 실패로 되돌린 금액, charged_point는 현재 실제 차감 상태입니다.

표준 크기 선택

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

참고 이미지 생성과 원본 편집의 차이

목적
첨부 필드
동작
참고해서 새로 만들기
reference_image · 선택
생성 경로에 제품, 인물, 색감 또는 구도 참고용 이미지를 첨부합니다. 원본을 그대로 수정하는 것이 아니라 프롬프트에 맞는 새 장면을 만듭니다.
원본 자체를 편집하기
image · 필수
편집 경로에 바꿀 원본을 첨부합니다. 유지할 부분과 변경할 부분을 프롬프트에 함께 적어 주세요.

첨부 파일은 50MB 이하 PNG, JPEG, WebP 한 장을 지원합니다. 마스크 파일은 받지 않습니다. 파일을 첨부하는 요청은 multipart/form-data로 보내야 합니다.

idempotency_key를 쉽게 이해하기

결제 버튼을 눌렀는데 응답이 늦으면 사용자는 같은 버튼을 다시 누를 수 있습니다. 이때 두 요청에 같은 idempotency_key를 넣으면 두 번째 호출을 새 작업으로 처리하지 않고 첫 번째 결과나 작업을 다시 돌려줍니다.

상황
처리 결과
같은 키 + 같은 요청
이미 생성된 결과 또는 기존 작업을 반환합니다. 이미지 생성과 포인트 차감이 중복되지 않습니다.
같은 키 + 다른 요청 내용
HTTP 409와 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}/result

텍스트만으로 바로 생성

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

동기 응답

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입니다.

방식
경로
작업
설명
GET
/rest/image-generation/jobs/:job_id
상태 조회
waiting, processing, completed, completed_partial, failed 중 현재 상태와 완료·실패·환급 수치를 확인합니다.
GET
/rest/image-generation/jobs/:job_id/images/:index
한 장 받기
완료된 결과 중 0부터 시작하는 index의 이미지를 내려받습니다.
GET
/rest/image-generation/jobs/:job_id/result
묶음 받기
완료된 결과를 ZIP 파일 하나로 내려받습니다.
{
  "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 — 작업 소유권, 현재 상태, 결과 만료시각과 이미지 번호를 확인하세요.

SDK와 MCP

apick-api에서는 generateImagesreferenceImage 옵션으로 참고 이미지를 함께 보낼 수 있습니다. 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_statusimage_batch_result로 결과를 확인합니다. 취소 도구는 제공하지 않습니다.

알아둘 한계

짧은 문구는 비교적 잘 표현하지만 작은 글자, 긴 문장, 반복 패턴, 정밀한 표 구성은 틀릴 수 있으므로 결과를 확인해야 합니다. 참고 이미지가 있어도 인물·제품·브랜드 요소가 픽셀 단위로 똑같이 유지된다고 보장하지 않습니다. 원하는 배치가 중요하면 피사체 위치, 여백, 카메라 각도와 잘리면 안 되는 요소를 프롬프트에 직접 적어 주세요.

현재 페이지 북마크