Hướng dẫn tạo ảnh với Qiaomu Codex: Để Claude, Cursor và mọi Agent chọn phong cách trước khi tạo ảnh

Giới thiệu dự án

qiaomu-codex-imagegen đóng gói khả năng tạo ảnh tích hợp trong Codex thành dịch vụ MCP, công cụ dòng lệnh và Agent Skill. Sau khi cài đặt, Claude Code, Codex, Cursor hoặc các Agent khác có thể thực thi lệnh đều có thể tạo tệp ảnh từ yêu cầu bằng ngôn ngữ tự nhiên.

Khác với cách “nhập một câu lệnh rồi tạo ảnh” thông thường, theo mặc định hệ thống sẽ dùng suggest_directions để đề xuất ít nhất bốn hướng phong cách có cơ chế khác nhau. Sau khi người dùng chọn hướng, compose_prompt sẽ mở rộng thành prompt hoàn chỉnh, rồi cuối cùng tạo và kiểm tra kết quả.

Dự án tích hợp 24 loại mẫu theo bối cảnh, 48 preset, 66 phong cách phổ quát và phong cách của 20 nhà thiết kế poster Mondo. Dự án cũng cung cấp bộ quy tắc về văn bản, dữ kiện, bố cục và nghiệm thu, phù hợp để tạo ảnh bìa, poster, ảnh mạng xã hội, hình ảnh sản phẩm và chỉnh sửa ảnh tham chiếu.

Quy trình cốt lõi

1. Đề xuất hướng: Dựa trên chủ đề và bối cảnh sử dụng, trả về ít nhất bốn hướng có cơ chế khác nhau, chẳng hạn như chủ đạo văn bản, cấu trúc phẳng, chân dung nhiếp ảnh, cận cảnh sản phẩm hoặc không gian vật liệu.
2. Chọn hướng: Người dùng có thể chọn một hoặc nhiều hướng, hoặc để Agent tự quyết định. Nếu chưa hài lòng, có thể loại bỏ các hướng hiện có rồi yêu cầu đề xuất lại.
3. Mở rộng prompt: Điền các biến của mẫu vào prompt hoàn chỉnh, đồng thời đưa ra các mục cần tránh, điều kiện nghiệm thu, giả định và thông tin còn thiếu.
4. Tạo ảnh: Tạo một ảnh cho mỗi hướng được chọn và lưu JSON thực tế đã sử dụng bên cạnh ảnh để thuận tiện tái hiện và sản xuất nội dung theo chuỗi.
5. Nghiệm thu và làm lại: Agent kiểm tra từng mục theo điều kiện nghiệm thu. Nếu không đạt, chỉ sửa phần tương ứng rồi tạo lại một lần.

Nếu người dùng đã chỉ định rõ phong cách, chẳng hạn “dùng phong cách Mondo” hoặc cung cấp trực tiếp T03, hệ thống có thể bỏ qua bước chọn hướng và chuyển thẳng sang dàn dựng prompt hoặc tạo ảnh.

Chuẩn bị trước khi cài đặt

Cần chuẩn bị các môi trường sau:

• Node.js 18 trở lên: Có thể kiểm tra bằng node --version.
• Codex CLI: Cần cài đặt và đăng nhập, dùng codex --version để xác nhận lệnh khả dụng.
• Quyền tạo ảnh: Tài khoản Codex hiện tại phải được phép sử dụng tính năng tạo ảnh. Nên thử tạo thủ công một ảnh trong Codex trước để xác minh.

Bản thân dự án là dự án Node.js không phụ thuộc thư viện, nhưng việc tạo ảnh thực tế vẫn cần Codex CLI khả dụng trên máy và hạn mức tài khoản.

Cài đặt Agent Skill

Nếu Agent bạn sử dụng hỗ trợ Agent Skills, có thể chạy trực tiếp:

npx skills add joeseesun/qiaomu-codex-imagegen

Skill giúp Agent hiểu cách chọn bối cảnh, chọn phong cách, viết mô tả và nghiệm thu, đồng thời tạo ảnh thông qua MCP hoặc công cụ dòng lệnh đi kèm dự án.

Đăng ký dịch vụ MCP

Đăng ký trong Claude Code

Thay đường dẫn bên dưới bằng thư mục thực tế của dự án:

claude mcp add --scope user qiaomu-codex-imagegen -- node /đường-dẫn-tuyệt-đối/qiaomu-codex-imagegen/scripts/mcp-server.mjs

