# 에이픽 이미지 AI



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



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/image-generation/generate 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.request_id` (string): 이미지 생성 요청의 고유 ID입니다. 같은 요청을 추적하거나 문의할 때 사용합니다.

- `data.image_count` (integer): 이번 응답에 포함된 생성 이미지 수입니다. 요청 이미지 수와 다를 수 있습니다.

- `data.idempotent_replay` (boolean): 호환용 필드입니다. 같은 요청도 매번 새로 생성하므로 true가 되지 않습니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.

- `data.images` (array): 이미지 목록입니다. 상품 조회에서는 이미지 주소 문자열이, 이미지 생성에서는 이미지 데이터·MIME·크기를 담은 객체가 들어갑니다. 값이 없으면 빈 배열입니다.

- `data.images[].index` (integer): 0부터 시작하는 이미지 번호. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.images[].b64_json` (string): 이미지 바이트의 Base64 문자열. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.images[].mime_type` (string): 이미지 MIME. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. 가능한 값은 3가지입니다. image/png = PNG 이미지 MIME입니다. 알파 채널(투명 배경)을 보존합니다. image/jpeg = JPEG 이미지 MIME입니다. 압축 손실이 있으며 알파 채널은 없습니다. image/webp = WEBP 이미지 MIME입니다. 같은 화질에서 용량이 작습니다. 허용값: image/png, image/jpeg, image/webp

- `data.images[].width` (integer): 이미지 너비(픽셀). 이미지·영상의 가로 크기(픽셀)입니다. 화면 배치 전에 원본 비율을 확인하세요.

- `data.images[].height` (integer): 이미지 높이(픽셀). 이미지·영상의 세로 크기(픽셀)입니다. width와 함께 원본 비율을 계산할 수 있습니다.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (number): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/image-generation/generate



### 입력

- `prompt` (string, 필수): 생성·편집할 이미지에 대한 설명입니다. 최대 28,000자까지 보낼 수 있으며, 피사체·배경·구도·화풍을 구체적으로 적을수록 결과가 안정적입니다.

- `image_count` (integer, 선택): 생성할 이미지 수. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50입니다. 기본값: 1

- `quality` (string, 선택): 이미지 품질. basic(기본) 40P, advanced(고급) 350P, premium(최고급) 1,400P(장당). 기본 basic 가능한 값은 3가지입니다. basic = 가장 낮은 품질·가장 빠른 처리 등급입니다. 초안·대량 생성에 적합하고 단가가 가장 낮습니다. advanced = 중간 품질 등급입니다. 기본과 프리미엄의 중간 속도·품질·단가를 가집니다. premium = 가장 높은 품질 등급입니다. 해상도·디테일이 좋은 대신 처리 시간과 단가가 가장 높습니다. 허용값: basic, advanced, premium

- `size` (string, 선택): 출력 이미지의 크기입니다. 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_format` (string, 선택): 생성 결과의 파일 형식입니다. png·jpeg·webp 중 선택하며, 생략하면 서비스 기본값(png)을 사용합니다. 투명 배경이 필요하면 png를 선택하세요. 가능한 값은 3가지입니다. png = 무손실 PNG 형식입니다. 투명 배경이 필요할 때 사용합니다. jpeg = 압축률이 높은 JPG 형식입니다. 사진·배경이 있는 이미지에 적합합니다. webp = 용량이 작은 WEBP 형식입니다. 웹 표시에 적합하며 일부 구형 뷰어는 지원하지 않습니다. 허용값: png, jpeg, webp

- `background` (string, 선택): 이미지 배경을 투명·불투명 중 어떻게 처리할지 정합니다. transparent는 배경 제거, opaque는 원본 배경 유지이며, 지원 여부는 모델·출력 형식에 따라 다릅니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. opaque = 배경을 불투명하게 채우는 값입니다. JPG처럼 알파 채널이 없는 형식과 호환됩니다. transparent = 배경을 투명하게 남기는 값입니다. PNG처럼 알파 채널을 지원하는 형식과 함께 써야 합니다. 허용값: auto, opaque, transparent

- `reference_image` (file, 선택): 생성 경로 전용. 제품·인물·색감·구도를 참고할 이미지 1장. 원본을 고치지 않고 프롬프트에 맞는 새 장면을 만듭니다.



### 응답 명세

