shijianjizhe/remotion

codex-image

사용자의 ChatGPT 구독을 통해 GPT Image로 이미지를 생성하고 편집합니다. 결과물은 ./generated_images/ (또는 --out-dir / --out) 디렉토리에 저장됩니다.

실행 방법

모든 작업은 하나의 스크립트를 통해 이루어집니다. 이 SKILL.md가 포함된 절대 디렉토리를 확인하세요 (스킬이 로드될 때 harness가 이를 알려줍니다 — 아래에서는 <skill-dir>로 표기합니다). 그런 다음:

bash "<skill-dir>/scripts/generate.sh" "<prompt>" [flags]

절대 상대 경로 scripts/generate.sh를 직접 호출하지 마세요: 작업 디렉토리는 사용자의 프로젝트이지 스킬의 설치 위치가 아닙니다 (설치 위치는 에이전트에 따라 다름 — ~/.claude/skills/, ~/.agents/skills/, ~/.opencode/skills/, 프로젝트 로컬 .claude/skills/, ...).

스크립트가 자동으로 확인하는 요구 사항:

• PATH에 python3 ≥ 3.10 (bash + stdlib Python 이외의 것은 필요 없음).
• Pillow — --format webp 및 --transparent-mode chroma에만 필요합니다. 기본적으로 설치되어 있지 않습니다. 해당 실행은 설치 명령어(python3 -m pip install 'Pillow>=10')와 함께 빠르게 실패합니다. 일반 --transparent는 Pillow가 필요하지 않습니다. 이 전제 조건을 처음 사용하기 전에 언급하세요.
• Codex CLI가 로그인되어 있어야 합니다. 로그인되어 있지 않으면 스크립트는 Run: codex login과 함께 종료됩니다. 해당 메시지를 사용자에게 전달하고 인증 관련 작업을 직접 처리하지 마세요.

bash "<skill-dir>/scripts/generate.sh" --help를 실행하면 전체 플래그 목록을 확인할 수 있습니다. 플래그를 임의로 사용하기 전에 반드시 참조하세요. 호스트 에이전트가 타입드 슬래시 명령어를 지원하는 경우, /codex-image "<prompt>" --flags는 이 스크립트 호출의 사용자 대상 단축키입니다.

스크립트는 기계적입니다 — 의미적 라우팅을 수행하지 않습니다. 연속 처리, 배치 결정, 배경 제거 디스패치는 사용자의 몫이며, 대화 내용에 기반해야 합니다.

GPT Image 2.5

OpenAI는 정밀 편집을 위한 gpt-image-2.5-sunburst와 빠른 일상 생성을 위한 gpt-image-2.5-flare를 제공합니다. 특정 모델을 요청하려면 --image-model <model-id>를 전달하고, 생략하면 Codex Responses의 기본 선택을 따릅니다. 이 플래그는 구독 전송에서 실험적입니다: 2026-09-08 라이브 체크에서 각 변형을 요청했지만 두 응답 모두 gpt-image-2-codex를 보고했습니다. 성공적인 요청만으로 2.5 업그레이드를 주장하지 마세요. 레거시 응답 별칭 또는 C2PA 버전 2.0도 이전 가중치를 입증하지 않습니다: OpenAI의 2.5 발표에서 게시된 이미지도 동일한 출처 버전을 가지고 있습니다. 스크립트는 보고된 모델이 다르거나 누락된 경우 경고합니다. 사이드카의 image_model을 requested_image_model과 별도로 확인하세요. --orchestrator는 이미지 도구를 호출하는 메인라인 모델을 선택하며, Sunburst 또는 Flare가 아닙니다. 생략하세요: 스크립트는 계정에 나열된 최신 Sol-계층 모델(gpt-<version>-sol)을 사용하므로 사용 중단된 모델로 인해 깨지지 않습니다. 요청은 Codex의 자체 구성이 Codex를 보내는 곳으로 전송됩니다: 프록시와 같은 사용자 정의 model_provider, openai_base_url 릴레이, 또는 chatgpt.com.

모델 선택, xhigh/max, 투명도에 대한 GPT Image 2.5 호환성을 읽어 전송 동작 및 공식 출처를 확인하세요. 모델 선택, xhigh/max, 투명도에 대한 공개 API 지원이 Codex Responses에서 동일한 동작을 보장하지는 않습니다.

연속 처리

요청이 바로 직전 턴에서 생성된 이미지를 수정하는 경우 ("더 어둡게", "이제 모자 추가", "대비 더 높게"), --from-last를 전달하세요. 스크립트가 마지막 생성 결과를 자동으로 재사용합니다 (~/.codex-image/last.json에 추적됨). 따라서 트랜스크립트에서 경로를 복구할 필요가 없습니다.