Cấu hình trong các ứng dụng MCP khác

Cursor, Codex hoặc các ứng dụng MCP khác có thể thêm nội dung sau vào tệp cấu hình:

{
  "mcpServers": {
    "qiaomu-codex-imagegen": {
      "command": "node",
      "args": ["/đường-dẫn-tuyệt-đối/qiaomu-codex-imagegen/scripts/mcp-server.mjs"]
    }
  }
}

Dịch vụ MCP cung cấp bảy công cụ:

• suggest_directions: Đề xuất miễn phí, tức thời ít nhất bốn hướng phong cách có cơ chế khác nhau.
• compose_prompt: Mở rộng mẫu và preset thành prompt hoàn chỉnh, đồng thời trả về các mục cần tránh, điều kiện nghiệm thu và thông tin còn thiếu.
• generate_image: Tạo ảnh mới hoặc chỉnh sửa ảnh tham chiếu, rồi trả về đường dẫn tệp và kích thước pixel.
• search_prompts và get_prompt: Tìm kiếm và đọc kho prompt tham chiếu cục bộ.
• build_prompt: Xem trước prompt được tạo theo lộ trình đơn giản, nhưng không thực sự tạo ảnh.
• list_catalog: Xem preset bối cảnh, mẫu, khóa phong cách và trạng thái kho dữ liệu cục bộ.

Chỉ sử dụng dòng lệnh

Nếu không cần MCP, bạn cũng có thể sao chép kho mã rồi chạy CLI:

git clone https://github.com/joeseesun/qiaomu-codex-imagegen
cd qiaomu-codex-imagegen
node scripts/cli.mjs "Cuốn sách mở bên cửa sổ, hơi nóng từ cà phê bay lên trên trang sách" --preset xiaohongshu

Ảnh được tạo mặc định sẽ lưu vào ~/Pictures/qiaomu-codex-imagegen/<ngày>. Có thể dùng --out, --name và --json để kiểm soát thư mục đầu ra, tên tệp và kết quả mà máy có thể đọc.

Cách dùng cơ bản: đề xuất hướng trước

Đối với các tác vụ poster, ảnh bìa và ảnh mạng xã hội, nên ưu tiên quy trình “đề xuất trước, tạo sau”. Lệnh dưới đây sẽ đề xuất nhiều hướng cho “sự kiện đọc sách tại quán cà phê” nhưng không tiêu hao hạn mức tạo ảnh:

node scripts/cli.mjs suggest "Sự kiện đọc sách kéo dài một tháng tại quán cà phê" --for Ảnh bìa video

Kết quả thường mô tả cơ chế hình ảnh, khóa phong cách, thông tin cần bổ sung và ví dụ tham khảo của từng hướng. Bạn có thể chọn một hướng hoặc yêu cầu Agent tạo song song nhiều hướng để so sánh.

Mở rộng prompt theo mẫu

Sau khi xác định hướng, có thể xem prompt hoàn chỉnh và điều kiện nghiệm thu trước:

node scripts/cli.mjs compose --template T03-1 --var topic=Tiết Cốc Vũ --var subject=Mầm non --var headline=Tiết Cốc Vũ

Mẫu sẽ tạo mô tả có cấu trúc dựa trên các biến. Ngoài chủ thể và phong cách, mô tả có thể bao gồm cấp bậc văn bản, khoảng trống, vùng an toàn, điều kiện thất bại và tiêu chuẩn kiểm tra. Xem prompt trước giúp phát hiện biến còn thiếu hoặc nội dung quá dài trước khi tạo chính thức.

Tạo ảnh bằng mẫu

Sau khi xác nhận prompt chính xác, có thể tạo trực tiếp:

node scripts/cli.mjs generate --template T03-1 --var topic=Tiết Cốc Vũ --var subject=Mầm non --var headline=Tiết Cốc Vũ

Dự án bao gồm 24 loại mẫu, chẳng hạn như chữ khổng lồ với câu chuyện nhỏ, vật thể phá khung, khe sáng trung tâm, biên tập mực nước phương Đông, địa hình giấy cắt và vải dệt, chân dung nhiếp ảnh, cận cảnh thực phẩm, hình ảnh chủ đạo sản phẩm công nghệ, bản vẽ kiến trúc và thẻ thông tin. Các mẫu khác nhau không chỉ thay đổi màu sắc hay bộ lọc, mà còn thay đổi cơ chế bố cục, quan hệ vật liệu, cấp bậc văn bản và mối quan hệ giữa các chủ thể.

