메인 콘텐츠로 건너뛰기
POST
/
v1
/
images
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2-official",
    "prompt": "별이 빛나는 하늘 아래의 고대 성",
    "size": "16:9",
    "resolution": "2k",
    "quality": "high",
    "n": 1
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPTXXXXXXXXXXXXXXX"
    }
  ]
}

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2-official",
    "prompt": "별이 빛나는 하늘 아래의 고대 성",
    "size": "16:9",
    "resolution": "2k",
    "quality": "high",
    "n": 1
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPTXXXXXXXXXXXXXXX"
    }
  ]
}

​
Authorizations

​
Authorization
string
필수
모든 엔드포인트는 Bearer Token 인증이 필요합니다API 키 받기：API 키 관리 페이지 에서 API 키를 받으세요사용 시 요청 헤더에 추가：
Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
기본값:"gpt-image-2-official"
필수
이미지 생성 모델 이름gpt-image-2-official 로 고정 (OpenAI 공식 gpt-image-2 모델)
​
prompt
string
필수
이미지 생성을 위한 텍스트 설명
  • 한국어 / 영어 / 중국어 지원, 상세한 설명을 권장
  • 제출 전에 플랫폼의 민감어 / 안전 심사를 거칩니다. 위반 내용은 즉시 오류를 반환합니다
​
size
string
기본값:"1:1"
이미지 비율외부에서는 비율 값을 사용하며, 시스템 내부에서는 resolution 에 따라 실제 픽셀로 자동 매핑됩니다.13 가지 비율 지원：
  • 1:1 - 정사각형 (기본값, SNS 아바타 / 로고)
  • 3:2 - 가로 구도 (DSLR 카메라 일반 비율)
  • 2:3 - 세로 구도 (포스터 세로판)
  • 4:3 - 가로 구도 (클래식 모니터 / 슬라이드)
  • 3:4 - 세로 구도
  • 5:4 - 가로 구도
  • 4:5 - 세로 구도 (Instagram 세로판 게시물)
  • 16:9 - 가로 구도 (와이드 비디오 커버)
  • 9:16 - 세로 구도 (폰 풀스크린 / 숏 비디오 커버)
  • 2:1 - 가로 구도 (웹 배너)
  • 1:2 - 세로 구도
  • 21:9 - 가로 구도 (영화 울트라와이드)
  • 9:21 - 세로 구도
​
resolution
string
기본값:"1k"
해상도 등급 (신규 필드)실제 출력 해상도를 제어합니다.
  • 1k - 1024 기준, 일상 사용에 비용 효율적 (기본값)
  • 2k - 2048 기준, 포스터 / 고해상도 용도에 적합
  • 4k - 3840 기준, 6 가지 비율만 지원 (16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21)
지원되지 않는 4K 조합은 400 을 반환합니다 (OpenAI 단일 이미지 총 픽셀 상한 8,294,400 제한):
  • 1:1 × 4k ❌ (3840² = 14.7M 상한 초과)
  • 3:2 / 2:3 × 4k ❌ (3840×2560 = 9.83M 상한 초과)
  • 4:3 / 3:4 × 4k ❌ (3840×2880 = 11.06M 상한 초과)
  • 5:4 / 4:5 × 4k ❌ (3840×3072 = 11.80M 상한 초과)
이러한 비율을 고해상도로 출력하려면 resolution=2k 를 사용하세요 (최대 2048 변, 픽셀 예산 내).
​
quality
string
기본값:"auto"
이미지 품질
  • auto - 자동 (기본값, 보통 low 와 동일)
  • low - 빠르고 저렴, 윤곽 정도
  • medium - 균형형
  • high - 최고 정밀도 (4K + high 는 120 초 이상 소요 가능)
​
background
string
기본값:"auto"
배경 모드
  • auto - 자동 (기본값)
  • opaque - 불투명
  • transparent - ⚠️ gpt-image-2-official 은 투명 배경을 지원하지 않으며, 전달해도 시스템이 자동으로 auto 로 강등합니다
​
moderation
string
기본값:"auto"
모더레이션 강도
  • auto - 기본 모더레이션 강도
  • low - 보다 완화된 모더레이션
​
output_format
string
기본값:"png"
출력 포맷
  • png - 기본값
  • jpeg - 파일 크기가 작음
  • webp - 최신 브라우저에 최적
​
output_compression
integer
출력 압축 강도, 범위 0-100
  • jpeg / webp 에만 유효
