208 lines
6.1 KiB
Markdown
208 lines
6.1 KiB
Markdown
# GPT-Edit Technical Specifications
|
|
|
|
## OpenAI API 설정
|
|
|
|
### 고정 파라미터 (변경 불가)
|
|
OpenAI API 요구사항에 따라 다음 파라미터들은 고정값입니다:
|
|
|
|
```python
|
|
MODEL = "gpt-image-1" # OpenAI 이미지 편집 모델
|
|
INPUT_FIDELITY = "high" # 입력 이미지 충실도
|
|
QUALITY = "high" # 출력 품질
|
|
NUMBER_OF_IMAGES = 1 # 생성 이미지 수 (편집은 1개만 지원)
|
|
OUTPUT_FORMAT = "png" # 출력 형식
|
|
PARTIAL_IMAGES = 0 # 부분 이미지 (미지원)
|
|
RESPONSE_FORMAT = "b64_json" # API 응답 형식
|
|
```
|
|
|
|
### 지원 이미지 크기
|
|
OpenAI API가 지원하는 출력 크기:
|
|
- `256x256` - 가장 빠름, 토큰 제한 낮음
|
|
- `512x512` - 균형잡힌 선택
|
|
- `1024x1024` - 고품질 (기본값)
|
|
- `1024x1536` - 세로형 고품질
|
|
- `1536x1024` - 가로형 고품질
|
|
|
|
### 토큰 제한
|
|
프롬프트 길이는 이미지 크기에 따라 제한됩니다:
|
|
- `256x256`: ~1000 토큰
|
|
- `512x512`: ~1000 토큰
|
|
- `1024x1024`: ~1000 토큰
|
|
- `1024x1536`, `1536x1024`: ~750 토큰
|
|
|
|
## 이미지 처리 사양
|
|
|
|
### 입력 이미지
|
|
- **지원 형식**: PNG, JPEG, WebP, GIF, BMP
|
|
- **최대 크기**: 4MB (자동 최적화 가능)
|
|
- **최대 해상도**: 제한 없음 (자동 리사이징)
|
|
- **알파 채널**: PNG 투명도 지원
|
|
|
|
### 자동 최적화
|
|
4MB 이상 이미지는 자동으로 최적화됩니다:
|
|
1. WebP 압축 시도 (최고 품질 유지)
|
|
2. PNG 최적화 (WebP 실패 시)
|
|
3. 단계적 품질 감소 (95% → 85% → 75%)
|
|
4. 최종 수단: 해상도 축소
|
|
|
|
### 마스크 이미지
|
|
- **형식**: PNG 권장 (흑백)
|
|
- **크기**: 입력 이미지와 동일할 필요 없음 (자동 조정)
|
|
- **색상**: 흰색(255) = 편집 영역, 검정색(0) = 보존 영역
|
|
|
|
## API 제한사항
|
|
|
|
### Rate Limits
|
|
- **분당 요청**: 50 requests/min (Tier 2)
|
|
- **일일 요청**: 제한 없음 (크레딧 기반)
|
|
- **동시 요청**: 최대 5개
|
|
|
|
### 배치 처리
|
|
- **최대 배치 크기**: 16개 이미지
|
|
- **동시 처리**: asyncio 기반 병렬 처리
|
|
- **실패 처리**: 개별 실패는 전체 배치에 영향 없음
|
|
|
|
## 파일 시스템 사양
|
|
|
|
### 디렉토리 구조
|
|
```
|
|
project_root/
|
|
├── input_images/ # INPUT_PATH - 편집할 원본 이미지
|
|
│ ├── photo.jpg
|
|
│ └── mask.png
|
|
├── generated_images/ # GENERATED_IMAGES_PATH - 편집 결과
|
|
│ ├── gptimage1_20250824_143022_000.png # 원본 복사본
|
|
│ ├── gptimage1_20250824_143022_001.png # 편집 결과
|
|
│ └── gptimage1_20250824_143022_001.json # 메타데이터
|
|
└── temp/ # 임시 파일 (자동 정리)
|
|
```
|
|
|
|
### 파일명 구조
|
|
```
|
|
gptimage1_{yyyymmdd}_{hhmmss}_{number}.{ext}
|
|
```
|
|
|
|
- `gptimage1`: 구성 가능한 prefix
|
|
- `{yyyymmdd}`: 날짜 (예: 20250824)
|
|
- `{hhmmss}`: 시간 (예: 143022)
|
|
- `{number}`:
|
|
- `000`: 원본 복사본 (입력 파일)
|
|
- `001-999`: 편집 결과 파일
|
|
- `{ext}`: 파일 확장자
|
|
|
|
### JSON 파라미터 구조
|
|
```json
|
|
{
|
|
"base_name": "gptimage1_20250824_143022",
|
|
"timestamp": "2025-08-24T14:30:22.123456",
|
|
"prompt": "사용자 프롬프트",
|
|
"background": "transparent|opaque",
|
|
"input_image_name": "photo.jpg",
|
|
"input_temp_path": "/path/to/temp/photo.jpg",
|
|
"input_generated_path": "/path/to/generated/gptimage1_20250824_143022_000.png",
|
|
"input_size": [width, height],
|
|
"output_size": [width, height],
|
|
"execution_time": 3.45,
|
|
"optimization": {
|
|
"optimized": true,
|
|
"original_size_mb": 5.2,
|
|
"final_size_mb": 3.8,
|
|
"format_used": "PNG|WEBP",
|
|
"method": "압축 방법"
|
|
},
|
|
"token_stats": {
|
|
"estimated_tokens": 450,
|
|
"token_limit": 1000,
|
|
"usage_percentage": 45.0
|
|
},
|
|
"config": {
|
|
"model": "gpt-image-1",
|
|
"quality": "high",
|
|
"api_version": "gpt-image-1"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 성능 사양
|
|
|
|
### 처리 시간
|
|
- **일반 편집**: 2-5초
|
|
- **최적화 포함**: 3-7초
|
|
- **배치 처리**: 병렬 처리로 선형 증가 방지
|
|
|
|
### 메모리 사용
|
|
- **기본**: ~100MB
|
|
- **대용량 이미지**: 최대 500MB
|
|
- **배치 처리**: 이미지당 ~50MB 추가
|
|
|
|
## 에러 처리
|
|
|
|
### 에러 타입 분류
|
|
```python
|
|
class EditErrorType(Enum):
|
|
QUOTA_EXCEEDED = "quota_exceeded" # API 한도 초과
|
|
INVALID_IMAGE = "invalid_image" # 잘못된 이미지
|
|
AUTHENTICATION = "authentication" # 인증 실패
|
|
TIMEOUT = "timeout" # 시간 초과
|
|
NETWORK = "network" # 네트워크 오류
|
|
SERVICE_UNAVAILABLE = "service_unavailable" # 서비스 불가
|
|
INVALID_REQUEST = "invalid_request" # 잘못된 요청
|
|
TOKEN_LIMIT_EXCEEDED = "token_limit_exceeded" # 토큰 초과
|
|
UNKNOWN = "unknown" # 알 수 없는 오류
|
|
```
|
|
|
|
### 자동 복구
|
|
- **타임아웃**: 30초 후 자동 재시도
|
|
- **네트워크 오류**: 3회 재시도 (지수 백오프)
|
|
- **이미지 최적화**: 실패 시 다른 형식 시도
|
|
|
|
## 보안 사양
|
|
|
|
### API 키 관리
|
|
- `.env` 파일에만 저장
|
|
- 로그에 마스킹 처리 (마지막 4자리만 표시)
|
|
- 환경 변수 우선순위 적용
|
|
|
|
### 파일 접근
|
|
- 지정된 디렉토리만 접근 가능
|
|
- 심볼릭 링크 따라가지 않음
|
|
- 파일 권한 검증
|
|
|
|
## 호환성
|
|
|
|
### Python 버전
|
|
- **최소**: Python 3.8
|
|
- **권장**: Python 3.10+
|
|
- **테스트**: Python 3.11, 3.12
|
|
|
|
### 운영체제
|
|
- **Windows**: 10, 11 (테스트 완료)
|
|
- **macOS**: 12+ (Monterey 이상)
|
|
- **Linux**: Ubuntu 20.04+ (테스트 완료)
|
|
|
|
### 의존성
|
|
```
|
|
openai>=1.51.0 # OpenAI API 클라이언트
|
|
mcp>=0.1.0 # Model Context Protocol
|
|
pillow>=10.0.0 # 이미지 처리
|
|
python-dotenv>=1.0.0 # 환경 변수 관리
|
|
aiofiles>=23.0.0 # 비동기 파일 I/O
|
|
```
|
|
|
|
## 확장 가능성
|
|
|
|
### 플러그인 시스템
|
|
향후 플러그인 시스템 추가 예정:
|
|
- 커스텀 이미지 필터
|
|
- 전처리/후처리 파이프라인
|
|
- 외부 서비스 통합
|
|
|
|
### API 버전 관리
|
|
- 현재: `gpt-image-1`
|
|
- 향후: 새 모델 출시 시 자동 감지 및 전환
|
|
|
|
---
|
|
|
|
이 문서는 GPT-Edit의 기술적 세부사항을 담고 있습니다.
|
|
개발 시 참고하시기 바랍니다.
|