명시적인 파일이나 이전 생성 결과를 편집하려면 대신 --input <path|url>를 전달하세요 (반복 가능, --from-last와 결합하여 최대 16개 참조, 스킬 참조 제한).

요청이 새로운 주제인 경우 — "이제 만들어…"라는 표현이어도 — 둘 다 전달하지 말고 처음부터 생성하세요. 잘못 추측하여 사용자가 "아니, 새로 만들라고 했어"라고 말하면 참조 없이 다시 실행하세요.

사용자가 스타일, 구성, 또는 분위기 용도로만 제공한 이미지는 생성을 위한 참조일 뿐 편집 대상이 아닙니다 — --input으로 전달하되 프롬프트는 새 이미지로 작성하세요 ("Image 2 스타일로"). 여러 입력을 혼합할 때는 프롬프트에서 각각을 인덱스와 역할로 표시하세요 (Image 1: 편집 대상, Image 2: 스타일 참조).

생성 후: 확인 후 보고

사용자에게 완료를 알리기 전에 저장된 이미지 파일을 보고 요청 사항과 대조 확인하세요: 주제, 구성, 렌더링된 모든 문자 텍스트, 사용자가 명시한 모든 제약 조건. 문제가 있으면 하나의 대상 변경(--from-last 사용)으로 반복하고, 변경되지 않아야 할 불변 조건을 다시 명시하세요. 여러 수정 사항을 한 번의 재실행에 쌓지 말고, 확인하지 않은 경로를 보고하지 마세요.

저장 규율: 출력 기본값은 ./generated_images/입니다. 이미지가 사용자의 프로젝트에 사용될 예정이면 실제 위치로 복사하거나 이동하고 (그리고 이를 참조하는 모든 코드를 업데이트하세요) — 프로젝트 자산을 임시 디렉토리에 남겨두지 마세요. 사용자가 교체를 요청하지 않은 기존 자산을 절대 덮어쓰지 말고, 버전이 지정된 형제 파일을 대신 작성하세요 (hero-v2.png).

투명 이미지

사용자가 투명 배경을 원할 때 --transparent를 추가하세요. 그게 전부입니다 — 디스패치 결정, Pillow, 또는 사용자가 조정해야 할 후처리 단계가 없습니다.

스크립트는 모델에 직접 알파를 요청합니다: background: "auto"를 보내고 프롬프트에 한 문장을 추가하며, 백엔드는 RGBA를 반환합니다. --background transparent를 전달하지 마세요. 이 값은 이 백엔드에서 거부됩니다 (docs/adr/0001-request-transparency-in-the-prompt.md에 이유와 명백한 "수정"이 왜 잘못되었는지 설명되어 있습니다).

직접 백엔드를 테스트하고 "Transparent background is not supported for this model." 메시지를 본 경우, 투명도를 사용할 수 없다고 결론짓지 마세요. 해당 400 오류는 파라미터가 거부된 것이지 기능이 거부된 것이 아닙니다. 모델은 프롬프트에서 요청할 때 실제 알파를 반환하며, 이것이 --transparent가 하는 일입니다. 네이티브 투명도에 gpt-image-1.5 또는 OPENAI_API_KEY가 필요하다는 조언은 0.2.0 이전 버전이며 잘못되었습니다. 해당 조언을 읽고 있다면 설치된 스킬이 오래된 것입니다. 이 파일의 metadata.version을 확인하세요 — 0.2.0 이상이어야 합니다.

프롬프트를 작성할 때 올바르게 처리해야 할 두 가지 사항:

• 장면이 아닌 대상을 설명하세요. 프롬프트가 파라미터를 능가합니다. "햇빛이 드는 스튜디오의 나무 테이블 위에 있는 머그"는 머그를 분리하는 대신 해당 스튜디오를 렌더링할 수 있습니다. 대상과 재질을 명명하고 주변 환경은 생략하세요.
• 자체 금지 사항을 추가하지 마세요. 접미사는 의도적으로 아무것도 금지하지 않습니다. 사용자가 드롭 섀도를 요청했다면 허용하세요 — 알파에 렌더링되어 돌아오며 올바르게 합성됩니다. "그림자 없음, 배경 없음"을 직접 추가하면 사용자의 의도를 무시하게 됩니다.

생성 후 파일을 보고 알파가 실제로 도착했는지 확인하세요. 스크립트는 결과에 알파가 없거나 완전히 불투명한 경우 stderr에 경고합니다. 이를 하나의 대상 변경(보통 장면 언어 제거)으로 재실행해야 하는 신호로 처리하세요.

대체 사다리, 네이티브가 실망스러운 경우에만 사용 (불투명 대상에서 확인됨, 머리카락, 유리, 연기 및 반투명은 테스트되지 않음):

