GPT Image Skill로 이미지 생성 및 편집

GPT Image Skill의 기능

GPT Image Skill을 사용하면 Codex, Claude Code 및 호환되는 로컬 에이전트가 사용자의 ChatGPT 구독을 통해 이미지를 생성하거나 편집할 수 있습니다. Codex에 내장된 $imagegen을 사용하거나, 사용 가능한 경우 호스트 네이티브 image_gen 도구를 사용합니다. OpenAI Images API를 호출하거나 별도로 요금이 청구되는 Images API 요청을 생성하지 않습니다.

이 스킬은 자연어 프롬프트와 읽을 수 있는 로컬 PNG, JPEG 또는 WebP 참조 파일을 지원합니다. 생성된 PNG 파일은 활성 프로젝트의 generated-images/ 디렉터리에 저장되며, 결과 경로와 인라인 Markdown 미리보기 정보를 반환합니다.

이미지 생성에는 포함된 ChatGPT 또는 Codex 사용량이 소비되며, 요금제 및 워크스페이스 제한이 적용됩니다. 이미지 생성은 일반 이미지가 아닌 요청에 비해 포함된 사용량 한도를 더 빠르게 소진할 수 있으므로, 병렬 배치는 의도적으로 소규모로 운영하세요.

주요 기능

• API 키가 아닌 ChatGPT 인증 Codex를 통해 이미지를 생성합니다.
• Codex와 Claude Code에 동일한 gpt-image 스킬을 설치합니다.
• 요청하지 않은 창의적 세부 사항을 추가하지 않고 직접적인 이미지 프롬프트를 유지합니다.
• 사용자가 여러 콘셉트나 디자인 방향을 명시적으로 위임하면 각각 구분되는 프롬프트를 작성합니다.
• 결정적인 첨부 순서로 하나 이상의 참조 파일을 지원합니다.
• 편집, 후속 수정, 변형, 합성, 투명도, 정확한 텍스트 및 복잡한 레이아웃 초안을 지원합니다.
• 독립적인 이미지 작업을 기본 동시성 2, 최대 4로 실행합니다.
• 파일을 활성 워크스페이스 내부에만 저장하며, 기본적으로 기존 이미지를 덮어쓰지 않습니다.
• macOS, Linux, 네이티브 Windows 및 WSL2를 지원합니다.
• API 키 로그인을 차단하고 Codex 자식 프로세스에서 관련 API 환경 변수를 제거합니다.

요구 사항

스킬을 설치하기 전에 환경에 다음 구성 요소가 있는지 확인하세요.

• Node.js 22 이상: 현재 지원되는 LTS 릴리스를 권장합니다.
• Git: GitHub에서 프로젝트를 복제할 때 필요합니다.
• Codex CLI: 호출 호스트가 네이티브 image_gen 도구를 제공하지 않는 한 ChatGPT에 로그인되어 있어야 합니다.
• 사용 가능한 요금제: ChatGPT 또는 Codex 요금제와 워크스페이스에서 이미지 생성을 허용해야 합니다.

WSL1은 지원되지 않습니다. WSL2를 사용하는 경우 Node.js, Codex, 저장소 및 작업 프로젝트를 Linux 측에 두세요. 복제본은 /mnt/c가 아닌 Linux 홈 디렉터리에 저장하세요.

로컬 에이전트를 통한 설치

가장 간단한 설정 방법은 Codex, Claude Code 또는 다른 호환 에이전트에 저장소 설치를 요청하는 것입니다. 에이전트가 AGENT_INSTALL.md를 읽고, 지속적인 복제 또는 안전한 fast-forward 업데이트를 수행하며, Codex 및 Claude Code 링크를 생성하고, ChatGPT 장치 인증을 시작한 다음 다음 명령을 실행하도록 안내하세요.

bootstrap --target all --yes --json

준비 상태 보고서는 ok: true, status: ready 및 best_practice_pass: true로 끝나야 합니다. 브라우저 또는 장치 인증은 사용자가 직접 완료합니다. 이 스킬은 비밀번호, 토큰, API 키 또는 ~/.codex/auth.json의 내용을 요청하지 않습니다.

설치 과정에서 실제 이미지를 생성해서는 안 됩니다. 설치가 끝나면 일반적인 화면 비율, 품질 표현, 이미지 생성 및 참조 요청 예시가 포함된 간단한 시작 안내가 제공되어야 합니다.

수동 설치

macOS, Linux 및 WSL2

설치된 스킬 링크가 저장소를 가리키므로 지속적인 복제본을 사용하세요.