```json

{
  "type": "object",
  "description": "공개 JSON 응답.",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "description": "이미지 생성 요청 ID."
        },
        "image_count": {
          "type": "integer",
          "description": "생성된 이미지 수."
        },
        "idempotent_replay": {
          "type": "boolean",
          "description": "호환용 필드입니다. 같은 요청도 매번 새로 생성하므로 true가 되지 않습니다."
        },
        "images": {
          "type": "array",
          "description": "생성한 이미지 목록.",
          "items": {
            "type": "object",
            "properties": {
              "index": {
                "type": "integer",
                "description": "0부터 시작하는 이미지 번호."
              },
              "b64_json": {
                "type": "string",
                "description": "이미지 바이트의 Base64 문자열."
              },
              "mime_type": {
                "type": "string",
                "description": "이미지 MIME.",
                "enum": [
                  "image/png",
                  "image/jpeg",
                  "image/webp"
                ]
              },
              "width": {
                "type": "integer",
                "description": "이미지 너비(픽셀)."
              },
              "height": {
                "type": "integer",
                "description": "이미지 높이(픽셀)."
              }
            }
          }
        }
      }
    },
    "api": {
      "type": "object",
      "description": "호출 메타데이터.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다."
        },
        "cost": {
          "type": "number",
          "description": "이번 호출에서 차감한 포인트. 무료 조회·재전송은 0."
        },
        "pl_id": {
          "type": "integer",
          "description": "과금 기록 ID. 과금 기록이 있을 때만 포함합니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "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
  }
}

```

### curl

```curl

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'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("prompt", "오프화이트 스튜디오 배경, 무광 세라믹 화병 하나, 창문으로 들어오는 부드러운 오전 햇빛, 자연스러운 그림자, 고급 제품 사진, 이미지 안에 글자 없음");
form.append("image_count", "2");
form.append("size", "1024x1024");
form.append("output_format", "webp");
form.append("background", "opaque");
form.append("quality", "advanced");
const response = await fetch("https://apick.app/rest/image-generation/generate", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("prompt", (None, "오프화이트 스튜디오 배경, 무광 세라믹 화병 하나, 창문으로 들어오는 부드러운 오전 햇빛, 자연스러운 그림자, 고급 제품 사진, 이미지 안에 글자 없음")),
    ("image_count", (None, "2")),
    ("size", (None, "1024x1024")),
    ("output_format", (None, "webp")),
    ("background", (None, "opaque")),
    ("quality", (None, "advanced")),
]
response = requests.request("POST", "https://apick.app/rest/image-generation/generate",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'prompt' => '오프화이트 스튜디오 배경, 무광 세라믹 화병 하나, 창문으로 들어오는 부드러운 오전 햇빛, 자연스러운 그림자, 고급 제품 사진, 이미지 안에 글자 없음',
    'image_count' => '2',
    'size' => '1024x1024',
    'output_format' => 'webp',
    'background' => 'opaque',
    'quality' => 'advanced',
];
$curl = curl_init('https://apick.app/rest/image-generation/generate');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## POST /rest/image-generation/edit 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.request_id` (string): 이미지 생성 요청의 고유 ID입니다. 같은 요청을 추적하거나 문의할 때 사용합니다.

- `data.image_count` (integer): 이번 응답에 포함된 생성 이미지 수입니다. 요청 이미지 수와 다를 수 있습니다.

- `data.idempotent_replay` (boolean): 호환용 필드입니다. 같은 요청도 매번 새로 생성하므로 true가 되지 않습니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.

- `data.images` (array): 이미지 목록입니다. 상품 조회에서는 이미지 주소 문자열이, 이미지 생성에서는 이미지 데이터·MIME·크기를 담은 객체가 들어갑니다. 값이 없으면 빈 배열입니다.

- `data.images[].index` (integer): 0부터 시작하는 이미지 번호. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.images[].b64_json` (string): 이미지 바이트의 Base64 문자열. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.images[].mime_type` (string): 이미지 MIME. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. 가능한 값은 3가지입니다. image/png = PNG 이미지 MIME입니다. 알파 채널(투명 배경)을 보존합니다. image/jpeg = JPEG 이미지 MIME입니다. 압축 손실이 있으며 알파 채널은 없습니다. image/webp = WEBP 이미지 MIME입니다. 같은 화질에서 용량이 작습니다. 허용값: image/png, image/jpeg, image/webp

- `data.images[].width` (integer): 이미지 너비(픽셀). 이미지·영상의 가로 크기(픽셀)입니다. 화면 배치 전에 원본 비율을 확인하세요.