​
n
integer
기본값:"1"
생성할 이미지 장수범위：1 ~ 4
반드시 순수 숫자 (예: 1) 를 입력하세요. 따옴표로 감싸지 마세요
​
image_urls
array
참조 이미지 URL 배열
​
mask_url
string
마스크 이미지 URL, 로컬 리터치 (inpainting) 용도
  • image_urls 와 함께 사용해야 합니다
  1. 마스크 이미지를 업로드하기 전에 Alpha 채널이「예」인지 확인하세요.
  2. 마스크 이미지 크기는 첫 번째 참조 이미지와 일치 해야 합니다.

​
사이즈 × 해상도 매핑 표

size × resolution → OpenAI 실제 픽셀 (13 비율 × 3 등급)：
size1k2k4k
1:11024×10242048×2048❌ 픽셀 상한 초과
3:21536×10242048×1360❌ 픽셀 상한 초과
2:31024×15361360×2048❌ 픽셀 상한 초과
4:31024×7682048×1536❌ 픽셀 상한 초과
3:4768×10241536×2048❌ 픽셀 상한 초과
5:41280×10242560×2048❌ 픽셀 상한 초과
4:51024×12802048×2560❌ 픽셀 상한 초과
16:91536×8642048×11523840×2160
9:16864×15361152×20482160×3840
2:12048×10242688×13443840×1920
1:21024×20481344×26881920×3840
21:92016×8642688×11523840×1648
9:21864×20161152×26881648×3840
참고：3:2 / 2:3 @ 2K 는 실제로 2048×1360 (1360 은 16 의 배수, 약 3:2, 오차 < 0.5%); 21:9 @ 4K 는 3840×1648 (정확한 2.33:1). 기타는 모두 정확한 비율입니다.

​
사용 시나리오 예시

텍스트-이미지 (최소 요청) 
{
  "model": "gpt-image-2-official",
  "prompt": "별이 빛나는 하늘 아래의 고대 성"
}
2K 고해상도 포스터 
{
  "model": "gpt-image-2-official",
  "prompt": "사이버펑크 야경",
  "size": "16:9",
  "resolution": "2k",
  "quality": "high",
  "output_format": "jpeg",
  "output_compression": 90
}
4K 배경화면 
{
  "model": "gpt-image-2-official",
  "prompt": "설산 일출 파노라마",
  "size": "16:9",
  "resolution": "4k",
  "quality": "high",
  "n": 1
}
이미지-이미지 (다중 참조 융합) 
{
  "model": "gpt-image-2-official",
  "prompt": "두 참조 이미지를 하나의 일러스트 포스터로 융합하고 주체 윤곽을 유지한다",
  "size": "1:1",
  "quality": "high",
  "image_urls": [
    "https://your-cdn.com/input-a.png",
    "https://your-cdn.com/input-b.png"
  ]
}
로컬 리터치 (mask) 
{
  "model": "gpt-image-2-official",
  "prompt": "배경을 사막 일몰로 바꾼다",
  "size": "1:1",
  "quality": "medium",
  "image_urls": ["https://your-cdn.com/photo.png"],
  "mask_url": "https://your-cdn.com/mask.png"
}
다중 생성 (n > 1) 
{
  "model": "gpt-image-2-official",
  "prompt": "Four minimalist poster variations of a red fox",
  "size": "1:1",
  "quality": "low",
  "n": 4
}
픽셀 문자열 직접 전달 (고급 사용법) 
{
  "model": "gpt-image-2-official",
  "prompt": "wide cinematic shot",
  "size": "3840x2160",
  "quality": "high"
}

​
Response

​
code
integer
응답 상태 코드
​
data
array
응답 데이터 배열

​
작업 결과 조회

제출 성공 후 task_id 가 반환됩니다. GET /v1/tasks/{task_id} 로 작업 상태를 폴링하세요. 자세한 내용은 작업 조회 API 참조.

​
성공 응답 예시

{
  "code": 200,
  "data": {
    "id": "task_01KPTXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "actual_time": 46,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-gpt_image_2_official_task_xxx_0.png"
          ],
          "expires_at": 1776928569
        }
      ]
    }
  }
}
작업 상태 흐름：submitted → in_progress → completed / failed. 이미지 가져오기：data.result.images[0].url[0].

​
폴링 권장사항

  • 첫 조회 지연：제출 후 10~20 초 기다린 뒤 첫 조회 실행
  • 조회 간격：3~5 초 권장
  • 타임아웃 참고：high + 2k/4k 조합은 최대 130 초 소요, 클라이언트 타임아웃 ≥ 180 초 권장
  • 배치 조회：여러 작업을 동시에 조회하려면 POST /v1/tasks/batch 사용