cmm-image-creator

name	cmm-image-creator
description	Use this CMM module when the CMM content factory needs to generate final image assets through Codex native image generation or configured third-party image APIs for WeChat covers, WeChat body illustrations, Xiaohongshu images, Douyin thumbnails, blog covers, and other platform visuals. This module receives visual_plan asset specs or direct image prompts, chooses a provider, calls the bundled image generation scripts when approved, saves prompt/result metadata, and returns generated_asset records for visual-production and publishing. Image content and text must come from the image-generation backend; local resize/crop/pad is allowed only as recorded platform-size normalization.
version	0.1.0

CMM Image Creator

cmm-image-creator is the raw image generation layer inside the CMM content factory.

Ownership & Input Contract

This module owns model scheduling for the whole factory — it is the single place that decides which image model runs. Every platform flow (WeChat, Xiaohongshu, Douyin, blog, video) calls it with the same uniform job contract that describes what to make, never which model:

prompt, size/aspect-ratio, resolution (1K/2K/4K), negative-prompt, seed, input-image, num-images, output-format, output-dir/prefix, and an optional semantic role (cover/illustration/background — a purpose, not a model).

Callers do not pass --provider. It defaults to auto and is an explicit override hatch only (user pins a model, a provider is down, an img2img job needs a specific backend). Upstream flows never set it. Full contract and per-provider parameter mapping: references/provider-policy.md.

Use This For

• WeChat cover images and body illustrations.
• Background art, metaphors, or spot illustrations for Xiaohongshu card sets.
• Blog/social covers and platform thumbnails.
• Image-to-image generation when a reference image is supplied.
• Prompt-only packages when no provider is configured or cost is unclear.

Boundaries

• Do not generate paid/API images unless the user approved generation in the current turn.
• Default provider selection is host-native first. In Codex, use the Codex native image generation tool by default when it is available. Use bundled third-party providers only when the host-native tool is unavailable, the user explicitly pins a third-party provider, or the host-native result fails a required quality/ratio/text gate. Record the fallback reason in visual_package.post_render_report.
• Do not store API keys, tokens, or provider secrets in outputs.
• Text is always rendered by the model (--text-policy allow). Capable models render clean Chinese and integrated text looks better; verify the output text by eye. --text-policy no-text is disabled — it is ignored and falls back to allow; the textless-background + deterministic-overlay path (render_cover_title.py) is no longer used (see references/provider-policy.md). Do not repair image content or text with local drawing, text overlays, deterministic renderers, screenshot edits, or manual bitmap painting. For character-exact / editable / series-consistent text, lock the text before generation, generate with allow-text, verify by eye, and regenerate through the image model if it is wrong. Local resize/crop/pad is allowed only for platform-size normalization and must be recorded.
• Do not publish or upload generated assets to platforms.

生图前置确认门（硬规则 · 所有平台、所有带文字的图）

生成任何图片前，必须先与用户确认「文案三件套」，确认通过才调用生图工具或第三方脚本。 文案没定就生图 = 文案一改、图就白生成（图片是最贵、最慢的产出）。三件套：

1. 标题 — 贴文/文章标题；
2. 正文文案 — 至少定稿到不会再大改；
3. 图上要印的文字 — 封面/卡片标题等会被「烤进」图里的逐字文案（错一字、改一字 → 整张图作废重生）。

执行：先把这三件套单独发给用户过目 → 用户 OK → 才生图。严禁把「写文案」和「生图」挤在同一步先斩后奏（X / 微博 / 小绿书都犯过这个错）。 唯一例外：用户当轮明确说「直接生 / 不用确认」。 适用范围：封面、卡片、信息图、任何把文字渲进画面的图都受此门约束。（no-text 无字底图路径已禁用，文字一律由模型直接渲染，因此基本所有图都含文字、都受此门约束。）

Workflow

1. Receive either a visual_plan.required_assets[] item or a direct prompt.
2. Resolve platform defaults with references/provider-policy.md.
3. Build a final prompt file and choose provider through references/provider-policy.md:
   • Tier 1: host-native image generation when available. In Codex, this means Codex native image generation is the default.
   • Tier 2: bundled third-party fallback via scripts/generate-image.sh only when Tier 1 is unavailable, explicitly overridden by the user, or fails a required quality gate.
   • Tier 2 fallback order: nano-banana → gpt-image2 → siliconflow-qwen-image → openai → prompt_only.
4. For third-party APIs only, run scripts/check-config.sh before generation. Keys are read from ~/.cmm/.env, ~/.cmm-content-factory/.env, or ~/.config/cmm-content-factory/.env. Read references/prompt-construction.md for the prompt formula, prompt-file requirement, asset naming, retry/downgrade rules, and the handoff loop back into illustration_map / typesetting blocks.
5. Save generated images, raw response JSON, and prompt files under the run output directory.
6. Return generated_asset[] records for visual_package.asset_paths.

Script Usage

Check local third-party config without calling image APIs:

{baseDir}/scripts/check-config.sh

Generate a single image with the bundled third-party fallback chain. Do not use this path inside Codex when the native image generation tool is available and approved for the job:

{baseDir}/scripts/generate-image.sh \
  --provider auto \
  --prompt "cover image prompt" \
  --size 1536x1024 \
  --output-dir outputs/cmm-content-factory/<run>/images \
  --output-prefix wechat_cover

GPT-image2 provider:

{baseDir}/scripts/generate-image.sh \
  --provider gpt-image2 \
  --prompt "cover image prompt" \
  --size 1536x1024 \
  --output-dir outputs/cmm-content-factory/<run>/images \
  --output-prefix gpt_image2_01

Nano Banana-compatible provider:

{baseDir}/scripts/generate-image.sh \
  --provider nano-banana \
  --prompt "illustration prompt" \
  --aspect-ratio 3:4 \
  --output-dir outputs/cmm-content-factory/<run>/images \
  --output-prefix xhs_background_01

SiliconFlow Qwen Image:

{baseDir}/scripts/generate-image.sh \
  --provider siliconflow-qwen-image \
  --prompt "illustration prompt" \
  --size 1024x1024 \
  --output-dir outputs/cmm-content-factory/<run>/images \
  --output-prefix qwen_image_01

Reference image:

{baseDir}/scripts/generate-image.sh \
  --provider openai \
  --input-image /absolute/path/reference.png \
  --prompt "preserve the referenced product identity, change the scene only" \
  --size 1024x1024 \
  --output-dir outputs/cmm-content-factory/<run>/images

Cross-platform asset handling

Local canvas refit, resize, crop, or padding is allowed only as a technical platform-size normalization step after image generation. It must preserve the generated image content and text, must not add overlays or painted content, and must be recorded with input path, output path, target size, mode, and review status. If the target platform needs different content, different text, or a different semantic composition, create a new approved image-generation job.

Output Contract

generated_assets:
  - asset_id: ""
    platform: wechat
    asset_type: cover
    role: raw_generated_image
    provider: openai
    model: ""
    prompt_path: ""
    image_paths: []
    raw_response_path: ""
    source_refs: []
    status: success
    notes: ""

Read references/provider-policy.md for provider order, environment variables, platform sizing, and text/card rules.