GPT-Image-2.5 이미지 생성

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.5-flare",
    "prompt": "비 오는 창가의 아늑한 독서 공간, 따뜻한 램프 조명",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

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

{
  "error": {
    "code": 400,
    "message": "잘못된 요청 매개변수",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "인증에 실패했습니다. API 키를 확인하세요.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "계정 잔액이 부족합니다",
    "type": "payment_required"
  }
}

POST

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.5-flare",
    "prompt": "비 오는 창가의 아늑한 독서 공간, 따뜻한 램프 조명",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

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

{
  "error": {
    "code": 400,
    "message": "잘못된 요청 매개변수",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "인증에 실패했습니다. API 키를 확인하세요.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "계정 잔액이 부족합니다",
    "type": "payment_required"
  }
}

모델 선택: gpt-image-2.5-flare는 더 빠르며 일상적인 고품질 이미지, 일괄 생성, 빠른 프로토타입에 적합합니다. gpt-image-2.5-sunburst는 편집 정확도를 우선하여 완성도 높은 상품 이미지, 광고 소재, 세밀한 다단계 편집에 적합합니다. 두 모델의 요금은 같습니다.

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.5-flare",
    "prompt": "비 오는 창가의 아늑한 독서 공간, 따뜻한 램프 조명",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

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

{
  "error": {
    "code": 400,
    "message": "잘못된 요청 매개변수",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "인증에 실패했습니다. API 키를 확인하세요.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "계정 잔액이 부족합니다",
    "type": "payment_required"
  }
}

인증

string

필수

모든 엔드포인트는 Bearer Token 인증을 사용합니다. API 키 페이지에서 키를 발급받으세요.

Authorization: Bearer YOUR_API_KEY

모델 선택

모델	특징	권장 용도
`gpt-image-2.5-flare`	빠른 기본 모델	소셜 콘텐츠, 상품 이미지, 시각 검색, 프로토타입, 일괄 생성
`gpt-image-2.5-sunburst`	편집 정확도 우선	완성형 상품 이미지, 광고 소재, 세밀한 다단계 편집

동일한 매개변수에서는 두 모델의 토큰 사용량과 가격이 같습니다. gpt-image-2보다 xhigh와 max가 추가되었으며, medium과 high의 출력 토큰은 이전 세대의 같은 이름 단계보다 약 4배 적습니다.

요청 매개변수

string

필수

gpt-image-2.5-flare 또는 gpt-image-2.5-sunburst.

string

필수

생성하거나 편집할 이미지 설명입니다. 피사체, 장면, 구도, 스타일, 조명, 유지하거나 변경할 요소를 구체적으로 작성하세요.

string

기본값:"auto"

출력 화면 비율 또는 정확한 픽셀 크기입니다.

auto: 프롬프트 또는 참조 이미지를 기준으로 자동 선택
비율: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3
정확한 크기(예: 1600x1200)

이미지 편집에서는 size를 생략하면 입력 이미지 비율과 resolution을 바탕으로 출력 크기를 계산합니다.

string

기본값:"1k"

해상도 단계: 1k, 2k, 4k. 정확한 픽셀 크기를 사용할 때는 무시됩니다.

string

기본값:"auto"

품질: low, medium, high, xhigh, max, auto.

xhigh와 max는 GPT-Image-2.5 전용입니다. gpt-image-2에 전송하면 자동 하향 없이 HTTP 400을 반환합니다.

integer

기본값:"1"

생성 이미지 수: 1~4. 문자열이 아닌 숫자로 전송하세요.

string

기본값:"png"

출력 형식: png, jpeg, webp.

integer

0~100의 압축 수준이며 jpeg와 webp에만 적용됩니다.

string

배경: transparent, opaque, auto.

transparent는 png 또는 webp와 함께 사용해야 합니다. JPEG는 알파 채널을 지원하지 않습니다.

string

기본값:"low"

