GPT Image 2 API 파라미터: 크기, 해상도, 화면비, 품질
이미지를 결정하는 GPT Image 2 API 파라미터: 모델 이름, 크기와 해상도, 화면비, 4K 제한, 품질, 출력 형식, 그리고 잘못된 값이 반환하는 오류를 정리합니다.
Markdown으로 읽기GPT Image 2 API는 모델 이름을 model에, 출력 크기를 size에 WIDTHxHEIGHT 픽셀로, 품질을 quality(low, medium, high 또는 auto)에 받습니다. resolution이나 aspect_ratio 필드는 없습니다. 16:9 이미지를 4K로 받으려면 "size": "3840x2160"을 보내세요. 크기는 16의 배수여야 하고, 두 변 모두 3840픽셀 이하, 비율은 1:33:1, 총 픽셀 수는 655,3608,294,400 사이여야 합니다.
이 가이드는 그림을 바꾸는 각 파라미터에 대해 보내야 할 정확한 값과 잘못된 값이 반환하는 오류를 다룹니다. 아래의 모든 오류는 실제 API로 확인했습니다.
API에서 GPT Image 2의 모델 이름은 무엇인가요?
gpt-image-2 또는 gpt-image-2-official을 사용하세요. 둘은 같은 필드를 쓰는 같은 모델입니다. gpt-image-2는 전달된 이미지 1장마다 고정 가격을 받고, gpt-image-2-official은 렌더링마다 보고된 토큰으로 과금합니다.
제목에 나오는 이름은 모델 ID로 쓸 수 없습니다. gpt-image-2.0, GPT Image 2, chatgpt-images-2는 모두 HTTP 400과 오류 코드 20002를 반환합니다.
해상도와 화면비는 어떻게 설정하나요?
size에 픽셀로 지정합니다. 원하는 화면비와 픽셀 규모를 고른 뒤, 그에 해당하는 너비와 높이를 보내세요.
| 화면비 | 약 1K | 약 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:2 | 1248x832 | 2496x1664 | 3504x2336 |
| 2:3 | 832x1248 | 1664x2496 | 2336x3504 |
| 4:3 | 1152x864 | 2304x1728 | 3264x2448 |
| 3:4 | 864x1152 | 1728x2304 | 2448x3264 |
| 16:9 | 1280x720 | 2560x1440 | 3840x2160 |
| 9:16 | 720x1280 | 1440x2560 | 2160x3840 |
| 21:9 | 1456x624 | 3024x1296 | 3808x1632 |
| 3:1 | 1728x576 | 3504x1168 | 3840x1280 |
이 값들은 Playground에서 비율과 1K, 2K, 4K 프리셋을 고를 때 쓰는 변환과 같습니다. 정사각형 4K가 2880x2880에서 멈추는 이유는 3840픽셀 정사각형이 총 픽셀 수 제한을 넘기 때문입니다.
size: "auto"는 크기를 모델에 맡깁니다. 기본값이고 편리하지만, 출력이 레이아웃이나 서로에 맞아야 할 때는 크기를 명시하세요.
OpenAI는 2560×1440을 넘는 출력을 실험적이라고 설명합니다. 여기서는 위 제한 안에서 허용되지만, 캔버스가 크다고 디테일이 더 많아진다는 보장은 없습니다.
어떤 size 값이 거부되나요?
| 보낸 값 | 실패 이유 | 응답 |
|---|---|---|
"size": "16:9" | 비율은 크기가 아님 | 400 20001, 메시지가 size를 알려 줌 |
"size": "4096x2304" | 변이 3840 초과 | 400 20001, 메시지가 size를 알려 줌 |
"size": "1000x1000" | 16의 배수가 아님 | 400 20001, 메시지가 size를 알려 줌 |
"size": "3840x1024" | 3:1보다 넓음 | 400 20001, 메시지가 size를 알려 줌 |
"resolution": "4k" | 알 수 없는 필드 | 400 20001, 필드 이름 없음 |
"aspect_ratio": "16:9" | 알 수 없는 필드 | 400 20001, 필드 이름 없음 |
마지막 두 행에 주목하세요. 알 수 없는 필드는 거부되지만, 오류가 그 필드 이름을 알려 주지는 않습니다. 20001과 일반 메시지 “Check the parameters against the API documentation”을 받았다면 resolution, aspect_ratio, response_format처럼 API가 받지 않는 필드가 있는지 찾아보세요.
품질은 무엇을 골라야 하나요?
quality는 low, medium, high, auto를 받습니다. 높은 단계일수록 시간이 더 걸리고 더 섬세한 디테일을 담습니다. xhigh와 max는 GPT Image 2.5 전용이며, GPT Image 2에 보내면 20001을 반환하고 메시지가 quality를 알려 줍니다.
실용적인 방법은 이렇습니다. 구도가 아직 바뀌는 동안에는 low로 초안을 만들고, 질감과 작은 글자는 medium으로 확인하고, 최종본은 high로 만드세요. gpt-image-2에서는 모든 단계의 가격이 같습니다. gpt-image-2-official에서는 높은 단계일수록 보고되는 출력 토큰이 많아 비용이 더 듭니다. 수치는 요금 가이드에 있습니다.
auto는 단계를 모델이 고르게 합니다. 실행 결과를 비교할 때는 값을 명시하세요. 그렇지 않으면 "동일한" 두 요청이 서로 다른 단계로 렌더링될 수 있습니다.
형식과 배경은 무엇으로 제어하나요?
output_format:png(기본값) 또는jpeg. WebP 출력은 제공하지 않으며,webp는20001을 반환하고 메시지가output_format을 알려 줍니다.output_compression: 0~100,jpeg에서만 사용.background:auto,opaque또는transparent. 투명 배경에는png가 필요하며,jpeg와 함께transparent를 보내면20001을 반환하고 메시지가background를 알려 줍니다.n: 요청당 이미지 1~10장. 전달된 이미지에 대해 과금됩니다.moderation:auto또는low.
참조 이미지와 마스크는 어떻게 전달하나요?
파일이나 base64가 아니라 URL로 전달합니다. images는 {"image_url": "https://..."} 형태의 객체를 1~16개 받으며, 이를 보내면 요청이 편집이 됩니다. mask는 같은 형태의 객체 하나를 받습니다. 첫 번째 참조 이미지와 같은 크기의 PNG로, 투명한 영역이 변경할 부분을 나타냅니다. 파일 제한은 레퍼런스에 나와 있습니다.
자주 묻는 질문
GPT Image 2는 4K를 지원하나요?
네, 위 제한 안에서 지원합니다. 16:9의 3840x2160과 9:16의 2160x3840이 가장 큰 프레임이며, 정사각형은 2880x2880이 가장 큽니다.
픽셀 대신 화면비를 보낼 수 있나요?
API에는 보낼 수 없습니다. 위 표나 Playground를 사용해 먼저 비율을 WIDTHxHEIGHT 크기로 변환하세요. Playground는 제출 전에 정확한 크기를 보여 줍니다.
기본 크기와 품질은 무엇인가요?
둘 다 기본값은 auto이며, 선택을 모델에 맡깁니다. 예측 가능한 출력이 필요하면 값을 명시하세요.
픽셀로 보내고, 품질을 정하고, 오류 메시지를 확인하세요
파라미터 문제는 거의 모두 세 가지 중 하나입니다. 비율을 크기로 보냈거나, API가 받지 않는 필드를 보냈거나, 제한을 벗어난 값을 보낸 경우입니다. 첫 번째와 세 번째는 오류 메시지가 필드 이름을 알려 주고, 필드 이름이 없는 일반 메시지는 두 번째를 가리킵니다. 연동하는 동안 이 페이지를 GPT Image 2 API 레퍼런스와 함께 곁에 두세요.