- `data.images[].height` (integer): 이미지 높이(픽셀). 이미지·영상의 세로 크기(픽셀)입니다. width와 함께 원본 비율을 계산할 수 있습니다.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (number): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/image-generation/edit



### 입력

- `prompt` (string, 필수): 생성·편집할 이미지에 대한 설명입니다. 최대 28,000자까지 보낼 수 있으며, 피사체·배경·구도·화풍을 구체적으로 적을수록 결과가 안정적입니다.

- `image_count` (integer, 선택): 생성할 이미지 수. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50입니다. 기본값: 1

- `quality` (string, 선택): 이미지 품질. basic(기본) 40P, advanced(고급) 350P, premium(최고급) 1,400P(장당). 기본 basic 가능한 값은 3가지입니다. basic = 가장 낮은 품질·가장 빠른 처리 등급입니다. 초안·대량 생성에 적합하고 단가가 가장 낮습니다. advanced = 중간 품질 등급입니다. 기본과 프리미엄의 중간 속도·품질·단가를 가집니다. premium = 가장 높은 품질 등급입니다. 해상도·디테일이 좋은 대신 처리 시간과 단가가 가장 높습니다. 허용값: basic, advanced, premium

- `size` (string, 선택): 출력 이미지의 크기입니다. 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_format` (string, 선택): 생성 결과의 파일 형식입니다. png·jpeg·webp 중 선택하며, 생략하면 서비스 기본값(png)을 사용합니다. 투명 배경이 필요하면 png를 선택하세요. 가능한 값은 3가지입니다. png = 무손실 PNG 형식입니다. 투명 배경이 필요할 때 사용합니다. jpeg = 압축률이 높은 JPG 형식입니다. 사진·배경이 있는 이미지에 적합합니다. webp = 용량이 작은 WEBP 형식입니다. 웹 표시에 적합하며 일부 구형 뷰어는 지원하지 않습니다. 허용값: png, jpeg, webp

- `background` (string, 선택): 이미지 배경을 투명·불투명 중 어떻게 처리할지 정합니다. transparent는 배경 제거, opaque는 원본 배경 유지이며, 지원 여부는 모델·출력 형식에 따라 다릅니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. opaque = 배경을 불투명하게 채우는 값입니다. JPG처럼 알파 채널이 없는 형식과 호환됩니다. transparent = 배경을 투명하게 남기는 값입니다. PNG처럼 알파 채널을 지원하는 형식과 함께 써야 합니다. 허용값: auto, opaque, transparent

- `image` (file, 필수): 편집 경로 전용이며 필수. 바꿀 원본 이미지 1장. 유지할 부분과 바꿀 부분을 프롬프트에 함께 적으세요.



### 응답 명세

```json