REPOSITORY_URL="https://github.com/GENEXIS-AI/gpt-image-skill"
INSTALL_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/gpt-image-skill"

git clone "$REPOSITORY_URL" "$INSTALL_DIR"
cd "$INSTALL_DIR"
node ./gpt-image/scripts/validate_skill.mjs
node ./gpt-image/scripts/gpt_image.mjs bootstrap --target all --yes --json

네이티브 Windows PowerShell

$RepositoryUrl = "https://github.com/GENEXIS-AI/gpt-image-skill"
$InstallDir = Join-Path $env:LOCALAPPDATA "gpt-image-skill"

git clone $RepositoryUrl $InstallDir
Set-Location $InstallDir
node .\gpt-image\scripts\validate_skill.mjs
node .\gpt-image\scripts\gpt_image.mjs bootstrap --target all --yes --json

macOS, Linux 및 WSL2에서는 설치 시 심볼릭 링크가 생성됩니다. 네이티브 Windows에서는 디렉터리 정션을 사용합니다. 기존의 관련 없는 경로는 대체하지 않습니다.

• Codex 설치 경로: ~/.agents/skills/gpt-image
• Claude Code 설치 경로: ~/.claude/skills/gpt-image
• Windows Codex 설치 경로: $env:USERPROFILE\.agents\skills\gpt-image
• Windows Claude Code 설치 경로: $env:USERPROFILE\.claude\skills\gpt-image

첫 이미지 생성하기

설치가 완료되면 호스트에서 스킬을 직접 호출하세요. Codex에서는 다음을 사용합니다.

$gpt-image 따뜻한 오프화이트 배경 위에 있는 코발트 블루 유리 로봇.

Claude Code에서는 다음을 사용합니다.

/gpt-image 따뜻한 오프화이트 배경 위에 있는 코발트 블루 유리 로봇.

구도와 품질도 자연어로 표현할 수 있습니다.

$gpt-image 석양이 비치는 아늑한 독서실을 만들어 줘. 16:9, 고품질.

일반적인 요청에는 1:1, 16:9, 9:16, 4:3 및 3:4가 포함됩니다. 유용한 품질 표현으로는 draft, high quality 및 high detail / final quality가 있습니다. 이는 고정된 API 크기 목록이 아닌 자연어 요청이므로 정확한 픽셀 크기는 달라질 수 있습니다.

직접 실행기 사용

저장소에서 Node.js 실행기를 명시적으로 호출할 수 있습니다.

node ./gpt-image/scripts/gpt_image.mjs generate \
  --prompt "A cobalt-blue glass robot on a warm off-white background." \
  --out "generated-images/glass-robot.png"
일반 생성은 빠른 ChatGPT 인증 확인을 수행하고, 이미지 하나를 생성한 뒤, 최소한의 PNG 정상 여부를 확인하고, PATH=...와 절대 경로가 포함된 MARKDOWN=... 값을 반환합니다.
참조 이미지로 이미지 생성
참조 이미지는 실제로 읽을 수 있는 파일이어야 합니다. Claude Code에서는 @path 또는 명시적인 파일 시스템 경로를 사용하세요.
/gpt-image Use @references/robot.png as the character reference. Draw it riding a bicycle.
Claude에 붙여넣거나 드래그해 표시한 이미지는 중첩된 Codex 프로세스에 자동으로 전달되지 않습니다. Claude가 정확한 임시 첨부 파일 경로를 제공하는 경우 에이전트가 해당 파일을 generated-images/inputs/로 복사할 수 있습니다. 그렇지 않으면 프로젝트 내부에 이미지를 저장하고 그 경로를 제공하세요. 이 스킬은 Claude의 이미지 캐시에서 사용할 파일을 추측하지 않습니다.
동일한 작업을 직접 실행하는 명령은 다음과 같습니다.
node ./gpt-image/scripts/gpt_image.mjs generate \
  --mode generate \
  --prompt "Draw this character riding a bicycle." \
  --reference "/absolute/path/robot.png" \
  --out "generated-images/robot-bicycle.png"
여러 참조 이미지 첨부
필요한 순서대로 --reference를 반복하세요. 참조 이미지에 명시적인 역할이 있는 경우에만 해당 역할을 추가하세요.
node ./gpt-image/scripts/gpt_image.mjs generate \
  --prompt "Use Image 1 for the character and Image 2 for the bicycle design." \
  --reference "/absolute/path/character.png" \
  --reference-role "character" \
  --reference "/absolute/path/bicycle.png" \
  --reference-role "bicycle design" \
  --out "generated-images/combined.png"