Tạo nhanh bằng preset và phong cách

Nếu đã biết bối cảnh và phong cách, có thể dùng lộ trình đơn giản mà không cần đề xuất hướng. Ví dụ, tạo ba phương án ảnh bìa video:

node scripts/cli.mjs "Một nút phát màu đỏ khổng lồ mọc lên như mặt trời mọc" --preset video-cover --style saul-bass --count 3

Các preset bối cảnh thường dùng gồm:

• xiaohongshu và xiaohongshu-square: Ảnh bìa Xiaohongshu tỷ lệ 3:4 hoặc hình vuông.
• video-cover: Ảnh bìa ngang 16:9 cho YouTube, Bilibili và các nền tảng khác.
• video-vertical: Ảnh bìa dọc 9:16 cho Douyin, WeChat Channels và Reels.
• wechat-cover: Ảnh đầu bài tỷ lệ 2.35:1 cho tài khoản công chúng WeChat.
• x-cover: Ảnh bìa trang cá nhân X tỷ lệ 5:2.
• moments: Poster Moments tỷ lệ 4:5.
• poster và movie-poster: Poster phổ thông và poster phim.
• book-cover, album-cover, article và paper: Hình minh họa cho sách, album, bài viết và nội dung khoa học phổ thông.

Ví dụ, dùng phong cách Mondo để tạo poster phim không có chữ:

node scripts/cli.mjs "Bóng dáng sâu cát khổng lồ trong sa mạc, một bóng người nhỏ bé" --preset movie-poster --style olly-moss

Kiểm soát văn bản trong ảnh

Poster và ảnh bìa thường cần tiêu đề, phụ đề, dòng thông tin hoặc nhãn góc, thay vì chỉ đặt một tiêu đề. Có thể dùng --text để chỉ định văn bản:

node scripts/cli.mjs "Một ngọn hải đăng" --preset wechat-cover --text "Con tàu đêm"

Nếu có văn bản tiếng Trung hoặc nội dung dài, nên cung cấp từng chữ trong câu ngắn và phóng to kiểm tra sau khi tạo. Tài liệu dự án chỉ ra rằng mô hình vẫn có thể mắc lỗi nhỏ khi tạo tiếng Trung và các dòng thông tin cỡ nhỏ. Với chân dung hoặc cận cảnh sản phẩm không cần lớp thông tin, có thể dùng phương án không chữ.

Chỉnh sửa ảnh tham chiếu

Có thể cung cấp một hoặc nhiều ảnh tham chiếu bằng --ref. Đường dẫn ảnh phải là đường dẫn tuyệt đối:

node scripts/cli.mjs "Giữ nguyên cây bút chì này, đổi nền thành giấy màu be ấm" --ref /abs/pencil.png --ratio 1:1

Cách này phù hợp để thay nền, giữ nguyên chủ thể hoặc điều chỉnh hình ảnh cục bộ. Dự án không âm thầm cắt ảnh. Nếu tỷ lệ cuối cùng không phù hợp yêu cầu, kết quả sẽ ghi rõ chênh lệch kích thước.

Xem trước prompt và tìm kiếm ví dụ cục bộ

Nếu chỉ muốn kiểm tra prompt mà không tạo ảnh, có thể dùng:

node scripts/cli.mjs "Cà phê và sách" --preset xiaohongshu --show-prompt

Nếu đã xây dựng gói dữ liệu cục bộ tùy chọn, cũng có thể tìm kiếm các ví dụ tương tự:

node scripts/cli.mjs search "tiết khí trà" --limit 5

Gói dữ liệu bao gồm khoảng 689 prompt tham chiếu và ảnh thu nhỏ, nhưng dữ liệu bên thứ ba này không được phát hành cùng kho mã. Khi không có gói dữ liệu, quy trình mẫu, phong cách và tạo ảnh vẫn hoạt động bình thường.

Cấu hình nâng cao và đề xuất thực hành

Cố định hướng cho ảnh theo chuỗi

Khi tạo một bộ ảnh Xiaohongshu hoặc nhiều ảnh bìa, nên chọn mẫu và phong cách cho ảnh đầu tiên, sau đó để các ảnh tiếp theo dùng cùng khóa phong cách, tỷ lệ và cấu trúc thông tin. Cách này giúp duy trì tính nhất quán dễ hơn so với việc nhập “phong cách tương tự” riêng cho từng ảnh.

