ened/gpt-edit

Fork 0

Files

ened fdfb72c9db rename gptedit to gpt-edit

2025-08-26 01:31:42 +09:00

6.1 KiB

Raw Permalink Blame History

GPT-Edit Technical Specifications

OpenAI API 설정

고정 파라미터 (변경 불가)

OpenAI API 요구사항에 따라 다음 파라미터들은 고정값입니다:

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 이상 이미지는 자동으로 최적화됩니다:

WebP 압축 시도 (최고 품질 유지)
PNG 최적화 (WebP 실패 시)
단계적 품질 감소 (95% → 85% → 75%)
최종 수단: 해상도 축소

마스크 이미지

형식: 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 파라미터 구조

{
  "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 추가

에러 처리

에러 타입 분류

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의 기술적 세부사항을 담고 있습니다. 개발 시 참고하시기 바랍니다.

6.1 KiB Raw Permalink Blame History