{
  "type": "object",
  "description": "공개 JSON 응답.",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "description": "이미지 생성 요청 ID."
        },
        "image_count": {
          "type": "integer",
          "description": "생성된 이미지 수."
        },
        "idempotent_replay": {
          "type": "boolean",
          "description": "호환용 필드입니다. 같은 요청도 매번 새로 생성하므로 true가 되지 않습니다."
        },
        "images": {
          "type": "array",
          "description": "생성한 이미지 목록.",
          "items": {
            "type": "object",
            "properties": {
              "index": {
                "type": "integer",
                "description": "0부터 시작하는 이미지 번호."
              },
              "b64_json": {
                "type": "string",
                "description": "이미지 바이트의 Base64 문자열."
              },
              "mime_type": {
                "type": "string",
                "description": "이미지 MIME.",
                "enum": [
                  "image/png",
                  "image/jpeg",
                  "image/webp"
                ]
              },
              "width": {
                "type": "integer",
                "description": "이미지 너비(픽셀)."
              },
              "height": {
                "type": "integer",
                "description": "이미지 높이(픽셀)."
              }
            }
          }
        }
      }
    },
    "api": {
      "type": "object",
      "description": "호출 메타데이터.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다."
        },
        "cost": {
          "type": "number",
          "description": "이번 호출에서 차감한 포인트. 무료 조회·재전송은 0."
        },
        "pl_id": {
          "type": "integer",
          "description": "과금 기록 ID. 과금 기록이 있을 때만 포함합니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "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
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/image-generation/edit' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=잔잔한 바닷가를 표현해 주세요.' \
  --form 'image=@/path/to/input.file'

```

### Node.js (서버 ESM)

```javascript

import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("prompt", "잔잔한 바닷가를 표현해 주세요.");
form.append("image", new Blob([await readFile("/path/to/input.file")]), "input.file");
const response = await fetch("https://apick.app/rest/image-generation/edit", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("prompt", (None, "잔잔한 바닷가를 표현해 주세요.")),
    ("image", ("input.file", open("/path/to/input.file", "rb"))),
]
response = requests.request("POST", "https://apick.app/rest/image-generation/edit",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'prompt' => '잔잔한 바닷가를 표현해 주세요.',
    'image' => new CURLFile('/path/to/input.file'),
];
$curl = curl_init('https://apick.app/rest/image-generation/edit');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## POST /rest/image-generation/jobs/generate 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.job_id` (string): 접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

- `data.status` (string): 현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다.

- `data.requested_count` (integer): 요청한 이미지 수입니다. 실제 생성 수와 비교해 실패 여부를 확인하세요.

- `data.cost_per_image` (number): 이미지 1장당 접수 시 단가(포인트). 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.prepaid_point` (number): 선결제 포인트. 접수 시 미리 차감한 포인트입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.idempotent_replay` (boolean): 호환용 필드로 항상 false입니다. 같은 요청도 매번 새 작업으로 접수합니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (number): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/image-generation/jobs/generate



### 입력

- `prompt` (string, 필수): 생성·편집할 이미지에 대한 설명입니다. 최대 28,000자까지 보낼 수 있으며, 피사체·배경·구도·화풍을 구체적으로 적을수록 결과가 안정적입니다.

- `image_count` (integer, 선택): 생성할 이미지 수. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50입니다. 기본값: 1

- `quality` (string, 선택): 이미지 품질. basic(기본) 40P, advanced(고급) 350P, premium(최고급) 1,400P(장당). 기본 basic 가능한 값은 3가지입니다. basic = 가장 낮은 품질·가장 빠른 처리 등급입니다. 초안·대량 생성에 적합하고 단가가 가장 낮습니다. advanced = 중간 품질 등급입니다. 기본과 프리미엄의 중간 속도·품질·단가를 가집니다. premium = 가장 높은 품질 등급입니다. 해상도·디테일이 좋은 대신 처리 시간과 단가가 가장 높습니다. 허용값: basic, advanced, premium

- `size` (string, 선택): 출력 이미지의 크기입니다. 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_format` (string, 선택): 생성 결과의 파일 형식입니다. png·jpeg·webp 중 선택하며, 생략하면 서비스 기본값(png)을 사용합니다. 투명 배경이 필요하면 png를 선택하세요. 가능한 값은 3가지입니다. png = 무손실 PNG 형식입니다. 투명 배경이 필요할 때 사용합니다. jpeg = 압축률이 높은 JPG 형식입니다. 사진·배경이 있는 이미지에 적합합니다. webp = 용량이 작은 WEBP 형식입니다. 웹 표시에 적합하며 일부 구형 뷰어는 지원하지 않습니다. 허용값: png, jpeg, webp

- `background` (string, 선택): 이미지 배경을 투명·불투명 중 어떻게 처리할지 정합니다. transparent는 배경 제거, opaque는 원본 배경 유지이며, 지원 여부는 모델·출력 형식에 따라 다릅니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. opaque = 배경을 불투명하게 채우는 값입니다. JPG처럼 알파 채널이 없는 형식과 호환됩니다. transparent = 배경을 투명하게 남기는 값입니다. PNG처럼 알파 채널을 지원하는 형식과 함께 써야 합니다. 허용값: auto, opaque, transparent

- `reference_image` (file, 선택): 생성 경로 전용. 제품·인물·색감·구도를 참고할 이미지 1장. 원본을 고치지 않고 프롬프트에 맞는 새 장면을 만듭니다.



### 응답 명세

```json

{
  "type": "object",
  "description": "공개 JSON 응답.",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "job_id": {
          "type": "string",
          "description": "접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다."
        },
        "status": {
          "type": "string",
          "description": "접수 또는 재전송 시점의 작업 상태."
        },
        "requested_count": {
          "type": "integer",
          "description": "요청 이미지 수."
        },
        "cost_per_image": {
          "type": "number",
          "description": "이미지 1장당 접수 시 단가(포인트)."
        },
        "prepaid_point": {
          "type": "number",
          "description": "선결제 포인트."
        },
        "idempotent_replay": {
          "type": "boolean",
          "description": "호환용 필드로 항상 false입니다. 같은 요청도 매번 새 작업으로 접수합니다."
        }
      }
    },
    "api": {
      "type": "object",
      "description": "호출 메타데이터.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다."
        },
        "cost": {
          "type": "number",
          "description": "이번 호출에서 차감한 포인트. 무료 조회·재전송은 0."
        },
        "pl_id": {
          "type": "integer",
          "description": "과금 기록 ID. 과금 기록이 있을 때만 포함합니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "7c1e0a9b8d6f4e3a2b1c0d9e8f7a6b5c",
    "status": "waiting",
    "requested_count": 20,
    "cost_per_image": 40,
    "prepaid_point": 800,
    "idempotent_replay": false
  },
  "api": {
    "success": true,
    "cost": 800
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/image-generation/jobs/generate' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=잔잔한 바닷가를 표현해 주세요.'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("prompt", "잔잔한 바닷가를 표현해 주세요.");
const response = await fetch("https://apick.app/rest/image-generation/jobs/generate", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("prompt", (None, "잔잔한 바닷가를 표현해 주세요.")),
]
response = requests.request("POST", "https://apick.app/rest/image-generation/jobs/generate",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'prompt' => '잔잔한 바닷가를 표현해 주세요.',
];
$curl = curl_init('https://apick.app/rest/image-generation/jobs/generate');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## POST /rest/image-generation/jobs/edit 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.job_id` (string): 접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

- `data.status` (string): 현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다.

- `data.requested_count` (integer): 요청한 이미지 수입니다. 실제 생성 수와 비교해 실패 여부를 확인하세요.

- `data.cost_per_image` (number): 이미지 1장당 접수 시 단가(포인트). 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.prepaid_point` (number): 선결제 포인트. 접수 시 미리 차감한 포인트입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.idempotent_replay` (boolean): 호환용 필드로 항상 false입니다. 같은 요청도 매번 새 작업으로 접수합니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (number): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/image-generation/jobs/edit



### 입력

- `prompt` (string, 필수): 생성·편집할 이미지에 대한 설명입니다. 최대 28,000자까지 보낼 수 있으며, 피사체·배경·구도·화풍을 구체적으로 적을수록 결과가 안정적입니다.

- `image_count` (integer, 선택): 생성할 이미지 수. 동기 생성·편집은 1~4, 작업형 생성·편집은 1~50입니다. 기본값: 1

- `quality` (string, 선택): 이미지 품질. basic(기본) 40P, advanced(고급) 350P, premium(최고급) 1,400P(장당). 기본 basic 가능한 값은 3가지입니다. basic = 가장 낮은 품질·가장 빠른 처리 등급입니다. 초안·대량 생성에 적합하고 단가가 가장 낮습니다. advanced = 중간 품질 등급입니다. 기본과 프리미엄의 중간 속도·품질·단가를 가집니다. premium = 가장 높은 품질 등급입니다. 해상도·디테일이 좋은 대신 처리 시간과 단가가 가장 높습니다. 허용값: basic, advanced, premium

- `size` (string, 선택): 출력 이미지의 크기입니다. 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_format` (string, 선택): 생성 결과의 파일 형식입니다. png·jpeg·webp 중 선택하며, 생략하면 서비스 기본값(png)을 사용합니다. 투명 배경이 필요하면 png를 선택하세요. 가능한 값은 3가지입니다. png = 무손실 PNG 형식입니다. 투명 배경이 필요할 때 사용합니다. jpeg = 압축률이 높은 JPG 형식입니다. 사진·배경이 있는 이미지에 적합합니다. webp = 용량이 작은 WEBP 형식입니다. 웹 표시에 적합하며 일부 구형 뷰어는 지원하지 않습니다. 허용값: png, jpeg, webp

- `background` (string, 선택): 이미지 배경을 투명·불투명 중 어떻게 처리할지 정합니다. transparent는 배경 제거, opaque는 원본 배경 유지이며, 지원 여부는 모델·출력 형식에 따라 다릅니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. opaque = 배경을 불투명하게 채우는 값입니다. JPG처럼 알파 채널이 없는 형식과 호환됩니다. transparent = 배경을 투명하게 남기는 값입니다. PNG처럼 알파 채널을 지원하는 형식과 함께 써야 합니다. 허용값: auto, opaque, transparent

- `image` (file, 필수): 편집 경로 전용이며 필수. 바꿀 원본 이미지 1장. 유지할 부분과 바꿀 부분을 프롬프트에 함께 적으세요.



### 응답 명세

```json

{
  "type": "object",
  "description": "공개 JSON 응답.",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "job_id": {
          "type": "string",
          "description": "접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다."
        },
        "status": {
          "type": "string",
          "description": "접수 또는 재전송 시점의 작업 상태."
        },
        "requested_count": {
          "type": "integer",
          "description": "요청 이미지 수."
        },
        "cost_per_image": {
          "type": "number",
          "description": "이미지 1장당 접수 시 단가(포인트)."
        },
        "prepaid_point": {
          "type": "number",
          "description": "선결제 포인트."
        },
        "idempotent_replay": {
          "type": "boolean",
          "description": "호환용 필드로 항상 false입니다. 같은 요청도 매번 새 작업으로 접수합니다."
        }
      }
    },
    "api": {
      "type": "object",
      "description": "호출 메타데이터.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다."
        },
        "cost": {
          "type": "number",
          "description": "이번 호출에서 차감한 포인트. 무료 조회·재전송은 0."
        },
        "pl_id": {
          "type": "integer",
          "description": "과금 기록 ID. 과금 기록이 있을 때만 포함합니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "7c1e0a9b8d6f4e3a2b1c0d9e8f7a6b5c",
    "status": "waiting",
    "requested_count": 20,
    "cost_per_image": 40,
    "prepaid_point": 800,
    "idempotent_replay": false
  },
  "api": {
    "success": true,
    "cost": 800
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/image-generation/jobs/edit' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=잔잔한 바닷가를 표현해 주세요.' \
  --form 'image=@/path/to/input.file'

```

### Node.js (서버 ESM)

```javascript

import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("prompt", "잔잔한 바닷가를 표현해 주세요.");
form.append("image", new Blob([await readFile("/path/to/input.file")]), "input.file");
const response = await fetch("https://apick.app/rest/image-generation/jobs/edit", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("prompt", (None, "잔잔한 바닷가를 표현해 주세요.")),
    ("image", ("input.file", open("/path/to/input.file", "rb"))),
]
response = requests.request("POST", "https://apick.app/rest/image-generation/jobs/edit",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'prompt' => '잔잔한 바닷가를 표현해 주세요.',
    'image' => new CURLFile('/path/to/input.file'),
];
$curl = curl_init('https://apick.app/rest/image-generation/jobs/edit');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## GET /rest/image-generation/jobs/:job_id 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.job_id` (string): 접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

- `data.status` (string): 현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 5가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. completed_partial = 일부만 완료된 상태입니다. 요청 수·완료 수·실패 수를 비교해 실패분만 다시 요청할지 판단합니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다. 허용값: waiting, processing, completed, completed_partial, failed

- `data.requested_count` (integer): 요청한 이미지 수입니다. 실제 생성 수와 비교해 실패 여부를 확인하세요.

- `data.completed_count` (integer): 정상 생성된 이미지 수입니다. requested_count보다 작으면 일부 실패입니다.

- `data.failed_count` (integer): 생성에 실패한 이미지 수입니다. 0이 아니면 error_code를 확인하세요.

- `data.prepaid_point` (number): 선결제 포인트. 접수 시 미리 차감한 포인트입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.refunded_point` (number): 환급 포인트. 작업 실패·취소로 돌려받은 포인트입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.charged_point` (number): 최종 차감된 포인트입니다. 실패·부분 성공 시 환급이 반영된 값입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.result_available` (boolean): 결과 파일을 지금 내려받을 수 있는지 여부입니다. false면 아직 처리 중이거나 결과가 만료·삭제된 상태입니다. true = 결과 파일을 지금 내려받을 수 있는 경우, false = 처리 중이거나 실패·만료된 경우입니다.

- `data.expires_at` (string): 결과 만료 일시. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `data.error_code` (string): 작업 실패 코드. 오류가 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (number): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## 상태·목록 조회: GET /rest/image-generation/jobs/:job_id



### 입력



### 응답 명세

```json

{
  "type": "object",
  "description": "공개 JSON 응답.",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "job_id": {
          "type": "string",
          "description": "접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다."
        },
        "status": {
          "type": "string",
          "description": "작업 상태.",
          "enum": [
            "waiting",
            "processing",
            "completed",
            "completed_partial",
            "failed"
          ]
        },
        "requested_count": {
          "type": "integer",
          "description": "요청 이미지 수."
        },
        "completed_count": {
          "type": "integer",
          "description": "완료 이미지 수."
        },
        "failed_count": {
          "type": "integer",
          "description": "실패 이미지 수."
        },
        "prepaid_point": {
          "type": "number",
          "description": "선결제 포인트."
        },
        "refunded_point": {
          "type": "number",
          "description": "환급 포인트."
        },
        "charged_point": {
          "type": "number",
          "description": "최종 차감 포인트."
        },
        "result_available": {
          "type": "boolean",
          "description": "다운로드 가능한 결과가 있는지 여부."
        },
        "expires_at": {
          "type": "string",
          "description": "결과 만료 일시.",
          "nullable": true
        },
        "error_code": {
          "type": "string",
          "description": "작업 실패 코드. 오류가 없으면 null.",
          "nullable": true
        }
      }
    },
    "api": {
      "type": "object",
      "description": "호출 메타데이터.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다."
        },
        "cost": {
          "type": "number",
          "description": "이번 호출에서 차감한 포인트. 무료 조회·재전송은 0."
        },
        "pl_id": {
          "type": "integer",
          "description": "과금 기록 ID. 과금 기록이 있을 때만 포함합니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "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
  }
}