콘텐츠 검토 수준: auto 또는 low. 생략하면 APIMart가 low를 명시적으로 전송하고, 명시한 auto는 그대로 전달합니다.

string[]

이미지 생성 또는 편집용 참조 이미지 URL로 최대 16장입니다. 이 필드를 전달하면 편집 모드가 활성화됩니다.공개 접근 가능한 HTTP(S) URL만 사용할 수 있습니다. 로컬 이미지는 POST /v1/uploads/images로 업로드한 뒤 반환된 url을 사용하세요.

string

국소 재그리기에 사용하는 마스크 이미지입니다. image_urls도 전달한 경우에만 적용됩니다. gpt-image-2.5-flare와 gpt-image-2.5-sunburst 모두 이 매개변수를 지원합니다.다음 형식 중 하나를 단일 문자열로 전달합니다.

서버가 직접 다운로드할 수 있는 HTTP(S) 이미지 URL
data:image/png;base64,... 형식의 PNG Data URL

마스크 요구 사항:

알파 투명 채널이 있는 PNG를 사용하고 입력 원본 이미지도 PNG 사용을 권장
픽셀 크기는 image_urls[0]과 정확히 같아야 함. 출력 size가 아니라 첫 번째 입력 원본 이미지에 맞춰야 함
완전히 투명한 픽셀(alpha=0)은 편집할 영역이며 나머지 영역은 보존에 사용됨
요청당 마스크는 한 장만 전달. 참조 이미지가 여러 장이어도 마스크는 첫 번째 입력 이미지에만 적용됨
일반 파일 크기 가이드는 50 MB 미만, mask 매개변수 설명은 4 MB 미만으로 안내합니다. 확인 전에는 더 엄격한 4 MB 기준을 사용

알파 채널이 없는 일반 흑백 이미지는 마스크로 바로 사용할 수 없습니다. APIMart는 알파 채널을 자동으로 추가하지 않으며 현재 마스크와 원본 이미지의 크기 일치 여부도 사전 검증하지 않으므로 호출 측에서 두 조건을 보장해야 합니다.

HTTP(S) URL은 쿠키나 추가 인증 헤더 없이 접근할 수 있어야 합니다. 서명 URL은 대기열과 실행 시간이 끝날 때까지 유효해야 합니다. 기본 다운로드 제한은 20 MB, 시간 제한은 60초이며 배포 설정에서 이 기본값을 재정의할 수 있습니다.마스크는 편집을 유도하지만 모델이 마스크 경계 밖 픽셀의 완전한 불변을 보장하지는 않습니다.

크기 규칙

너비와 높이는 모두 16의 배수
어느 한 변도 3840픽셀을 초과할 수 없음
긴 변과 짧은 변 비율은 3:1 이하
전체 픽셀 수는 655,360~8,294,400

2560×1440을 초과하는 해상도는 실험적이며 일반 해상도보다 안정성이 낮을 수 있습니다.

비율 및 해상도 매핑

`size`	`1k`	`2k`	`4k`
`1:1`	1024×1024	2048×2048	2880×2880
`3:2`	1536×1024	2048×1360	3520×2336
`2:3`	1024×1536	1360×2048	2336×3520
`4:3`	1024×768	2048×1536	3312×2480
`3:4`	768×1024	1536×2048	2480×3312
`5:4`	1280×1024	2560×2048	3216×2576
`4:5`	1024×1280	2048×2560	2576×3216
`16:9`	1536×864	2048×1152	3840×2160
`9:16`	864×1536	1152×2048	2160×3840
`2:1`	2048×1024	2688×1344	3840×1920
`1:2`	1024×2048	1344×2688	1920×3840
`21:9`	2016×864	2688×1152	3840×1648
`9:21`	864×2016	1152×2688	1648×3840
`3:1`	1536×512	3072×1024	3840×1280
`1:3`	512×1536	1024×3072	1280×3840

모든 크기 규칙을 충족한다면 표에 없는 정확한 크기도 사용할 수 있습니다.

