GPT Image 2 API Key 스킬

GPT Image 2 API Key

개요

별도로 구성된 gpt-image-2 공급자를 사용하여 scripts/generate_image.py를 실행함으로써 이미지를 생성하거나 편집합니다. 이 스킬은 이미지 생성이 Codex의 현재 OpenAI/Codex 자격 증명 대신 전용 이미지 API 키로 청구, 인증 및 격리되어야 할 때 사용하세요.

이 스킬은 OPENAI_API_KEY, Codex 인증 파일, ChatGPT/Codex 세션 자격 증명을 의도적으로 읽지 않습니다. 오직 --config로 선택된 개인 설정 파일이나 아래 문서화된 기본 설정 파일만 읽습니다.

해결하는 문제

이 스킬은 일반적인 Codex 워크플로 문제를 해결합니다: 현재 Codex 세션이 이미 하나의 API 키로 인증되어 있는 반면, 이미지 생성은 다른 키, 다른 계정, 다른 할당량 또는 OpenAI 호환 프록시를 사용해야 할 수 있습니다.

이 스킬을 사용하여:

• 이미지 생성 자격 증명을 Codex의 자체 자격 증명과 분리할 수 있습니다.
• 프롬프트, 명령어 또는 저장소 파일에 키를 노출하지 않고 Codex에서 gpt-image-2 또는 호환 이미지 엔드포인트를 호출할 수 있습니다.
• /v1/images/generations을 통해 이미지를 생성할 수 있습니다.
• 멀티파트 업로드로 /v1/images/edits을 통해 기존 이미지를 편집할 수 있습니다.
• 편집, 스타일 변경, 로고 처리, 제품 목업 및 이미지 간 변환을 위해 하나 이상의 참조 이미지를 사용할 수 있습니다.
• 영역 제한 편집을 위해 선택적으로 마스크 이미지를 제공할 수 있습니다.
• 생성된 출력을 Codex가 표시, 검사 또는 이후 단계에 전달할 수 있는 명시적인 로컬 경로에 저장할 수 있습니다.

사용 사례

다음과 같은 요청에 이 스킬을 사용하세요:

• "정확히 JunXxxxi 텍스트가 있는 로고를 생성해 줘."
• "이 참조 이미지를 사용해서 워드마크를 이탤릭체로 만들어 줘."
• "이 로고 텍스트를 은색에서 검은색으로 가는 메탈릭 그라데이션으로 바꿔 줘."
• "gpt-image-2를 사용하여 제품 이미지를 생성하는데, 내 별도 이미지 API 키를 사용해 줘."
• "원본 구성을 유지하면서 이 이미지를 편집해 줘."
• "사용자 정의 기본 URL로 OpenAI 호환 이미지 공급자를 사용해 줘."

크롭, 리사이즈, 알파 변환 또는 완전히 결정적인 색상 재매핑과 같이 정확한 형상을 유지해야 하는 간단한 픽셀 수준 변환의 경우 이 스킬 대신 결정적인 로컬 이미지 처리를 선호하세요. 사용자가 모델 기반 시각적 해석, 스타일 변경 또는 생성을 원할 때 이 스킬을 선호하세요.

내용

gpt-image-2-apikey/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── generate_image.py

• SKILL.md: Codex 대상 워크플로 및 사람이 읽을 수 있는 사용법 문서.
• agents/openai.yaml: 선택적 Codex UI 메타데이터.
• scripts/generate_image.py: 생성 또는 편집 엔드포인트를 호출하는 종속성 없는 Python 3 스크립트.

이 스크립트는 b64_json 및 URL 스타일 이미지 응답을 모두 지원합니다. URL 응답은 즉시 다운로드되어 요청된 출력 경로에 기록됩니다.

개인 설정

기본 설정 경로:

~/.config/gpt-image-2-apikey/config.json

설정에는 현재 Codex API 키가 아닌 이미지 공급자 키가 포함되어야 합니다:

{
  "api_key": "put-image-provider-key-here",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-image-2"
}

파일을 만든 후 개인 권한을 설정하세요:

chmod 600 ~/.config/gpt-image-2-apikey/config.json

사용자가 명시적으로 다른 개인 설정 파일을 원하는 경우에만 --config /path/to/config.json을 사용하세요.

설정 필드

• api_key: 필수. 이미지 공급자 키. 명시적으로 의도된 경우가 아니라면 Codex의 현재 API 키를 사용하지 마세요.
• base_url: 선택 사항. 기본값은 https://api.openai.com/v1입니다. OpenAI 호환 공급자의 경우 이를 API 루트(예: https://example.com/v1)로 유지하세요.
• model: 선택 사항. 기본값은 gpt-image-2입니다.
• extra_body: 선택적 객체. 값이 공급자별 필드를 위해 요청 본문에 병합됩니다.