```

### curl

```curl

curl --fail-with-body --request GET "https://apick.app/rest/image-generation/jobs/${APICK_JOB_ID}" \
  --header "Authorization: Bearer $APICK_API_KEY"

```

### Node.js (서버 ESM)

```javascript

const response = await fetch(`https://apick.app/rest/image-generation/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/image-generation/jobs/{job_id}".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/image-generation/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## GET /rest/image-generation/jobs/:job_id/images/:index 응답 필드

## 결과 받기: GET /rest/image-generation/jobs/:job_id/images/:index



### 입력



### 응답 명세

```json

{
  "type": "string",
  "format": "binary"
}

```

### curl

```curl

curl --fail-with-body --request GET "https://apick.app/rest/image-generation/jobs/${APICK_JOB_ID}/images/${APICK_INDEX}" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --dump-header response.headers --output result.png
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.

```

### Node.js (서버 ESM)

```javascript

const response = await fetch(`https://apick.app/rest/image-generation/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/images/${encodeURIComponent(process.env.APICK_INDEX)}`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.png", new Uint8Array(await response.arrayBuffer()));

```

### python

```python

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/image-generation/jobs/{job_id}/images/{index}".format(job_id=quote(os.environ["APICK_JOB_ID"], safe=""), index=quote(os.environ["APICK_INDEX"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.png", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/image-generation/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/images/' . rawurlencode(getenv('APICK_INDEX')) . '');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.png', $body);

```

## GET /rest/image-generation/jobs/:job_id/result 응답 필드

## 결과 받기: GET /rest/image-generation/jobs/:job_id/result



### 입력



### 응답 명세

```json

{
  "type": "string",
  "format": "binary"
}

```

### curl

```curl

curl --fail-with-body --request GET "https://apick.app/rest/image-generation/jobs/${APICK_JOB_ID}/result" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --dump-header response.headers --output result.zip
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.

```

### Node.js (서버 ESM)

```javascript

const response = await fetch(`https://apick.app/rest/image-generation/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/result`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.zip", new Uint8Array(await response.arrayBuffer()));

```

### python

```python

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/image-generation/jobs/{job_id}/result".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.zip", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/image-generation/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/result');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.zip', $body);

```

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

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

```bash

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. 참고 이미지로 새 장면 만들기

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

```bash

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. 원본 일부만 바꾸기

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

```bash

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를 함께 보냅니다.

```bash

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장을 작업으로 접수

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

```bash

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초 간격으로 조회합니다. 무료입니다.

```bash

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`로 내려받습니다.

## 코드·오류

- 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): 잠시 후 다시 시도하세요.

