본문으로 건너뛰기

GPT Image 2

프롬프트로 이미지를 생성하고 입력 이미지 편집하기

이미지 생성과 편집의 요청 필드와 허용 값, 출력 크기 조건, 투명 배경과 mask의 조건 및 문제 해결 방법을 설명합니다.

페이지 목차

지원 기능

GPT Image 2로 할 수 있는 일과 보낼 입력은 다음과 같습니다.

하려는 일입력확인할 절
새 이미지 생성prompt이미지 생성
입력 이미지 편집prompt와 이미지 파일 1~16개이미지 편집
편집할 영역 지정편집 입력에 mask 추가mask로 편집 영역 지정하기

결과는 응답 본문에 base64 문자열로 바로 받습니다. 작업 ID를 반환하지 않으므로 Jobs로 다시 조회하거나 비동기로 요청할 수 없습니다.

모델 코드와 엔드포인트

항목값
모델 코드gpt-image-2
생성Image Generations POST /v1/images/generations, JSON 본문
편집Image Edits POST /v1/images/edits, multipart/form-data 본문
결과 형식응답의 data[].b64_json(base64 문자열)

gpt-image-2는 AI 게이트웨이를 사용하는 모든 스페이스에 기본 제공됩니다. 별도 모델 배급 요청이나 OpenAI API 키는 필요하지 않습니다. 쓰던 AI 게이트웨이 API 키와 OpenAI 호환 클라이언트로 호출하면 됩니다.

요청 필드와 허용 값

-는 기본값이 명시되지 않았다는 뜻입니다. 모든 모델에 공통인 필드의 뜻은 각 엔드포인트 명세에 있습니다.

이미지 생성

요청 본문은 application/json으로 보냅니다.

필드타입요구 여부허용 값과 기본값설명
modelstring필수gpt-image-2호출할 모델 코드
promptstring필수-생성할 이미지를 설명하는 프롬프트
sizestring선택auto 또는 픽셀 단위 WIDTHxHEIGHT. 기본 auto. 예: 1024x1024, 1536x1024, 1024x1536출력 이미지의 크기. 출력 크기 조건 참고
qualitystring선택low, medium, high, auto. 기본 auto출력 이미지의 품질
ninteger선택1~10. 기본값 -생성할 이미지 수
backgroundstring선택auto, opaque 또는 지원될 때 transparent. 기본값 -배경. 투명 배경 참고

이미지 편집

요청 본문은 multipart/form-data로 보냅니다. 여러 이미지를 보낼 때는 파일마다 같은 이름의 image 파트를 추가합니다.

필드타입요구 여부허용 값과 기본값설명
modelstring필수gpt-image-2호출할 모델 코드
promptstring필수-입력 이미지의 편집 내용을 설명하는 프롬프트
imagefile 또는 file[]필수PNG, WebP 또는 JPG/JPEG 형식 1~16개. 파일당 최대 50MB편집할 이미지
maskfile선택최대 4MB PNG RGBA 이미지편집할 영역을 안내하는 이미지. mask로 편집 영역 지정하기 참고
sizestring선택auto 또는 픽셀 단위 WIDTHxHEIGHT. 기본 auto. 예: 1024x1024, 1536x1024, 1024x1536출력 이미지의 크기. 출력 크기 조건 참고
qualitystring선택low, medium, high, auto. 기본 auto출력 이미지의 품질
ninteger선택1~10. 기본값 -생성할 이미지 수

출력 크기 조건

size를 픽셀 단위로 직접 지정하면 다음 조건을 모두 만족해야 합니다.

조건허용 범위
가로와 세로모두 16의 배수
긴 변3,840픽셀 이하
긴 변과 짧은 변의 비율3:1 이하
총 픽셀 수655,360~8,294,400

모델의 크기 및 품질 조건 도 함께 확인합니다.

투명 배경

background: "transparent"는 공급사 Preview 범위에 속합니다. transparent가 모든 요청에서 제공된다고 가정하지 마세요. 옵션이 거부되었다는 오류 응답을 받으면 오류 상세를 확인하고 지원되는 값으로 수정합니다.

mask로 편집 영역 지정하기

편집 요청에 mask 파일을 추가하면 편집할 영역을 안내할 수 있습니다. cURL에서는 -F "mask=@mask.png"를 추가합니다. mask 파일은 다음 조건에 맞춰 준비합니다.

  • 알파 채널이 있는 PNG로 만듭니다. 완전히 투명한 영역(알파값 0)이 편집할 부분을 가리킵니다.
  • 여러 이미지를 보내면 mask는 첫 번째 이미지에 적용됩니다. mask의 가로와 세로 픽셀 수를 첫 번째 이미지와 맞춥니다.

mask는 편집 범위를 안내할 뿐이어서, 모델이 경계를 픽셀 단위로 정확히 지키지 않을 수 있습니다. mask 입력 조건 도 확인하세요.

요청 예시

이미지 생성은 다음과 같이 보냅니다. 예제는 환경 변수 LETSUR_API_KEY를 사용합니다.

cURL
curl https://gw.letsur.ai/v1/images/generations \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "푸른 하늘 아래 달리는 자동차", "size": "1024x1024", "n": 1 }'

현재 디렉터리의 input.png를 편집하려면 다음과 같이 보냅니다.

cURL
curl https://gw.letsur.ai/v1/images/edits \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -F "model=gpt-image-2" \ -F "prompt=배경을 푸른 하늘로 바꿔줘" \ -F "image=@input.png"

제한과 사용량

크기와 품질이 사용량과 처리 시간에 영향을 줍니다. 요청을 보내기 전에 현재 단가를 확인하세요.

이 호출의 비용은 응답의 estimated_cost에 들어 있습니다. 비용을 기록할 값과 식별자는 요청별 비용에서 확인합니다.

결과 받기

결과는 응답 본문의 base64 문자열로 받으므로 작업을 조회하지 않습니다. base64를 디코딩해 파일로 저장하는 Python 예제와 응답 필드는 Image Generations의 요청 예시와 결과 저장과 Image Edits의 요청 예시와 결과 저장에 있습니다.

문제 해결

증상다음 행동
invalid_image_file (400)편집 이미지의 형식, 크기와 개수가 이미지 편집의 조건에 맞는지 확인합니다
image_fetch_error (400)입력 이미지를 읽을 수 있는지 확인한 뒤 다시 보냅니다
크기나 옵션이 거부됨오류 응답의 detail을 확인하고 출력 크기 조건과 투명 배경에 맞게 수정합니다
응답을 받지 못함같은 요청을 다시 보내면 별도 호출로 처리되어 비용이 추가될 수 있습니다. 다시 보낼지는 재시도할 수 있는 경우에 따라 판단합니다

인증, 한도와 그 밖의 공통 오류는 오류 처리에 있습니다.