좋은 base_url 예시:

{
  "base_url": "https://api.openai.com/v1"
}

{
  "base_url": "https://www.packyapi.com/v1"
}

의도적으로 하나의 정확한 엔드포인트를 고정하지 않는 한 base_url에 /images/generations 또는 /images/edits를 포함하지 마세요. 스크립트는 일반적으로 올바른 엔드포인트를 자동으로 추가합니다.

사용법

스킬 디렉토리에서 실행:

python3 scripts/generate_image.py \
  --prompt "호두나무 책상 위에 있는 무광 블랙 기계식 키보드의 깔끔한 제품 사진" \
  --out /absolute/path/to/output.png \
  --size 1024x1024 \
  --quality high

--edit-image이 생략되면 스크립트는 다음을 호출합니다:

POST <base_url>/images/generations

--edit-image을 추가하여 하나 이상의 참조 이미지를 편집:

python3 scripts/generate_image.py \
  --prompt "이 로고를 정확한 철자를 유지하면서 이탤릭체 은색-검정 그라데이션 텍스트로 바꿔 줘" \
  --edit-image /absolute/path/to/input.png \
  --out /absolute/path/to/edited.png \
  --size 1024x1024 \
  --quality high

--edit-image이 있으면 스크립트는 다음을 호출합니다:

POST <base_url>/images/edits

마스크된 편집의 경우 --mask /absolute/path/to/mask.png를 추가:

python3 scripts/generate_image.py \
  --prompt "피사체는 유지하면서 배경만 깔끔한 스튜디오 그레이로 변경" \
  --edit-image /absolute/path/to/source.png \
  --mask /absolute/path/to/mask.png \
  --out /absolute/path/to/edited.png \
  --quality high

다중 이미지 편집을 위해 --edit-image 반복:

python3 scripts/generate_image.py \
  --prompt "이미지 1의 제품과 이미지 2의 배경 분위기를 결합" \
  --edit-image /absolute/path/to/product.png \
  --edit-image /absolute/path/to/background-reference.png \
  --out /absolute/path/to/combined.png

사용자가 특정 위치에 파일이 필요할 때는 항상 절대 --out 경로를 제공하세요. 생략하면 스크립트는 현재 작업 디렉토리에 타임스탬프가 포함된 PNG를 기록합니다.

명령어 참조

--prompt       필수 이미지 프롬프트 또는 편집 지시.
--out          출력 이미지 경로. 추가 출력은 확장자 앞에 -2, -3 등을 사용합니다.
--config       개인 설정 경로. 기본값: ~/.config/gpt-image-2-apikey/config.json.
--model        설정에서 모델 덮어쓰기.
--size         공급자 지원 이미지 크기. 기본값: 1024x1024.
--quality      low, medium, high, auto. 기본값: auto.
--n            이미지 개수. 기본값: 1.
--format       png, jpeg, webp. 기본값: png.
--edit-image   /v1/images/edits용 입력 이미지 경로. 반복 가능.
--mask         편집용 선택적 PNG 마스크 경로.
--timeout      HTTP 제한 시간(초). 기본값: 600.
--dry-run      API를 호출하지 않고 수정된 엔드포인트, 본문 및 파일 목록을 출력합니다.

실제 호출 전에 설정, 엔드포인트 라우팅 또는 편집이 의도한 입력 파일을 사용할지 확인하려면 --dry-run을 사용하세요:

python3 scripts/generate_image.py \
  --prompt "dry run only" \
  --edit-image /absolute/path/to/input.png \
  --out /absolute/path/to/output.png \
  --dry-run

드라이 런 출력은 인증을 Bearer ***redacted***로 수정합니다.

프롬프트 가이드

생성의 경우:

• 에셋 유형, 주제, 스타일, 레이아웃 및 필요한 텍스트를 명시적으로 지정하세요.
• 정확한 표시 텍스트를 따옴표 안에 넣으세요.
• 로고, 포스터 또는 UI 그래픽 작업 시 "추가 텍스트 없음, 워터마크 없음"을 포함하세요.
• 최종 로고, 타이포그래피가 많은 이미지, 제품 샷 및 세련된 결과물에는 quality high를 사용하세요.
• 저렴한 탐색 및 빠른 초안에는 quality low를 사용하세요.

편집의 경우:

• 전체 이미지를 다시 해석해야 하는 경우가 아니라면 전체 이미지가 아닌 변경 사항을 설명하세요.
• 보존해야 할 항목(텍스트 철자, 레이아웃, 구성, 얼굴 정체성, 제품 형태, 색상 또는 배경)을 명시적으로 지정하세요.
• 텍스트가 많은 그래픽의 경우 프롬프트에 정확한 철자와 대소문자를 반복하세요.
• 공급자가 지원하는 경우 수술적 편집에 마스크를 사용하세요.