편집할 때는 Image 1이 편집 대상입니다. 보조 참조 이미지는 명령줄 순서에 따라 그 뒤에 배치합니다.
이미지 편집 및 수정
기존 이미지를 수정하려면 --edit-target과 함께 --mode edit을 사용하세요.
node ./gpt-image/scripts/gpt_image.mjs generate \
  --mode edit \
  --prompt "Replace the bicycle basket with a small wooden crate." \
  --edit-target "generated-images/robot-bicycle.png" \
  --out "generated-images/robot-bicycle-crate.png"
후속 수정에서는 원본으로 돌아가지 말고 항상 최신 결과물을 편집하세요.
node ./gpt-image/scripts/gpt_image.mjs generate \
  --mode edit \
  --prompt "Make the wooden crate dark green." \
  --edit-target "generated-images/robot-bicycle-crate.png" \
  --out "generated-images/robot-bicycle-green-crate.png"
계속 필요한 모든 보조 참조 이미지를 다시 첨부하세요. 각 브리지 호출은 일시적이므로 이전에 첨부한 파일을 자동으로 유지하지 않습니다. 최신 결과물 대신 원본을 편집하면 이전 수정 사항이 사라집니다.
여러 이미지를 병렬로 실행
이미지 하나를 생성할 때는 generate를 사용하세요. 준비된 작업이 두 개 이상이면 이 스킬은 제한된 배치 처리를 사용할 수 있습니다. 기본 동시 실행 수는 2이며 최대 4개입니다. 배치에 대한 인증은 한 번만 확인하고, 실패한 작업은 자동으로 재시도하지 않습니다.
배치 모델은 다음 세 가지 일반적인 구조를 지원합니다.

공유 기준점 변형: 모든 작업이 동일한 기존 디자인을 읽고 서로 다른 스타일을 적용합니다.
위임된 콘셉트: 공통 제약 조건을 유지하면서 에이전트가 요청된 각 디자인 방향에 대해 완전하고 의미 있게 다른 프롬프트를 하나씩 만듭니다.
반복 렌더링: 차이가 요청되지 않은 경우 각 작업이 정확히 동일한 프롬프트를 재사용합니다.

다음과 같이 작업 공간 내부에 매니페스트를 만드세요(image-jobs.json 등).
{
  "version": 1,
  "jobs": [
    {
      "id": "watercolor",
      "mode": "variation",
      "prompt": "Keep the same design and render it in watercolor style.",
      "edit_target": "references/base-design.png",
      "references": ["references/watercolor-style.png"],
      "reference_roles": ["style reference for this output"],
      "out": "generated-images/design-watercolor.png"
    },
    {
      "id": "clay",
      "mode": "variation",
      "prompt": "Keep the same design and render it in clay style.",
      "edit_target": "references/base-design.png",
      "references": ["references/clay-style.png"],
      "reference_roles": ["style reference for this output"],
      "out": "generated-images/design-clay.png"
    }
  ]
}
다음 명령으로 매니페스트를 실행하세요.
node ./gpt-image/scripts/gpt_image.mjs batch \
  --manifest "image-jobs.json" \
  --concurrency 2
여러 작업이 동일한 기준점을 읽어도 안전합니다. 각 결과물에는 관련된 스타일 참조 이미지만 첨부하세요. 서로 관련 없는 콘셉트라면 공통 edit_target을 생략하고, 각 작업에 독립적인 프롬프트와 고유한 참조 이미지를 제공하세요.
한 배치 작업에서 생성된 결과물은 동일한 배치에서 다른 작업의 입력이 될 수 없습니다. 출력물을 입력으로 사용하는 워크플로는 여러 단계로 나누어 실행하세요. 공통 기준점이 없다면 먼저 요청된 첫 번째 결과물을 생성하고, 이후 변형 작업에는 반환된 경로를 사용하세요. 이 스킬은 숨겨진 기준점을 추가로 만들지 않습니다.
고급 사용 팁
프롬프트 의도 유지
단일 직접 요청에서는 사용자의 표현이 기준이 되며 변경 없이 전달됩니다. 사용자가 서로 다른 디자인, 콘셉트, 방향, 옵션 또는 대안을 여러 개 요청한 경우에는 위임된 창작 의도 역시 기준이 됩니다. 이때 에이전트는 공통 주제, 브랜드, 텍스트, 참조 이미지, 화면 비율 및 기타 제약 조건을 유지하면서 각 결과물에 대해 이미지 생성에 적합한 서로 다른 프롬프트를 작성합니다.
작업 번호는 이미지 프롬프트가 아니라 매니페스트 ID와 파일 이름에 포함해야 합니다. this is the second option과 같은 문구는 추가하지 마세요.
올바른 모드 선택

