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으로 보냅니다.
| 필드 | 타입 | 요구 여부 | 허용 값과 기본값 | 설명 |
|---|---|---|---|---|
model | string | 필수 | gpt-image-2 | 호출할 모델 코드 |
prompt | string | 필수 | - | 생성할 이미지를 설명하는 프롬프트 |
size | string | 선택 | auto 또는 픽셀 단위 WIDTHxHEIGHT. 기본 auto. 예: 1024x1024, 1536x1024, 1024x1536 | 출력 이미지의 크기. 출력 크기 조건 참고 |
quality | string | 선택 | low, medium, high, auto. 기본 auto | 출력 이미지의 품질 |
n | integer | 선택 | 1~10. 기본값 - | 생성할 이미지 수 |
background | string | 선택 | auto, opaque 또는 지원될 때 transparent. 기본값 - | 배경. 투명 배경 참고 |
이미지 편집
요청 본문은 multipart/form-data로 보냅니다. 여러 이미지를 보낼 때는 파일마다 같은 이름의 image 파트를 추가합니다.
| 필드 | 타입 | 요구 여부 | 허용 값과 기본값 | 설명 |
|---|---|---|---|---|
model | string | 필수 | gpt-image-2 | 호출할 모델 코드 |
prompt | string | 필수 | - | 입력 이미지의 편집 내용을 설명하는 프롬프트 |
image | file 또는 file[] | 필수 | PNG, WebP 또는 JPG/JPEG 형식 1~16개. 파일당 최대 50MB | 편집할 이미지 |
mask | file | 선택 | 최대 4MB PNG RGBA 이미지 | 편집할 영역을 안내하는 이미지. mask로 편집 영역 지정하기 참고 |
size | string | 선택 | auto 또는 픽셀 단위 WIDTHxHEIGHT. 기본 auto. 예: 1024x1024, 1536x1024, 1024x1536 | 출력 이미지의 크기. 출력 크기 조건 참고 |
quality | string | 선택 | low, medium, high, auto. 기본 auto | 출력 이미지의 품질 |
n | integer | 선택 | 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 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 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을 확인하고 출력 크기 조건과 투명 배경에 맞게 수정합니다 |
| 응답을 받지 못함 | 같은 요청을 다시 보내면 별도 호출로 처리되어 비용이 추가될 수 있습니다. 다시 보낼지는 재시도할 수 있는 경우에 따라 판단합니다 |
인증, 한도와 그 밖의 공통 오류는 오류 처리에 있습니다.