imagegen은(는) 무엇을 하나요?
하나의 명령으로 /images/generations 또는 /images/edits를 호출하고 결과를 현재 프로젝트에 저장합니다.
설정 (사용자가 한 번)
- OpenAI Images API 또는 OpenAI 호환 이미지 API용 API 키가 필요합니다.
- 환경 변수 (Windows에서는
setx로 설정한 값이 레지스트리에서 읽히므로 에이전트 재시작이 필요 없음):IMAGEGEN_API_KEY: API 키.OPENAI_API_KEY로 대체됩니다.IMAGEGEN_BASE_URL: 선택 사항, 기본값https://api.openai.com/v1.IMAGEGEN_MODEL: 선택 사항, 기본값gpt-image-2.
- Python 3.8+, 표준 라이브러리만 사용. 이 폴더를
~/.claude/skills/imagegen/(Claude Code) 및/또는~/.codex/skills/imagegen/(Codex)에 설치하세요. - 선택 사항: PATH에
imagegen래퍼를 넣습니다 (예제는 리포지토리의wrappers/디렉토리에 있음). 래퍼가 없으면 아래의imagegen을python <이 스킬 폴더>/scripts/imagegen.py로 대체하세요.
생성
imagegen "<프롬프트>" [--size 1536x1024] [--quality high] [--n 2] [--out 경로.png]
출력 옵션 (지정된 경우에만 전송되며, 모든 API나 모델이 지원하는 것은 아님): --background transparent|opaque|auto, --format png|jpeg|webp, --compression 0-100 (jpeg/webp만 해당).
편집 (하나 이상의 입력 이미지 전달)
imagegen "<변경할 내용>" --image input.png [--image ref.png] [--mask mask.png]
출력
표준 출력에 JSON 한 줄:
{"ok": true, "mode": "generate", "paths": ["/path/to/project/output/imagegen/20260101-120000-orange-cat.png"], "seconds": 42.9, "model": "gpt-image-2", "revised_prompt": null, "sidecars": ["/path/to/project/output/imagegen/20260101-120000-orange-cat.json"]}
각 이미지마다 <동일 이름>.json 사이드카 파일이 생성되며, 프롬프트, 수정된 프롬프트, 모델, 크기, 품질, 기타 옵션, 입력 이미지 및 마스크 경로, 소요 시간, 생성 시간이 포함됩니다 (--no-sidecar로 비활성화 가능). 마지막 이미지는 이전 출력의 마지막 경로입니다. 해당 정보가 없으면 (새 세션) output/imagegen/에서 가장 최신 이미지를 가져와 해당 .json 파일에서 프롬프트를 읽습니다.
실패 시: {"ok": false, "error": "..."} 및 종료 코드 1. paths를 읽고 사용자에게 보고하세요. 오류에 API 키가 없다고 표시되면 사용자에게 IMAGEGEN_API_KEY 설정 방법을 알려주세요. 키를 직접 찾지 마세요.
작업 방법
- 기본: 사용자의 요청에 따라 한 번 생성하고 경로를 보고합니다. 이미지를 열거나 평가하지 말고, 사용자가 요청하지 않는 한 다시 생성하지 마세요.
- 사용자가 말한 내용만 사용하세요. 스타일이나 세부 사항을 임의로 추가하지 마세요. 이미지를 사용할 수 없게 만드는 필수 요소 (이미지 내 정확한 텍스트, 가로/세로 방향)가 누락된 경우 생성 전에 한 번 물어보세요.
- 사용자가 결과를 변경하라고 요청하면 ("왼쪽 이미지를 파란색으로") 처음부터 다시 생성하지 말고
--image <마지막 경로>로 마지막 이미지를 편집하세요. - 여러 개의 독립적인 이미지를 병렬로 요청할 수 있습니다 (동시에 별도의 명령 실행).
- 사용자가 반복을 요청하고 ("좋을 때까지 반복") 이미지를 볼 수 있는 경우에만: 확인 가능한 요구 사항의 짧은 체크리스트를 작성하고, 생성한 후 이미지를 열어 각 항목을 확인하세요. 로컬 문제는
--image편집으로 수정하고 전체 방향이 잘못된 경우에만 다시 생성하세요. 모든 항목이 통과하거나 3회 후에 중단하고 각 버전의 경로와 여전히 실패하는 항목을 보고하세요.
참고 사항
--out이 없으면 파일은 현재 디렉토리 아래output/imagegen/<시간>-<단어>.png에 저장됩니다 (확장자는--format을 따름).- 크기:
1024x1024(정사각형),1536x1024(가로),1024x1536(세로). gpt-image-2는2048x1152(16:9)와 같은 사용자 지정 크기도 허용합니다: 양쪽 모두 16의 배수, 최대 길이 3840 이하, 종횡비 1:3 ~ 3:1 사이.--size를 생략하면 자동으로 설정됩니다. --quality low는 초안에 가장 빠르며,high는 최종 에셋에 적합합니다.xhigh/max는 이를 지원하는 모델에서만 작동합니다.- 하나의 이미지 생성에는 약 30~90초가 소요됩니다. 포그라운드에서 최소 600000ms의 타임아웃으로 실행하고, 폴링하지 마세요.
- 프롬프트 작성: 에셋 유형, 주제, 스타일, 구도, 조명, 이미지 내 정확한 텍스트 (따옴표 사용). 비영어 프롬프트도 작동합니다.
- 이미지에 반드시 표시되어야 하는 텍스트는 따옴표 안에 단어 그대로 넣고, 위치를 지정하세요: 상단 헤드라인 "Summer Sale". 특이한 단어는 철자를 하나씩 알려주세요.
- 여러 개의 입력 이미지가 있는 경우, 각 이미지의 용도를 순서대로 설명하세요: "이미지 1: 편집할 제품 사진. 이미지 2: 스타일 참조용."
- 편집 시 정확히 무엇이 변경되는지와 다른 모든 것이 동일하게 유지된다고 명시하세요: "재킷만 빨간색으로 변경하고 얼굴, 포즈, 배경, 조명은 변경하지 않습니다." 이후 편집에서도 변경되지 않은 부분을 반복하세요.
--background transparent는 png 또는 webp 출력과 이를 지원하는 모델이 필요합니다.--dry-run은 API를 호출하지 않고 요청을 출력합니다.- API 키를 절대 출력하거나 기록하지 마세요.