텍스트를 이미지로 변환하려면 --mode generate를 사용하세요.
기존 파일을 참고해 새 이미지를 만들려면 --reference PATH를 추가하세요.
기존 이미지를 변경하려면 --mode edit --edit-target PATH를 사용하세요.
기존 디자인의 변형을 만들려면 --mode variation --edit-target PATH를 사용하세요.
투명도가 요청된 경우에만 --background transparent를 사용하세요.
하나의 구성을 서로 다른 스타일로 렌더링하는 여러 변형 작업에는 동일한 편집 대상을 사용하세요.
동일한 이미지가 서로 다른 장면이나 레이아웃에 나타나야 하는 여러 생성 작업에는 같은 이미지를 참조 이미지로 사용하세요.

실수로 덮어쓰기 방지
--overwrite를 명시하지 않으면 실행기는 기존 이미지를 덮어쓰지 않습니다. 각 결과에 generated-images/ 아래의 설명적인 출력 경로를 지정하세요.
문제 해결 및 설정 확인
계획 수립과 상세 진단은 선택 사항입니다. 일반적인 생성 전에 반드시 실행할 필요는 없습니다. 설정, 인증, 참조 이미지 또는 출력 파일을 확인해야 할 때 사용하세요:
node ./gpt-image/scripts/gpt_image.mjs doctor --json
node ./gpt-image/scripts/gpt_image.mjs guide
node ./gpt-image/scripts/gpt_image.mjs capabilities --json
node ./gpt-image/scripts/gpt_image.mjs inspect \
  --input "generated-images/combined.png" --json
이미지를 생성하지 않고 로그인 상태와 경로를 확인하려면 다음을 실행하세요:
node ./gpt-image/scripts/gpt_image.mjs generate \
  --prompt "test" \
  --out "generated-images/test.png" \
  --dry-run --json
로그인하거나 이미지를 생성하지 않고 배치 매니페스트와 예약 상태를 검증하려면 다음을 실행하세요:
node ./gpt-image/scripts/gpt_image.mjs batch \
  --manifest "image-jobs.json" \
  --check-only --json
생성된 이미지는 SHA-256 영수증 대신 간단한 파일 및 서명 검사를 받습니다. SHA-256은 설치 프로그램 검증처럼 의미가 있는 경우 계속 사용할 수 있습니다:
node ./gpt-image/scripts/gpt_image.mjs verify-installers --json
보안 및 개인정보 보호 조치

이 스킬은 Codex 하위 프로세스에서 OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_ORG_ID, OPENAI_PROJECT_ID, CODEX_ACCESS_TOKEN을 제거합니다.
삭제된 정보로 제공되는 진단 결과에서 ChatGPT 인증이 확인되지 않으면 생성을 차단합니다.
OpenAI Images API 엔드포인트나 /v1/images 요청은 포함하지 않습니다.
이 스킬은 인증 파일을 읽지 않습니다.
생성된 파일은 활성 작업 공간 내부에 유지됩니다.
구독 한도에 도달해도 실행기는 Images API로 대체 실행하지 않습니다.

스킬 업데이트
macOS, Linux 또는 WSL2에서는 영구 클론을 fast-forward한 후 부트스트랩을 다시 실행하세요:
INSTALL_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/gpt-image-skill"
git -C "$INSTALL_DIR" pull --ff-only
node "$INSTALL_DIR/gpt-image/scripts/gpt_image.mjs" \
  bootstrap --target all --yes --json
Windows 네이티브 PowerShell에서는 다음을 실행하세요:
$InstallDir = Join-Path $env:LOCALAPPDATA "gpt-image-skill"
git -C $InstallDir pull --ff-only
node "$InstallDir\gpt-image\scripts\gpt_image.mjs" bootstrap --target all --yes --json
결론
GPT Image Skill은 ChatGPT 인증을 사용해 Codex, Claude Code 또는 호환 가능한 다른 에이전트에서 이미지를 생성하고 편집할 수 있는 작업 공간 중심의 방법을 제공합니다. 먼저 직접적인 자연어 요청으로 시작하고, 참조 이미지에는 안정적인 로컬 경로를 제공하며, 각 수정에는 최신 출력을 사용하세요. 독립적인 콘셉트나 공통 기준점을 사용하는 변형에는 제한된 배치를 활용하세요.
설치 계약과 자세한 워크플로 정보는 GPT Image Skill 저장소를 방문하세요.