Kiểm soát hạn mức khi dùng biến thể song song

--count có thể tạo song song từ 1 đến 4 biến thể, nhưng mỗi hình ảnh sẽ tiêu tốn hạn mức của tài khoản Codex hoặc OpenAI. Một hình ảnh thường mất khoảng 30 đến 60 giây; số lượng chạy song song càng nhiều thì mức tiêu thụ cũng tăng tương ứng.

Xử lý vấn đề nền trong suốt

Dự án sẽ phát hiện các vùng trong suốt trong kết quả tạo ảnh. Theo mặc định, khi phát hiện vùng trong suốt, hệ thống sẽ dàn phẳng chúng lên nền trắng; nếu thực sự cần giữ nền trong suốt, bạn có thể sử dụng transparent_background: true. Cách xử lý này nhằm tránh việc một số phần mềm xem ảnh hiển thị vùng trong suốt thành viền đen.

Chỉ định đường dẫn Codex và thời gian chờ

Nếu hệ thống không tìm thấy Codex, bạn có thể chỉ định đường dẫn tệp thực thi thông qua biến môi trường QIAOMU_CODEX_BIN. Khi quá trình tạo ảnh bị hết thời gian chờ, hãy tăng giá trị --timeout hoặc đơn giản hóa mô tả trước:

node scripts/cli.mjs "Bìa sự kiện đọc sách tại quán cà phê" --preset video-cover --timeout 120000

Xây dựng kho ngữ liệu cục bộ

Nếu bạn có thư mục lưu trữ riêng chứa archive.json, prompts/ và images/, bạn có thể thực thi:

node scripts/build-corpus.mjs /path/to/kho-luu-tru-prompt

Thư mục ngữ liệu mặc định là ~/.local/share/qiaomu-codex-imagegen/corpus; bạn cũng có thể dùng QIAOMU_CORPUS_DIR để trỏ đến vị trí khác. Chỉ nên sử dụng kho ngữ liệu trên máy cục bộ, không提交 hoặc chuyển tiếp nội dung của bên thứ ba khi chưa được授权.

Xác minh cài đặt thành công

Dự án cung cấp các lệnh kiểm thử ngoại tuyến và kiểm tra thư mục:

npm test
node scripts/cli.mjs --list
node scripts/cli.mjs "Một hình tròn màu đỏ" --show-prompt

npm test không tiêu tốn hạn mức tạo ảnh, có thể dùng để xác minh việc lắp ráp mẫu, chế độ văn bản, thay thế cấu trúc, tính đa dạng của hướng, truy xuất ngữ liệu, xử lý nền trong suốt và giao thức.

Câu hỏi thường gặp

• cannot start codex: Xác nhận đã cài đặt Codex CLI hoặc thiết lập QIAOMU_CODEX_BIN.
• codex finished without producing an image: Kiểm tra trạng thái đăng nhập Codex và xác nhận tài khoản có quyền tạo ảnh.
• timed out: Tăng thời gian chờ hoặc giảm độ phức tạp của mô tả.
• Tỷ lệ không đúng như mong đợi: Nhấn mạnh lại tỷ lệ trong mô tả hoặc sử dụng --ratio; công cụ sẽ không tự động âm thầm cắt ảnh.
• Không tìm thấy ảnh tham chiếu: Đổi giá trị của --ref thành đường dẫn tuyệt đối.

Lời kết

Điểm cốt lõi của qiaomu-codex-imagegen không chỉ là chuyển tiếp một câu cho mô hình tạo ảnh, mà là tổ chức bối cảnh, phong cách, quan hệ bố cục, cấp bậc văn bản và tiêu chí nghiệm thu thành một quy trình làm việc có thể tái sử dụng. Bạn có thể bắt đầu từ Agent Skill hoặc MCP để Agent phụ trách đề xuất và điều phối; cũng có thể dùng CLI để kiểm soát chính xác preset, phong cách, tỷ lệ, văn bản và ảnh tham chiếu.

Đối với các tác vụ cần tạo ổn định ảnh bìa, áp phích và hình minh họa theo bộ, nên áp dụng quy trình “đề xuất hướng trước, mở rộng prompt sau, nghiệm thu theo điều kiện sau khi tạo”, đồng thời kiểm tra thủ công văn bản trong ảnh và kích thước của các ảnh dùng chính thức.