편집 프롬프트 예시:

제공된 로고 이미지를 편집하세요. 정확한 텍스트 "JunXxxxi"와 동일한 워드마크 레이아웃을 유지하세요. 글자를 오른쪽으로 기울인 이탤릭체/경사체로 만드세요. 글자 채우기를 왼쪽/위쪽의 밝은 은색에서 오른쪽/아래쪽의 진한 검정색으로 가는 메탈릭 그라데이션으로 변경하세요. 깨끗한 흰색 배경을 유지하세요. 추가 단어, 아이콘, 워터마크, 테두리 또는 장식 요소를 추가하지 마세요.

격리 규칙

• Codex의 현재 API 키를 이 스킬에 전달하거나 복사하지 마세요.
• OPENAI_API_KEY를 읽지 마세요. 스크립트는 의도적으로 이를 무시합니다.
• api_key 또는 설정 내용을 출력하지 마세요. 스크립트는 --dry-run에서 수정된 설정 요약만 보고합니다.
• 설정이 누락된 경우 사용자에게 개인 설정 파일을 만들라고 알리세요. 명시적으로 요청하지 않는 한 실제 비밀로 설정 파일을 대신 만들지 마세요.
• 공급자가 OpenAI 호환 엔드포인트를 사용하는 경우 개인 설정에 base_url을 설정하세요. 스크립트는 생성 시 /images/generations를, 편집 시 /images/edits를 자동으로 추가합니다.

설정 참고 사항

• config.json을 Git에 보관하지 마세요. 실제 API 키를 절대 커밋하지 마세요.
• 개인 설정에 파일 모드 600을 사용하세요.
• 공급자가 달리 문서화하지 않는 한 base_url을 API 루트(.../v1)로 유지하세요.
• 공급자에게 사용자 정의 요청 필드가 필요한 경우 extra_body 아래에 배치하세요.
• 공급자가 gpt-image-2를 지원하지 않는 경우 model을 공급자의 호환 모델 이름으로 설정하세요.
• 공급자가 URL 응답만 지원하는 경우 스크립트는 반환된 URL을 다운로드합니다.
• 공급자가 b64_json으로 base64 이미지를 반환하는 경우 스크립트는 이를 직접 디코딩합니다.
• 네트워크 호출은 구성된 공급자 계정에 요금이 부과될 수 있습니다.

공급자별 필드 예시:

{
  "api_key": "put-image-provider-key-here",
  "base_url": "https://example.com/v1",
  "model": "gpt-image-2",
  "extra_body": {
    "moderation": "auto"
  }
}

오류 처리

• 설정 또는 api_key 누락: 설정 경로와 필수 필드를 보고합니다.
• HTTP 오류: 상태 코드와 공급자의 오류 본문을 표시하지만 키는 절대 포함하지 않습니다.
• 지원되지 않는 공급자 응답: 최상위 응답 키를 보고하고 파일을 저장하지 않습니다.
• 여러 이미지: 첫 번째 이미지는 --out을 사용하고 추가 이미지는 확장자 앞에 -2, -3 등을 얻습니다.

제한 사항

• 이 스킬은 API 래퍼이지 완전한 그래픽 편집기가 아닙니다. 정확한 크롭, 리사이즈, 벡터 내보내기 또는 보장된 픽셀 완벽한 타이포그래피 변경에는 결정적인 로컬 도구를 사용하세요.
• 모델 기반 이미지 편집은 정확한 텍스트, 커닝 또는 형상을 변경할 수 있습니다. 로고 및 워드마크의 경우 결과물을 전달하기 전에 검사하세요.
• 멀티파트 편집 호환성은 OpenAI 호환 공급자마다 다를 수 있습니다. 편집이 실패하고 생성이 작동하는 경우 공급자가 멀티파트 image 업로드로 /v1/images/edits를 지원하는지 확인하세요.
• 스크립트는 현재 다중 이미지 호환성을 위해 멀티파트 필드 이름 image[]로 편집 이미지를 전송합니다. 공급자가 다른 필드 이름을 필요로 하는 경우 해당 공급자에 맞게 scripts/generate_image.py를 조정하세요.
• 실제 투명 배경 동작은 공급자/모델 지원에 따라 다릅니다. 투명 PNG가 필요한 경우 생성 후 알파 채널을 확인하세요.

게시 참고 사항

이 스킬을 GitHub에 게시할 때:

• SKILL.md, agents/openai.yaml, scripts/generate_image.py를 포함하세요.
• ~/.config/gpt-image-2-apikey/config.json을 포함하지 마세요.
• 의도적인 예제가 아닌 한 생성된 이미지를 포함하지 마세요.
• 이 스킬이 더 큰 저장소에 있는 경우 로컬 설정, 출력 및 임시 이미지에 대한 .gitignore 항목을 추가하세요.