GPT Image 2 이미지 생성

##모든 API는 Bearer Token 인증이 필요합니다## **API Key 받기:** [API Key 관리 페이지](https://starmagic.ai/app/api-keys)를 방문하여 API Key를 받으세요 **요청 헤더에 추가:** ``` Authorization: Bearer YOUR_API_KEY ```

Authorization: Bearer YOUR_API_KEY

이미지 생성 모델 이름, 공식 채널, 더 나은 안정성과 제어성, 상업적 시나리오에 적합

"gpt-image-2"

생성할 이미지를 설명하는 프롬프트, 또는 입력 이미지를 편집하는 방법을 설명하는 프롬프트 **제한:** - 최대 `32000`자 (유니코드 코드 포인트 기준, 한/중/일/영 등 모두 지원)

"바다 위의 화려하고 아름다운 석양"

이미지-이미지 및 이미지 편집 기능을 위한 참조 이미지 URL 목록 **참고:** - 요청당 입력 이미지 수: `1~16`개 - 단일 이미지 크기: 최대 `50MB` - 지원 형식: `.jpeg`, `.jpg`, `.png`, `.webp` - 이미지 URL은 서버에서 직접 접근 가능하거나, 접근 시 직접 다운로드되어야 합니다 (일반적으로 `.png`, `.jpg` 등 이미지 확장자로 끝나는 URL) - 이미지-이미지 / 이미지 편집 시나리오에서는 전달된 참조 이미지 자체도 추가 이미지 입력 토큰을 소모합니다

[
  "https://example.com/image1.png",
  "https://example.com/image2.png"
]

인페인팅 마스크 URL — 참조 이미지에서 다시 생성할 영역을 표시합니다. **이미지 편집 모드에서만 작동**합니다(반드시 `image_urls`와 함께 사용). 순수한 텍스트-투-이미지 요청에서는 마스크가 조용히 무시됩니다. **형식 요구사항:** - **알파 채널이 있는 PNG여야 합니다**: 투명 픽셀(`alpha < 255`) = 다시 생성할 영역, 불투명 픽셀 = 보존됨 - **마스크 크기는 참조 이미지와 정확히 일치**해야 합니다(너비 × 높이, 픽셀 단위) - 요청당 마스크는 1개만 지원 **참고:** - `image_urls`에 최소 1장의 참조 이미지가 필요합니다. 마스크만 보내면 효과가 없습니다 - 자주 발생하는 오류: - `Invalid mask image format - mask image missing alpha channel`: 업로드한 이미지에 알파 채널이 없습니다(JPEG, 불투명 PNG 등). 투명 영역이 있는 PNG로 다시 내보내세요. - `Invalid mask image format - mask size does not match image size`: 마스크와 참조 이미지의 크기가 일치하지 않습니다. 마스크를 참조 이미지와 동일한 픽셀 크기로 조정하세요.

"https://example.com/mask.png"

생성 이미지 크기. **비율 형식**과 **명시적 픽셀 형식** 두 가지를 지원하며, 기본값은 `auto` **① 비율 형식 (권장, 15가지)** - `1:1`: 정사각형 - `1:2` / `2:1`: 극단 세로 / 가로 - `1:3` / `3:1`: 초 세로 / 가로 (3:1 경계) - `2:3` / `3:2`: 표준 세로 / 가로 - `3:4` / `4:3`: 클래식 세로 / 가로 - `4:5` / `5:4`: 소셜 미디어 일반 - `9:16` / `16:9`: 모바일 / 데스크톱 와이드스크린 - `9:21` / `21:9`: 울트라와이드 **② 명시적 픽셀 형식**: `WxH` (또는 `W×H`), 예: `1024x1024`, `1536x1024`, `3840×2160` - 가로·세로 모두 `16`의 배수여야 함 - 각 변 범위: `[16, 3840]` - 픽셀 예산: `655,360 ≤ width × height ≤ 8,294,400` (약 0.65 MP ~ 8.29 MP) - 종횡비: `≤ 3:1` **③ `auto`**: 모델이 자동으로 크기를 결정 (이 경우 `resolution`은 적용되지 않음) **초과 처리:** - 비율 + `resolution` 조합이 픽셀 예산을 초과하면 비율을 유지한 채 자동으로 상한까지 축소됩니다 (예: 4K 2:1 → 3840×1920)

"auto"

해상도 티어 단축 파라미터. `size`가 비율 형식일 때만 유효하며, 명시적 픽셀 형식에서는 이 필드가 무시됩니다 **픽셀 버짓 규칙** (목표 총 픽셀 수와 `size` 비율에서 너비와 높이를 산출하며 16의 배수로 정렬됩니다): - `1K`: ~1 MP (1024² = 1,048,576 픽셀) - `2K`: ~4 MP (2048² = 4,194,304 픽셀) - `4K`: ~8.29 MP (3840×2160 = 8,294,400 픽셀, 최대값) **가로 / 정사각형 실제 출력 크기** (세로 크기는 대응하는 가로의 폭과 높이를 바꾼 것, 예: `2:3` = `3:2` 반전): | 비율 | 1K | 2K | 4K | |---|---|---|---| | `1:1` | 1024×1024 | 2048×2048 | 2880×2880 | | `2:1` | 1456×720 | 2896×1456 | 3840×1920 \* | | `3:1` | 1776×592 | 3552×1184 | 3840×1280 \* | | `3:2` | 1248×832 | 2512×1680 | 3520×2352 | | `4:3` | 1184×880 | 2368×1776 | 3312×2480 \* | | `5:4` | 1152×912 | 2288×1824 | 3216×2576 | | `16:9` | 1360×768 | 2736×1536 | 3840×2160 (UHD) | | `21:9` | 1568×672 | 3136×1344 | 3840×1632 \* | \* 는 픽셀 예산 초과로 비율을 유지한 채 자동 축소된 조합을 나타냅니다. 값은 대소문자를 구분하지 않습니다.

"1K"

렌더링 품질. 모델의 "사고 깊이"를 제어하며 출력 토큰 수와 비용에 직접적인 영향을 미칩니다. 기본값 `medium` | 값 | 타일 기수 | 상대 비용 (1024²) | |---|---|---| | `low` | 16 | ~0.11× | | `medium` | 48 | 1.0× | | `high` | 96 | ~4.0× |

"medium"

생성할 이미지 개수, 각각 독립적으로 과금됩니다 **참고:** - 텍스트 입력 토큰은 `n`에 비례하여 확대됩니다

1

작업 완료 후 HTTPS 콜백 주소 **콜백 타이밍:** - 작업이 완료, 실패 또는 취소될 때 트리거됨 - 과금 확인 완료 후 전송 **보안 제한:** - HTTPS 프로토콜만 지원 - 내부 IP 주소로의 콜백 금지 (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x 등) - URL 길이는 `2048`자를 초과할 수 없음 **콜백 메커니즘:** - 타임아웃: `10`초 - 실패 시 최대 `3`회 재시도 (`1`초/`2`초/`4`초 후 재시도) - 콜백 응답 본문 형식은 작업 조회 API 응답 형식과 동일 - 콜백 주소가 2xx 상태 코드를 반환하면 성공으로 간주, 다른 상태 코드는 재시도를 트리거

"https://your-domain.com/webhooks/image-task-completed"