단계	작업
재프롬프트	장면/배경 언어 제거, 대상만 명명
품질 향상	미세한 가장자리와 작은 텍스트를 위해 --quality medium
크로마	--transparent-mode chroma (Pillow 필요) — 키 플레이트를 제어합니다
Adobe MCP	--transparent-mode chroma --bg-tool=none, 그런 다음 이 세션에서 노출되는 Adobe 배경 제거 도구를 호출하고 (이름에 remove_background가 포함된 MCP 도구를 찾으세요) 파일을 알파 결과로 덮어씁니다. 반투명에 가장 좋은 옵션

크로마 가장자리 복구: 얇은 프린지 → --edge-contract 1; 무광 대상의 계단식 가장자리 → --edge-feather 0.25. 더 깊은 실패 모드: references/transparent-image-tips.md.

품질, 비용 및 시간 보호 장치

• 기본값은 --quality high입니다. low, medium, high, xhigh, max, auto를 요청할 수 있습니다. 초안에는 low로 시작하세요. Codex Responses가 품질을 재정의할 수 있습니다. 레벨이 전달되었다고 주장하기 전에 사이드카의 resolved_quality 또는 --verbose 출력을 확인하세요.
• 생성은 사용자의 ChatGPT 요금제 한도에 포함됩니다. 지연 시간은 모델, 프롬프트, 품질 및 서비스 부하에 따라 다릅니다.
• 단일 요청에 대해 3개 이상의 이미지를 생성하기 전에 먼저 사용자에게 확인하세요.
• 무한 루프를 절대 돌지 마세요. "많은" / "전체 세트" → 적절한 기본값(4)을 선택하고 계속할 것을 제안하세요.
• 백엔드로부터 HTTP 429 = 즉시 중지, 재시도하지 마세요.

일반적인 워크플로우

# 단일 생성
bash "<skill-dir>/scripts/generate.sh" "밤에 비 오는 노란 택시"

# 이전 생성 연속
bash "<skill-dir>/scripts/generate.sh" "이제 김이 피어오르게" --from-last

# 명시적 참조 이미지 편집
bash "<skill-dir>/scripts/generate.sh" "파란색으로" --input ./mug.png

# 투명 배경 (모델의 네이티브 알파, Pillow 불필요)
bash "<skill-dir>/scripts/generate.sh" "커피 머그" --transparent

# 투명, 사용자가 요청한 그림자 포함 (알파에 유지)
bash "<skill-dir>/scripts/generate.sh" "부드러운 드롭 섀도가 있는 커피 머그" --transparent

# 크로마 대체, 네이티브가 실망스러울 때 (Pillow 필요)
bash "<skill-dir>/scripts/generate.sh" "유리병" --transparent --transparent-mode chroma

# 다른 크기 / 형식 / 품질
bash "<skill-dir>/scripts/generate.sh" "히어로 배너" --size 2048x1152 --format webp --quality low

토큰 편집 (보안)

사용자의 access_token, id_token, refresh_token 또는 Authorization: Bearer ... 헤더를 절대 출력하거나 기록하지 마세요. 스킬의 Python 모듈은 자동으로 편집합니다. ~/.codex/auth.json을 직접 읽거나 오류 메시지에 토큰을 표시하여 이를 무효화해서는 안 됩니다.

호출하지 말아야 할 경우

• 벡터 아트, SVG, ASCII 아트 또는 LaTeX 다이어그램 → 전용 벡터 또는 다이어그램 도구를 사용하세요.
• 사용자가 명시적으로 다른 모델 또는 제품(DALL-E, Stable Diffusion, Midjourney)을 원하는 경우 → 해당 도구에 위임하세요.

프로덕션 로고/브랜드 작업의 경우 호출하세요 — 그러나 기대치를 설정하세요: 탐색을 생성하고 단일 변경 --from-last 반복으로 구체화하며, 한 번에 최종 자산을 약속하지 마세요 (템플릿은 references/prompting-cookbook.md에 있음).

참조

더 깊이 있는 내용이 필요하면 <skill-dir>/references/에서 읽으세요:

• api-recipe.md — 표준 요청 본문, 헤더, 거부된 필드, 투명도 메커니즘, SSE 구문 분석
• prompting-cookbook.md — 프롬프팅 기본 + 사용 사례 템플릿 (로고, 제품 샷, UI 목업, 인포그래픽)
• transparent-image-tips.md — 네이티브 투명도 작동 방식, 문제가 발생하는 경우, 크로마 대체

리포지토리 수준 컨텍스트: CONTEXT.md (용어집 — 세 가지 전송이 정의되어 있음) 및 docs/adr/ (투명도가 파라미터가 아닌 프롬프트에서 요청되는 이유)