## 상세 기능·요금

연동 순서 1경로 고르기결과를 바로 받으면 동기 경로(1~4장), 많이 만들거나 기다리지 않으려면 작업형 경로(1~50장)를 씁니다. 2요청 보내기프롬프트·장수·품질·크기·출력 형식을 정하고, 필요하면 참고 이미지나 편집 원본을 첨부합니다. 3결과 받기동기 경로는 응답의 images를 저장합니다. 작업형은 job_id로 상태를 조회한 뒤 한 장씩 또는 ZIP으로 내려받습니다. 어떤 경로를 써야 하나요? 방식경로이미지 수사용 시점 POST/rest/image-generation/generate1~4장텍스트만, 또는 참고 이미지 + 텍스트로 새 이미지를 만들고 결과를 바로 받습니다. POST/rest/image-generation/edit1~4장첨부한 원본의 색상·배경·요소·분위기를 바꾸고 결과를 바로 받습니다. POST/rest/image-generation/jobs/generate1~50장여러 장을 작업으로 접수하고 완료된 이미지를 나중에 내려받습니다. POST/rest/image-generation/jobs/edit1~50장원본 한 장에서 여러 편집 결과를 작업으로 만듭니다. GET/rest/image-generation/jobs/:job_id-작업 상태, 완료·실패 장수, 환급·차감 포인트를 조회합니다. 무료. GET/rest/image-generation/jobs/:job_id/images/:index1장완료된 결과 중 0부터 시작하는 index번 이미지를 파일로 받습니다. 무료. GET/rest/image-generation/jobs/:job_id/result전체완료된 결과를 ZIP 파일 하나로 받습니다. 무료. 차감·환급 규칙 접수된 요청은 취소할 수 없습니다.접수 응답을 받은 뒤에는 연결을 끊어도 처리가 계속됩니다. 보내기 전에 장수와 예상 포인트를 확인하세요. 상황포인트 처리 입력 오류로 접수 전 거절차감하지 않습니다. 예: 프롬프트 누락, 지원하지 않는 크기, 포인트 부족. 접수품질별 장당 요금 × 장수를 먼저 차감합니다. 일부 이미지 실패성공한 장의 요금만 확정하고 실패한 장의 요금은 돌려줍니다. 같은 요청을 다시 보냄새 요청으로 만들고 다시 차감합니다. 응답을 받지 못했다면 다시 보내기 전에 포인트 사용 내역을 확인하세요. size 고르기 size 값비율추천 용도 1024x10241:1 정사각형상품 이미지, SNS 피드, 아이콘, 정사각형 썸네일 1536x10243:2 가로형아티클 커버, 광고 배너, 웹사이트 대표 이미지, 풍경 1024x15362:3 세로형포스터, 전신 인물, 쇼츠·릴스 배경, 세로 광고 1152x8644:3 가로형문서 삽화, 프레젠테이션, 인테리어, 제품 설명 이미지 864x11523: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로 확인합니다. 취소 도구는 없습니다.

