| name | codex-image |
| description | Tạo và chỉnh sửa ảnh bitmap qua OpenAI Codex CLI (gpt-image-2), có fallback gọi thẳng OpenAI API. Hỗ trợ: text-to-image, nền trong suốt (chroma-key + native transparency gpt-image-1.5), batch generation, image editing (style transfer qua codex exec -i, edit chính xác/mask qua API), size chính xác tới 4K, quality control. Trigger: tạo ảnh, generate image, vẽ icon, logo, banner, illustration, minh họa, transparent background, xóa nền, ảnh trong suốt, batch ảnh, sửa ảnh, edit image, chỉnh ảnh, tạo ảnh hàng loạt, inpainting, ảnh 4K. KHÁC ai-artist (skill này dùng OpenAI gpt-image-2 trực tiếp + hỗ trợ edit ảnh có sẵn, ai-artist dùng Nano Banana với 129 curated prompts). KHÔNG dùng khi cần sửa SVG/vector/icon-system có sẵn trong repo hoặc đồ họa nên làm bằng HTML/CSS/SVG code-native. |
| argument-hint | [mô tả ảnh] [--size WxH] [--transparent] [--batch N] [--edit input.png] |
Codex Image: Tạo ảnh qua Codex CLI + OpenAI API fallback
Tạo và chỉnh sửa ảnh với model gpt-image-2 (mặc định) qua hai chế độ.
Hai chế độ
| Chế độ | Cơ chế | Điều kiện | Khi nào dùng |
|---|
Mặc định: codex exec | Nhờ Codex agent gọi built-in tool $imagegen | Codex CLI + đăng nhập ChatGPT (không cần API key) | Mọi request thông thường: generate, biến tấu, chroma-key transparent, batch |
Fallback: scripts/image_gen.py | Gọi thẳng OpenAI Image API | OPENAI_API_KEY + openai/pillow trong venv | Chỉ khi user yêu cầu rõ CLI/API/model control, HOẶC user xác nhận cần: size/quality chính xác, edit high-fidelity/mask, native transparency (gpt-image-1.5) |
Quy tắc chuyển chế độ:
- Không tự chuyển sang fallback chỉ vì cần chỉnh size/quality thông thường — hint trong prompt trước.
- Không bao giờ âm thầm đổi xuống
gpt-image-1.5 — đó là downgrade model, phải hỏi user trước (trừ khi user đã yêu cầu đích danh).
- Fallback cần
OPENAI_API_KEY: nếu chưa có, hướng dẫn user tạo key tại https://platform.openai.com/api-keys và tự đặt env var — không bao giờ yêu cầu user dán key vào chat.
- Không sửa
scripts/image_gen.py (script vendor từ OpenAI, Apache 2.0 — xem scripts/LICENSE.txt). Thiếu gì thì hỏi user.
Khi nào KHÔNG dùng skill này
- Icon/logo/đồ họa UI cần khớp bộ SVG/vector có sẵn trong repo → sửa trực tiếp file vector.
- Hình khối đơn giản, diagram, wireframe → làm bằng SVG/HTML/CSS code-native tốt hơn.
- Ảnh đã tồn tại trong project ở định dạng editable, chỉ cần sửa nhỏ → sửa file gốc.
Yêu cầu môi trường
codex --version
Fallback CLI cần thêm: uv pip install --python ~/.venv/claude/bin/python openai pillow và OPENAI_API_KEY.
Workflow
- Chế độ: mặc định
codex exec; fallback chỉ khi user yêu cầu rõ hoặc đã xác nhận.
- Ý định: user muốn ảnh mới (kể cả có ảnh tham chiếu style/mood) → generate; muốn giữ nguyên phần lớn ảnh cũ → edit. Không rõ thì coi là generate.
- Số lượng: 1 ảnh → 1 lệnh; nhiều asset khác nhau → mỗi asset 1 lệnh (hoặc
batch-generate.py); nhiều prompt trên đường API → generate-batch.
- Prompt: dựng theo schema bên dưới, áp dụng chính sách augmentation.
- Chạy → verify file tồn tại ở đích (xem Chính sách output) → kiểm tra ảnh (subject, style, text, constraints) → iterate từng thay đổi một.
- Báo cáo: path cuối cùng, prompt đã dùng, chế độ nào.
1. Text-to-Image (đường chính)
codex exec --skip-git-repo-check --enable image_generation \
'$imagegen <PROMPT>. Save the final PNG as <TÊN_FILE>.png in <THƯ_MỤC_OUTPUT_TUYỆT_ĐỐI>.'
- Built-in tool chỉ nhận prompt text: size, style, quality đều mô tả trong prompt ("1024x1024 square format", "wide landscape 1536x1024"). Chọn size:
references/size-guide.md.
- Ví dụ:
'$imagegen A minimal flat-design coffee cup icon, white background, 1024x1024. Save as coffee-icon.png in /path/to/output.'
2. Nền trong suốt (transparent)
Mặc định dùng chroma-key trên đường chính (gpt-image-2 không hỗ trợ background=transparent):
Bước 1 — Generate trên nền chroma-key. Thêm vào prompt (nguyên văn):
Create the requested subject on a perfectly flat solid #00ff00 chroma-key background for background removal.
The background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation.
Keep the subject fully separated from the background with crisp edges and generous padding.
Do not use #00ff00 anywhere in the subject.
No cast shadow, no contact shadow, no reflection, no watermark, and no text unless explicitly requested.
Subject có màu xanh lá → thay bằng #ff00ff (magenta). Tránh key màu trùng subject.
Bước 2 — Xóa nền cục bộ:
~/.venv/claude/bin/python skills/codex-image/scripts/remove_chroma_key.py \
--input <source.png> --out <final.png> \
--auto-key border --soft-matte \
--transparent-threshold 12 --opaque-threshold 220 --despill
Lưu ý --despill: khử ánh xanh lây ở cạnh, nhưng tẩy luôn màu xanh thật trong subject (đã kiểm chứng: lá táo xanh bị biến thành xám). Subject có phần màu gần key → bỏ --despill, hoặc tốt hơn là dùng key magenta ngay từ bước 1.
Bước 3 — Validate: mở ảnh ra nhìn — output phải có alpha channel, 4 góc trong suốt, subject coverage hợp lý, không viền màu key, màu subject không bị biến đổi. Còn viền mảnh → retry một lần thêm --edge-contract 1; cạnh răng cưa rõ (subject không bóng/phản chiếu) → thêm --edge-feather 0.25.
Đường thoát — native transparency. Nếu user cần transparency thật, subject phức tạp (tóc, lông, khói, thủy tinh, chất lỏng, vật phản chiếu, bóng mềm), hoặc chroma-key fail validation → giải thích và hỏi user trước khi chạy fallback:
~/.venv/claude/bin/python skills/codex-image/scripts/image_gen.py generate \
--model gpt-image-1.5 --prompt "<PROMPT>" \
--background transparent --output-format png --out <final.png>
(Cần OPENAI_API_KEY; chưa có thì hướng dẫn đặt key. Phương án chót không cần key: tool chuyên dụng như remove.bg/Photoshop.)
3. Batch (nhiều ảnh)
Đường chính — script gọi codex exec tuần tự cho từng prompt, tự đặt tên prefix-001.png...:
~/.venv/claude/bin/python skills/codex-image/scripts/batch-generate.py \
--prompts "prompt 1" "prompt 2" --output-dir ./output-images/ --prefix batch
Đường API (chỉ khi user đã chọn fallback) — chạy song song từ JSONL, xem references/cli.md:
~/.venv/claude/bin/python skills/codex-image/scripts/image_gen.py generate-batch \
--input prompts.jsonl --out-dir output/ --concurrency 5
Lưu ý: chữ "batch" trong request KHÔNG có nghĩa là chuyển sang API fallback. Nhiều asset khác nhau = nhiều prompt riêng, không dùng --n (n chỉ dành cho biến thể của cùng 1 prompt).
4. Image Editing
Phân luồng theo mức bảo toàn ảnh gốc:
| Yêu cầu | Đường | Cơ chế |
|---|
| Biến tấu, style transfer, "vẽ lại theo hướng..." | codex exec -i (mặc định) | Model nhìn ảnh → tả lại → generate mới. Composition giữ khá tốt, KHÔNG phải edit pixel-level |
| Bảo toàn chính xác: giữ mặt/người, xóa/thay 1 vật thể, đổi nền giữ subject, sửa text trong ảnh, mask/inpainting | image_gen.py edit (fallback, hỏi trước) | Ảnh đưa thẳng vào edit endpoint; gpt-image-2 luôn high-fidelity; hỗ trợ --mask |
Đường chính (lưu ý: phải có exec và dấu -- ngăn flag -i nuốt prompt):
codex exec --skip-git-repo-check --enable image_generation \
-i <ảnh_gốc.png> -- '$imagegen Modify this image: <MÔ_TẢ>. Change only X; keep Y unchanged. Save as <output>.png in <thư_mục>.'
Nhiều ảnh tham chiếu: -i style-ref.png,content-ref.png — trong prompt gọi ảnh theo index và vai trò (Image 1: style reference...).
Đường API:
~/.venv/claude/bin/python skills/codex-image/scripts/image_gen.py edit \
--image input.png --prompt "Replace only the background with a warm sunset; keep the subject unchanged" \
--out edited.png
Quy tắc invariants: mọi prompt edit phải ghi rõ change only X; keep Y unchanged, và lặp lại ở mỗi vòng iterate để chống drift.
5. Prompt
Schema (dùng các dòng cần thiết, không phải điền đủ):
Use case: <slug taxonomy>
Primary request: <yêu cầu chính của user>
Subject / Scene: <chủ thể + bối cảnh>
Style/medium: <photo/illustration/3D...>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <ánh sáng + mood>
Text (verbatim): "<text chính xác>"
Constraints: <phải giữ / phải tránh>
Chính sách augmentation:
- Prompt user đã chi tiết → chỉ chuẩn hóa thành spec sạch, KHÔNG thêm yêu cầu sáng tạo.
- Prompt chung chung → được thêm chi tiết có chừng mực (composition, mức polish, bối cảnh hợp lý). KHÔNG thêm nhân vật/vật thể/brand/slogan không được ngụ ý.
- Thiếu chi tiết then chốt chặn thành công → hỏi user; còn lại cứ tiến hành.
Taxonomy use-case (slug): generate — photorealistic-natural, product-mockup, ui-mockup, infographic-diagram, scientific-educational, ads-marketing, productivity-visual, logo-brand, illustration-story, stylized-concept, historical-scene; edit — text-localization, identity-preserve, precise-object-edit, lighting-weather, background-extraction, style-transfer, compositing, sketch-to-render.
Chi tiết nguyên tắc: references/prompting.md. Recipe copy/paste theo use-case: references/sample-prompts.md.
Chính sách output
- Prompt luôn chỉ rõ "Save as X.png in <thư mục tuyệt đối>". Sau khi
codex exec xong, verify file tồn tại ở đích; không thấy → tìm ảnh mới nhất trong ~/.codex/generated_images/ copy về đích rồi báo user.
- Không bao giờ để asset của project nằm lại chỉ ở
~/.codex/generated_images/.
- Không ghi đè file có sẵn trừ khi user yêu cầu rõ — tạo tên phiên bản (
hero-v2.png, icon-edited.png).
- Kết thúc luôn báo: path cuối cùng, prompt đã dùng, chế độ nào.
Xử lý lỗi thường gặp
| Lỗi | Nguyên nhân | Giải pháp |
|---|
codex: command not found | Chưa cài Codex CLI | npm install -g @openai/codex |
image_generation is not enabled | Feature chưa bật | Thêm --enable image_generation |
Authentication required | Chưa đăng nhập | Chạy codex và đăng nhập ChatGPT |
No prompt provided via stdin | Flag -i nuốt prompt | Thêm -- trước prompt: -i img.png -- '$imagegen ...' |
| Mở TUI thay vì chạy | Thiếu exec | Dùng codex exec ... |
| File không xuất hiện ở đích | Codex lưu vào default path | Tìm trong ~/.codex/generated_images/, copy về đích |
| Ảnh sai kích thước (đường chính) | Model tự quyết | Ghi rõ size trong prompt; cần chính xác tuyệt đối → fallback --size |
| Text sai chính tả trong ảnh | Prompt chưa rõ | Text trong ngoặc kép, spell letter-by-letter từ khó |
| Viền xanh sau xóa nền | Cạnh mờ/antialiasing | Retry --edge-contract 1; phức tạp quá → hỏi fallback gpt-image-1.5 |
| Màu xanh trong subject bị xám hóa | --despill tẩy nhầm màu thật | Chạy lại không có --despill, hoặc generate lại trên nền magenta |
OPENAI_API_KEY missing (fallback) | Chưa đặt key | Hướng dẫn tạo key + đặt env var, không dán key vào chat |
Reference map
references/prompting.md — nguyên tắc prompt (2 chế độ dùng chung) + bảng từ vựng style/composition/lightingreferences/sample-prompts.md — recipe copy/paste theo use-case (2 chế độ dùng chung)references/size-guide.md — chọn kích thước theo use case + constraint gpt-image-2references/cli.md — fallback CLI: lệnh, flags, quality, mask, batch JSONL (chỉ đọc khi vào fallback)references/image-api.md — tham số Image API (chỉ đọc khi vào fallback)scripts/image_gen.py — fallback CLI (vendor từ OpenAI Codex, Apache 2.0, không sửa)scripts/remove_chroma_key.py — xóa nền chroma-key (vendor từ OpenAI Codex, Apache 2.0)scripts/batch-generate.py — batch tuần tự trên đường codex execscripts/LICENSE.txt — Apache License 2.0 cho các script vendor