편집 예시

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "상품과 패키지 문구를 유지하고 배경을 부드러운 미색 스튜디오로 교체한 뒤 자연스러운 그림자를 추가",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

마스크를 사용한 국소 재그리기

다음 예시는 마스크에서 완전히 투명한 영역만 편집합니다. 마스크 크기는 product.png와 같아야 합니다.

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "투명 마스크가 덮은 영역만 금색 리본으로 바꾸고 상품과 나머지 배경은 유지",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "quality": "xhigh"
}

제출 및 작업 조회

제출 성공 시 작업 ID는 data[0].task_id에 있습니다. 작업 상태 API를 2~5초마다 호출하여 completed 또는 failed가 될 때까지 확인하세요. 여러 작업은 POST /v1/tasks/batch로 조회할 수 있습니다.

{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "result": {
      "images": [{
        "url": ["https://upload.apimart.ai/f/image/example.png"],
        "expires_at": 1789000000
      }]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}

이미지 URL은 data.result.images[].url[]에 있습니다. 즉시 다운로드하여 별도로 저장하세요.

상태	의미
`submitted`	제출됨
`processing`	생성 중
`completed`	성공, `result.images` 사용 가능
`failed`	실패, `error.message` 확인, 예약 금액 환불

과금

GPT-Image-2.5는 실제 토큰 사용량에 따라 과금됩니다. 요금 페이지 또는 /api/pricing에서 계정의 현재 요금을 확인하세요.

항목	100만 토큰당 가격
이미지 출력	$30.00
이미지 입력	$8.00
캐시 이미지 입력	$2.00
텍스트 입력	$5.00
캐시 텍스트 입력	$1.25

1024×1024 `quality`	출력 토큰	공식 출력 비용
`low`	196	$0.00588
`medium`	439	$0.01317
`high`	1756	$0.05268
`xhigh`	3122	$0.09366
`max`	7024	$0.21072

quality: "auto"에서는 선택한 크기의 max 금액을 먼저 예약하고, 완료 후 실제 사용량으로 정산하여 차액을 반환합니다.

n > 1이면 예약 금액이 이미지 수에 비례해 증가합니다. 실패한 작업은 자동 환불됩니다.

제한 및 자주 발생하는 오류

항목	제한 또는 해결 방법
요청당 이미지	1~4
참조 이미지	최대 16장
출력 형식	PNG / JPEG / WebP
투명 배경	PNG / WebP만 지원
부분 이미지 스트리밍	미지원
잘못된 품질	`xhigh` / `max`는 GPT-Image-2.5 필요
잘못된 크기	픽셀 및 비율 범위 내에서 16의 배수 사용

Response

integer

응답 코드이며 제출 성공 시 200입니다.

array

제출 응답 데이터입니다.

표시 배열 항목

string

초기 상태는 submitted입니다.

string

상태와 결과 조회에 사용하는 고유 작업 ID입니다.

개요

모델

텍스트 시리즈

이미지 시리즈

비디오 시리즈

오디오 시리즈

모더레이션 시리즈

업로드 관리

작업 관리

계정 관리

GPT-Image-2.5 이미지 생성

인증

모델 선택

요청 매개변수

크기 규칙

비율 및 해상도 매핑

편집 예시

마스크를 사용한 국소 재그리기

제출 및 작업 조회

과금

제한 및 자주 발생하는 오류

Response

​인증

​모델 선택

​요청 매개변수

​크기 규칙

​비율 및 해상도 매핑

​편집 예시

​마스크를 사용한 국소 재그리기

​제출 및 작업 조회

​과금

​제한 및 자주 발생하는 오류

​Response

인증

모델 선택

요청 매개변수

크기 규칙

비율 및 해상도 매핑

편집 예시

마스크를 사용한 국소 재그리기

제출 및 작업 조회

과금

제한 및 자주 발생하는 오류

Response