## 상세 요청

생성·편집 요청은 form-data로 보내며, 파일은 같은 요청에 첨부합니다. 아래에 없는 조정 옵션을 보내면 APICK_IMAGE_OPTION_NOT_SUPPORTED로 거절됩니다. 첨부 파일은 50MB 이하 PNG·JPEG·WebP 한 장입니다. 마스크 파일은 받지 않습니다. 같은 내용을 다시 보내도 결과를 재사용하지 않고 새로 만들어 다시 차감합니다. form-data 전체 예제 보기

## 상세 응답

응답 — 동기 생성·편집 data.images[]의 b64_json을 Base64 디코딩해 mime_type에 맞는 확장자로 저장합니다. api.cost는 확정된 차감 포인트입니다. 필드타입설명 data.request_idString요청 ID. 문의할 때 함께 알려 주세요. data.image_countInteger받은 이미지 수 data.images[].indexInteger0부터 시작하는 번호 data.images[].b64_jsonString이미지 파일의 Base64 문자열 data.images[].mime_typeStringimage/png·image/jpeg·image/webp data.images[].widthInteger이미지 너비(픽셀) data.images[].heightInteger이미지 높이(픽셀) data.error_codeString실패했을 때의 오류 코드. 사유는 data.error { "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.statusStringwaiting(대기)·processing(처리 중)·completed(전부 성공)·completed_partial(일부 성공)·failed(전부 실패) data.completed_countInteger완료한 장수 data.failed_countInteger실패한 장수 data.prepaid_pointNumber접수 때 먼저 차감한 포인트 data.refunded_pointNumber실패한 장에 대해 돌려준 포인트 data.charged_pointNumber현재 차감 포인트. 처리 중에는 아직 확정되지 않은 예약분이 포함되므로, 끝난 상태에서 최종 요금으로 확인합니다. data.result_availableBoolean내려받을 수 있는 결과가 있으면 true data.expires_atString/null결과 보관 만료 시각. 완료 후 24시간 동안 반복해서 내려받을 수 있습니다. data.error_codeString/null작업이 실패했을 때의 오류 코드 { "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)입니다.

## 상세 예제

호출 예시 텍스트만으로 생성하는 동기 호출 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기