Codex 이미지 생성 · qiaomu-codex-imagegen

모든 Agent가 Codex 내장 이미지 생성 기능을 호출할 수 있게 합니다: 이미지를 생성할 때마다 최소 네 가지 메커니즘이 다른 스타일 방향을 먼저 제시하고, 사용자가 선택한 후에 출력을 진행합니다. 이 시스템은 24가지 클래스의 시나리오 템플릿(48개 프리셋), 20명의 Mondo 포스터 디자이너 스타일, 그리고 사실 왜곡이나 무의미한 텍스트 생성을 방지하는 규칙 세트를 내장하고 있습니다.

Codex의 이미지 생성 도구는 Codex 내부에서만 사용 가능했습니다. 이 프로젝트가 이를 외부로 연결했습니다: MCP 서비스, 명령줄 인터페이스(CLI), 그리고 Agent Skill을 통해 동일한 핵심 기능을 공유합니다. Claude Code, Codex, Cursor 또는 명령 실행이 가능한 모든 Agent는 "샤오홍슈 스타일 이미지 하나 만들어줘"라고 말하는 것만으로도 이미지 파일을 받을 수 있습니다.

MCP, CLI 또는 스킬을 통해 모든 Agent가 Codex의 내장 이미지 생성 기능을 사용할 수 있게 합니다. 요청 시마다 최소 네 가지 메커니즘이 다른 스타일 방향(24개 템플릿, 48개 프리셋, 20명의 Mondo 아티스트)을 먼저 제시하며, 사용자가 선택하면 프롬프트를 구성하고 이미지를 생성하며 결과를 검토합니다.

방안 제안 후 이미지 출력

Agent에게 "이번 영상에 사용할 커버 이미지를 만들어줘"라고 지시하면, Agent는 바로 그림을 그리지 않고 다음 순서대로 진행합니다:

1. 방향 추천: suggest_directions 함수를 통해 최소 네 가지 메커니즘이 다른 방향을 제시하며, 이들은 서로 다른 계열(텍스트 중심, 평면 구조, 사진 인물, 제품 근접 촬영, 소재 공간 등)에서 나옵니다. 각 방향은 스타일 잠금(style lock), 사용자가 보충해야 할 정보, 그리고 참고 사례 축소 이미지를 포함합니다.
2. 사용자 선택: 사용자에게 하나 또는 여러 개를 선택하게 하거나 "네가 정해줘"라고 요청할 수 있습니다. 더 많은 옵션을 원하면 이 목록에서 제외한 후 다시 추천받을 수도 있습니다.
3. 프롬프트 구성: compose_prompt 함수는 변수들을 채워 완전한 프롬프트를 만들고, 동시에 피해야 할 항목(avoidance items), 검수 조건(acceptance criteria), 가정 사항(assumptions), 그리고 누락된 정보를 제공합니다. '구조 대체'가 포함된 프리셋은 충돌하는 문장들을 단순히 붙여 넣지 않고 Agent에게 재작성을 요청할 것입니다.
4. 생성: 선택된 각 방향별로 이미지를 하나씩 생성하며, 이미지 옆에는 실제 프롬프트를 기록한 JSON 파일이 남습니다. 이는 결과물을 재현하거나 시리즈를 만들 때 편리합니다.
5. 검수: Agent는 이미지를 보고 검수 조건에 따라 항목별로 점검합니다. 불합격인 경우 해당 문장만 수정하여 다시 생성할 수 있습니다.

사용자가 스타일("Mondo 스타일 사용", "T03")을 지정했거나 "바로 출력해줘"라고 말하면, 이 선택 단계를 건너뜁니다.

기능 범위

예시

아래의 모든 이미지는 이 도구를 사용하여 Codex가 생성한 것이며, 후반 작업(포토샵 등)은 거치지 않았습니다. 활동, 브랜드, 인물 및 문안은 모두 허구적인 예시입니다. 각 이미지의 프롬프트와 파라미터는 docs/samples/prompts.json에서 확인할 수 있습니다.

동일 주제, 다섯 가지 방향

주제는 모두 "카페 독서의 달"입니다. suggest_directions가 제시하는 방향 메커니즘은 완전히 다르기 때문에, 단순히 필터만 바꾼 같은 이미지가 나오는 것이 아닙니다:

24개 클래스별 예시 이미지

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

장면 예시

수정된 이미지 (改图)

이러한 예시는 어떻게 만들어졌는가

• 모든 카테고리는 전체 과정을 거칩니다: 추천 방향 제시 → 변수 채우기 → 생성 → 참고 사례와 대조하여 검수.
• 1차 버전 불합격, 재작업: 처음에는 제목만 주거나 아예 텍스트를 주지 않아 깔끔한 컨셉 아트가 나왔을 뿐, 포스터는 아니었습니다. 나란히 참고 사례와 비교하며 부제목, 정보 행, 각주라는 레이어의 텍스트를 보완해야 현재 수준에 도달했습니다. 인물(T09–T11)은 방법론에 따라 텍스트 없이 유지합니다.
• 1차 버전에서는 도구의 결함이 노출되기도 했습니다: 이미지의 약 4분의 1이 투명 채널을 가져, 이미지 보기 소프트웨어에서 검은 테두리로 표시되었습니다. 현재는 프롬프트가 배경을 불투명하게 요구하며, 저장 후 투명 영역이 감지되면 자동으로 흰색 바탕으로 평탄화됩니다 (transparent_background: true로 유지 가능).
• 이미지 내 텍스트: 제목과 주요 문안은 장별로 교차 확인했습니다. 작은 글씨의 정보 행은 여전히 미세한 결함이 있을 수 있으니, 공식 사용 시에는 확대하여 점검해 주십시오.
• 인물 사진은 AI가 생성한 가상의 인물이며, 실제 개인을 나타내지 않습니다.

설치

선행 조건:

• Node.js 18+ (node --version)
• 설치 및 로그인된 Codex CLI (codex --version 실행 가능)
• Codex 계정으로 이미지 생성 사용 가능 (먼저 Codex에서 수동으로 하나를 생성해 보세요)

1. Skill로 설치하기 (Agent Skills를 지원하는 모든 도구)

npx skills add joeseesun/qiaomu-codex-imagegen

Skill은 Agent가 어떤 장면, 스타일, 설명을 작성해야 할지 알게 해주고, 아래의 MCP 또는 내장 CLI를 통해 이미지를 출력합니다.

2. MCP 등록 (권장, Agent가 직접 도구 호출)

Claude Code:

claude mcp add --scope user qiaomu-codex-imagegen -- node /절대경로/qiaomu-codex-imagegen/scripts/mcp-server.mjs

다른 MCP 클라이언트(Cursor, Codex 등)의 경우, 설정에 추가합니다:

{
  "mcpServers": {
    "qiaomu-codex-imagegen": {
...

총 일곱 가지 도구를 제공합니다:

3. 명령줄만 사용하기

git clone https://github.com/joeseesun/qiaomu-codex-imagegen && cd qiaomu-codex-imagegen
node scripts/cli.mjs "창가에 펼쳐진 책, 페이지에서 커피의 김이 올라오는 모습" --preset xiaohongshu

이렇게 직접 말할 수 있어요

Skill과 MCP를 설정한 후, Agent에게 다음과 같이 말하세요:

• 「이번 영상 썸네일(16:9)을 디자인 감각 있게 만들어줘. 세 가지 안을 먼저 내줘」
• 「초저홍슈(小红书)용 이미지 세트를 만들고 싶어. 주제는 아침 독서야. 첫 번째 이미지는 스타일을 정하고, 나머지는 통일된 느낌으로 해줘」
• 「Olly Moss 스타일로 《듄》 영화 포스터를 만들어줘. 글자는 넣지 마」
• 「이 이미지의 배경을 베이지색 종이 질감으로 바꿔주고, 주체는 그대로 유지해 줘」

사용 예시 (명령줄)

# 먼저 방향을 제시받고(무료), 그 다음 선택하기
node scripts/cli.mjs suggest "한 달간의 카페 독서 이벤트" --for 영상커버

...

쉬운 경로 (방향 제시를 거치지 않을 때 권장):

# 영상 커버, 세 가지 안을 먼저 보기
node scripts/cli.mjs "거대한 빨간색 재생 버튼이 일출처럼 떠오르는 모습" --preset video-cover --style saul-bass --count 3

...

매개변수: --preset (장면), --style (스타일, 키워드 또는 자유 텍스트), --ratio (커버 비율), --text (이미지 내 텍스트, 반복 가능), --ref (참고 이미지, 반복 가능, 절대 경로), --count (병렬 변형 개수 1–4), --out (출력 디렉토리), --name (파일명), --model, --timeout, --json (기계가 읽을 수 있는 출력). 기본적으로 ~/Pictures/qiaomu-codex-imagegen/<날짜>에 저장됩니다.

장면 프리셋

내장 디자인 자료

• 24가지 템플릿, 48개의 프리셋 (references/design-system/): 거대한 글자와 미세한 서사, 사물 프레임 이탈(物象破框), 중앙 광선 간격(中央光隙), 동양 수묵화(东方水墨), 종이 조각 지형(纸雕地貌), 민예 색상 충돌(民艺撞色), 아동화, 꽃밭 콜라주(花境拼贴), 스튜디오 촬영 및 환경/결혼 초상화, 식품 및 음료 클로즈업, 식물 수채화 제품, 과학 기술 트랙, 거대 사물의 축소(巨物微缩), 건축 도면, 프레임 뷰(框景), 문화 박물관 재질, 회의 명단, 구구격자(九宫格), 발표 자료, 과학 상식 카드, 일일 기록. 각 카테고리는 스타일 잠금(风格锁)(이미지 생성 시 반드시 충족해야 하는 관계), 대체 가능한 변수, 실패 조건 및 승인 항목을 포함합니다.
• 방법론: 관계가 사물보다 안정적입니다; 색상은 역할에 따라 대체됩니다; 글자도 형태를 가집니다; 재료는 위치를 가집니다; 하나의 예외만으로 충분합니다; 초상화는 신분을 먼저 보존하고, 정보도는 사실을 먼저 보존합니다. 전체 규칙은 agent-guide에서 확인 가능하며, 인간이 읽을 수 있는 버전은 템플릿 라이브러리와 채우기 예시를 참고하세요.
• 템플릿은 보관된 689개의 공개 기록에서 추출되었습니다; 추출되는 것은 메커니즘과 변수이며, 원본 이미지의 복제는 아닙니다. 원본 이미지를 재현할 수 있다는 증거는 없습니다.

내장 스타일

• 66가지 범용 스타일: 미니멀 라인(极简线条), 수채화, 종이 조각, 등거리(等距), 픽셀, 로우 폴리곤(低多边形) 등. references/styles.json 참조.
• 20명의 포스터 디자이너 (Mondo 기법은 qiaomu-mondo-poster-design에서 통합): Olly Moss, Saul Bass, Martin Ansin, Tyler Stout, Kilian Eng, Drew Struzan 등. 또한 실크스크린, 네거티브 스페이스(负空间), 책 및 앨범 커버 전용 스타일이 있습니다. 어떤 것을 선택하고 어떻게 작성하는지는 references/mondo-poster.md를 참고하세요.

로컬 데이터 패키지 (선택 사항)

템플릿 라이브러리는 저장소와 함께 배포됩니다. 689개의 원본 레퍼런스 프롬프트와 미리보기 이미지는 저장소에 포함되어 있지 않습니다: 이들은 小小东 오픈 프롬프트의 공개 구역(유료 프롬프트 라이브러리의 무료 샘플)에서 가져온 제3자 콘텐츠이며, 개방 승인 여부를 확인하지 못했기 때문에 로컬 데이터 패키지로만 구성되어 저장소와 함께 배포되지 않습니다.

데이터 패키지가 있는 경우: search_prompts / get_prompt로 원문을 검색하고 읽을 수 있으며, suggest_directions는 참고 썸네일과 유사 사례를 첨부합니다. 데이터 패키지가 없는 경우 모든 것이 평소와 같으며, 이 부분만 빠진 것입니다.

# 본인의 아카이브 디렉토리(archive.json, prompts/, images/ 포함)로 구성하며, 기본적으로 ~/.local/share/qiaomu-codex-imagegen/corpus에 설치됩니다.
node scripts/build-corpus.mjs /path/to/小小东提示词归档
# 또는 환경 변수 QIAOMU_CORPUS_DIR을 사용하여 다른 곳을 지정할 수 있습니다.

데이터 패키지는 약 12 MB이며(썸네일 너비 360 px), 로컬에서만 사용해야 하며, 제출하거나 전달해서는 안 됩니다.

작동 방식

Qiaomu Agent의 Obsidian 플러그인과 동일한 방식으로 작동합니다: codex app-server --listen stdio://를 실행하여 (표준 입출력상의 JSON-RPC) 턴을 시작하고 이미지 생성을 요청하며, imageGeneration 작업이 완료될 때까지 기다린 후 Codex가 저장한 이미지를 지정된 디렉토리로 복사합니다. 매 호출마다 독립적인 임시 세션을 시작하며, 샌드박스는 출력 디렉토리에 쓰기만 허용하고, 승인 정책은 never입니다. 상호 작용 요청이 발생하면 모두 거부됩니다.

실측 및 제한

• 비율(比例): Codex는 프롬프트에 명시된 비율을 준수합니다. 실측 결과, 3:4로 설정 시 1086×1448이 나오고, 21:9로 설정 시 1916×821이 나옵니다. 비율을 지정하지 않으면 기본적으로 정사각형(실측 1254×1254)으로 출력됩니다. 도구는 결과의 픽셀 크기를 읽어오며, 요구 사항과 다를 경우 결과물에 이를 표시합니다.
• 소요 시간 및 할당량: 이미지 한 장당 약 30~60초가 소요되며, Codex/OpenAI 계정 할당량을 소비합니다. count는 최대 4까지 가능하며, 병렬로 실행할 경우 할당량이 배수로 소모됩니다.
• 이미지 내 텍스트: 포스터, 커버, 카드 등은 텍스트 계층(제목, 부제목, 정보 행, 각주)이 필요합니다. 제목만 있는 이미지는 개념도일 뿐 포스터가 아닙니다. 따라서 이러한 용도로는 exact_short를 사용하고, 전체 짧은 문안 세트를 제공할 때는 (copy) ｜로 구분합니다. 모델이 중국어와 긴 문장을 작성하는 경우 오류가 발생하기 쉬우므로, 각 문장은 짧게 하고 생성 후에는 글자 단위로 검사해야 합니다. 인물 사진이나 정보가 없는 제품 클로즈업의 경우 텍스트를 넣지 않아도 됩니다.
• Codex 의존성: Codex가 설치되지 않았거나 로그인하지 않았거나 계정에 이미지 생성 권한이 없을 경우 명확한 오류가 반환됩니다. 환경 변수 QIAOMU_CODEX_BIN을 사용하여 Codex 경로를 지정할 수 있습니다.
• 크기나 개수와 같은 하위 레벨 파라미터: 이는 Codex의 이미지 생성 도구에 의해 결정되며, 설명이나 사전 설정에 작성합니다.

문제 해결 (Troubleshooting)

검증 (Verification)

npm test                                                  # 오프라인 테스트
node scripts/cli.mjs --list                               # 사전 설정 및 스타일 확인
node scripts/cli.mjs

⚠️ `[IMG:N]` 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

| 후원 지원 | 위챗 공식 계정 |
|---|---|
| <img src="https://raw.githubusercontent.com/joeseesun/qiaomu-codex-imagegen/HEAD/assets/qiaomu-profile/qiaomu_reward_qr.png" alt="향양교목 후원 QR 코드" width="180" /> | <img src="https://raw.githubusercontent.com/joeseesun/qiaomu-codex-imagegen/HEAD/assets/qiaomu-profile/qiaomu_wechat_public_account_qr.jpg" alt="향양교목 추천 공지 계정 QR 코드" width="180" /> |
| 감사드립니다. 교목의 지속적인 AI 실습 공유를 응원합니다 | 스캔하여 「향양교목 추천 공지」 팔로우하기 |

<!-- qiaomu-profile:end -->

## 라이선스

Copyright (c) 향양교목 · X [@vista8](https://x.com/vista8) · GitHub [joeseesun](https://github.com/joeseesun/) · MIT License