codex-image-service

Codex Image Engineering

The first round must output a per-image engineering plan and request confirmation;
The first round must end at the confirmation request and must absolutely not call any image generation tool;
"Generate directly, don't ask, I'm in a hurry, you decide" in the user's initial request must absolutely not serve as confirmation;
Confirmation can only occur after the user has seen the latest complete plan;
N independent final products must execute at least N independent image generations; a collage, four-panel grid, or mockup generated in one call counts only as 1 preview.
All batch projects must declare the delivery form and composition strategy; when pixel blending is required, generation or composition is prohibited unless the project checklist and algorithm prerequisites pass machine validation. When the user only says "long image" without specifying card-style, continuous mode is the default mode.

Violating any one of these means the task execution failed. There are no exceptions such as "produce one first and then supplement the plan," "just call it once to try," or "execute according to the spirit."

Core Principles

Use Codex native image_gen tools to complete generation or editing, and treat multi-image requirements as an acceptablebatch image engineering, not a single prompt. Long images are only one type; material sets, nine-grid layouts, storyboards, carousels, PPT pages, panoramas, and partial insertions must all choose an engineering workflow according to their respective delivery semantics.

The number of independent final products determines the number of image generations. Four materials require at least four independent generations; a single composite image containing four layouts still counts only as one preview, not four final products.

Task Classification

Classify first; calling image generation tools is prohibited before classification is complete.

Single-Image Task

Execute as a single image only when all of the following conditions are met:

The user explicitly requests "one image," "a single image," or editing one specified image;
There is only one visual purpose and one delivery file;
No split-screen, series consistency, stitching, or set delivery is required.

When the information is complete, generate directly; only supplement necessary information that would change the result.

Batch Project

If any of the following conditions appears, it must be executed as a batch project:

Keywords: a set, a suite, series, batch, multiple images, materials, set images, nine-grid, carousel, card set, long image, WeChat long image, multi-screen, storyboard, comic, infographic, PPT, slides;
The user describes two or more uses, layouts, pages, scenes, or deliverables;
The final product requires stitching, unified cropping, unified naming, a contact sheet, or a collection preview;
Although the quantity is not written, semantics such as "the whole set" or "a set of materials introducing a certain theme" inherently include multiple independent final products.

When the quantity is unclear, proactively propose a reasonable quantity and structure; do not ask "how many do you want" and then wait in place, and even less may you arbitrarily downgrade to one image.

Batch Project Hard Gate

Batch projects must first output a complete plan and wait for the user'sexplicit confirmation. Before confirmation, calling image_genis prohibited, generating a tone-setting image is prohibited, and using a single composite image to probe requirements is prohibited.

Confirmation must occur after the latest complete plan is displayed. In the initial request, "generate directly," "don't ask," "in a hurry," and "you decide" are only efficiency preferences, not confirmation of a plan that has not yet been shown, and cannot bypass the gate. The first-round reply for a batch project may only contain the plan and a confirmation request, and must end the current round before calling any image generation tool.

The plan must list:

Field	Required content
Project goal	Publishing platform, audience, and purpose
Planned quantity	Number of independent final deliverables, excluding preview images
Image-by-image list	Number, filename, image purpose, subject, exact text, aspect ratio
Visual system	Color, typography feel, grid, whitespace, photography or illustration style
Reference relationships	Tone-setting image, shared reference images, previous image reference, or independent generation
Engineering handling	Cropping, stitching, custom grid, naming, contact sheet, final format
Compositing strategy routing	`material-kit` / `grid` / `storyboard` / `carousel` / `document` / `generated-continuous` / `panorama` / `object-blend`
Algorithm plan	Alignment, seams, blending, required masks or layout, dependencies, and failure strategy
Acceptance criteria	Quantity, text, aspect ratio, consistency, and prohibited elements
Seam engineering (required for continuous long images)	Shared elements, direction, color tone, transition safe zones, overlap size, and bridging strategy for adjacent screens

After the complete plan is shown, only user statements such as "confirm," "do it this way," "okay," or "start generating" count as confirmation. Silence, vague feedback, urging, and authorization before the plan is shown cannot be regarded as confirmation. After the user modifies the plan, first update the list, then wait for new explicit confirmation.

If asked "can the image generation tool be called now," as long as the latest plan has not received explicit confirmation after being shown, the answer must be "no."

After confirmation, by default complete the entire batch automatically, avoiding repeated requests for instructions on every image. Only when the user explicitly requests "show me one image's style first" should a second confirmation point be added after the tone-setting image.

State machine

Proceed strictly in order; do not skip steps:

INTAKE: Extract theme, purpose, audience, platform, quantity, aspect ratio, text, reference images, and constraints.
CLASSIFY_DELIVERY: Determine independent assets, deterministic layout, continuous blending, live-action panorama, or mask insertion; a long image is only one of these.
PLAN: Load the corresponding template, establish the image-by-image list, reference relationships, naming, compositing Profile, and post-processing plan.
AWAIT_CONFIRMATION: Show the complete plan; in this state, calling image generation tools is prohibited.
VALIDATE_PROJECT: After confirmation, first fill in composition-project.json and perform machine validation; for continuous long images, then validate the dedicated seam items. If it does not pass, image generation is prohibited.
STYLE_ANCHOR: After the project passes, generate the first independent final deliverable as the tone-setting image, and check style, composition, aspect ratio, and text areas.
BATCH_GENERATE: Generate serially according to reference dependencies; only independent materials with no dependencies may be generated in parallel. For continuous images, pass the actual interface image screen by screen.
VERIFY_ASSETS: Check each image one by one; validate interfaces, layout sources, panorama overlaps, or insertion masks according to the Profile.
ROUTE_COMPOSITION: Combine the user's delivery semantics and real material diagnosis to determine alignment, seam, and blending algorithms; record the routing report.
REWORK: Rework only unqualified images, interfaces, masks, or layouts; do not overturn items that have already passed.
POST_PROCESS: Execute deterministic layout or trusted pixel fusion, and output the algorithm, layout, and seam report.
DELIVER: Reconcile planned quantity, actual quantity, derived artifacts, algorithm report, and failed items.

Native tool invocation rules

Mandatory self-check before invocation

Before each preparation to invoke image_gen , internally judge item by item:

这是批量项目吗？
最新完整规划已经展示吗？
用户是在规划展示之后明确确认的吗？
本次调用只对应清单中的一个独立成品吗？

In a batch project, when any answer is "no", invoking tools is prohibited and you must return to the corresponding state. User urging, saving time, or "let's see the effect first" must not override the self-check result.

Invoke once per independent finished product image_gen.imagegen。
Multi-image continuity must be processed serially; concurrency must not break style consistency.
The first image uses the user reference image or text-to-image to set the tone; subsequent images use the real tone-setting image or the previous result as reference.
For local reference images use referenced_image_paths; for recent conversation images use the minimum necessary num_last_images_to_include; the two must not be mixed.
Each prompt must specify subject, environment, composition, lighting, ratio, purpose, exact text, unified style, and exclusions.
Only the actual results returned by tools count as artifacts; fabricating paths, dimensions, success status, or download addresses is prohibited.
Collection preview images must not be counted toward the finished product quantity. For material sets, independent finished products should be delivered first; preview contact sheets may only serve as additional artifacts.

Engineering processing

When a writable directory and real image paths are available, establish or maintain the following artifact ledger:

<project>/
├── manifest.md
├── source/       # 原始生成结果
├── final/        # 返工通过和后处理后的成品
└── preview/      # 联系表或合集预览，不计入成品数

Use templates/batch-project-manifest.md to record file name, purpose, ratio, reference relationships, and status. For all batch projects copy templates/composition-project.json, specifying Profile, independent assets, and derived deliverables; after confirmation run:

python scripts/adaptive_compositor.py validate-project <composition-project.json>
python scripts/adaptive_compositor.py plan --intent "<用户需求>" --output <routing.json>

Use scripts/assemble_images.pywhen vertical stitching, contact sheets, or deterministic grid layout are needed; use scripts/adaptive_compositor.pyfor advanced image compositing. Scripts only process local images and are not responsible for image generation.

Compositing strategy routing

First select the Profile according to the final delivery semantics, then determine algorithm parameters based on the real images. For complete boundaries see references/composition-routing.md。

material-kit: promotional materials, e-commerce sets, and brand series. Retain all independent finished products, and only derive contact sheets or platform layouts; pixel fusion is prohibited.
grid: nine-grid, magazine collage, and asymmetric grids. Use deterministic layout, without feature alignment.
storyboard: storyboards, comic panels, and storyboards. Preserve order, numbering, and shot boundaries.
carousel / document: carousels, PPT, and infographic pages. Keep pages independent; do not fuse pages into one image.
generated-continuous: generative continuous multi-screen or long images. Use interface passing, translation correction, overlap detection, and multi-band fusion.
panorama: architectural, interior, or landscape real shots. Use feature point matching, RANSAC homography, Graph Cut, and multi-band fusion.
object-blend: cutout insertion or local scene replacement with an explicit mask. Use mask localization and Poisson fusion.

When automatic routing fails, advanced dependencies, masks, matching points, trusted overlap, or inlier ratio are missing, you must stop and rework. Automatic downgrade to hard stitching is prohibited. Homography must not be used for text layout images; optical flow must not stretch faces, products, logos, or architectural hard edges; Poisson must not be executed without a real mask.

WeChat long image

First use templates/wechat-long-image-plan.md to split into 4–8 regular-ratio screens. When the user only says "long image",continuous mode is the default mode; only when the user explicitly requests card style, chapter style, dividers, or independent content blocks may you choose cards。

After the plan is confirmed, copy templates/long-image-project.json to the project directory, fill in all screens and N−1 seams, and update the status to confirmed. Run the following machine validation; when it fails, calling the image generation tool is prohibited:

python scripts/long_image_pipeline.py validate-project <project.json>

Generate and accept each screen one by one, then stitch vertically. It is prohibited to directly ask the model to generate one ultra-long image; besides the stitched image, still keep each split-screen source file.

Hard rules for seams in continuous long images

Continuous narrative, illustration, or photographic long images cannot directly hard-paste independent split screens. Zero-overlap stitching is allowed only when a card-style, chapter-style, or intentionally separated layout is explicitly adopted.

During the planning stage, establish for each adjacent screen aseam contract: the bottom of the previous screen, the top of the next screen, shared transition elements, motion direction, color temperature, brightness, subject scale, overlap amount, and bridging strategy.
Reserve approximately 12%–20% at the top and bottom of each screen as atransition safe zone. In the safe zone, place only blendable textures such as clouds, mist, flames, light dust, fabric bands, and gradient backgrounds; do not place titles, faces, hands, products, hard architectural edges, or key evidence.
The prompt for the next screen must explicitly carry forward the shared elements and direction at the bottom of the previous screen; it must still reference the real tone-setting image or the previous screen's result, and cannot rely only on the same style words.
Each time a screen is generated, immediately use long_image_pipeline.py extract-interface to extract the bottom 12%–20% interface image. When generating the next screen,referenced_image_paths must simultaneously include the previous screen's complete image and that interface image; the prompt must explicitly state that “the top safe zone carries forward the interface image, and key structures must not enter the safe zone.” When the real interface image is missing, generation must not continue.
After the next screen is generated, use long_image_pipeline.py compare-interfaces to compare the bottom of the previous screen with the top of the next screen. When the interface score is below the project threshold, rework only the next screen; do not hand discontinuous images to post-processing for forced rescue.
When unifying proportions or cropping, prioritize protecting the transition safe zone. When cropping would remove the safe zone, truncate shared elements, or change the subject scale, mark that screen as “to be reworked”; do not rely on aggressive cropping and then continue stitching.
For seams of the same texture type, use 8%–15% vertical overlap, translation correction, multi-band blending, and local color matching; use cosine feathering only in explicit lightweight mode. When the scene, space, or shot scale changes significantly, a bridging image with no text and no key subject must be generated or edited; do not conceal it with large-scale blur or crossfade.
After stitching, a 1:1 local preview of each seam must be exported, and horizontal cut lines, ghosting, brightness jumps, texture direction, and structural breaks must be checked one by one.It is prohibited to judge whether a seam passes based only on a thumbnail long image or contact sheet.
Continuous mode uses scripts/assemble_images.py stitch-vertical --mode continuous --project <项目 JSON> --overlap auto --blend multiband --seam-preview <路径> --seam-report <路径>. The script will again validate the project confirmation status, split-screen order, interface files, and seam-by-seam comparison report, then find real overlap and perform multi-band blending.When engineering evidence is missing or no trustworthy overlap region can be found, stitching is prohibited, and the corresponding interface must be reworked.
Card style must explicitly use --mode cards. When the command does not provide --mode , it fails directly; zero-overlap hard stitching is no longer the default behavior.

For detailed fields and execution order, see templates/wechat-long-image-plan.md; for acceptance rules, see templates/quality-gate.md。

Material set images

First use templates/material-kit-plan.md Define each independent finished piece. By default, it is recommended to include the key visual, selling points or services, scene or environment, and call to action; add or remove according to the theme. It is prohibited to replace independent files with desktop mockups, four-grid layouts, or collection displays. When a collection is needed, generate an additional contact sheet only after all independent finished pieces have passed.

Choose the corresponding template according to the industry: editorial and official accounts, e-commerce products, architecture and interiors, fashion and beauty, food and beverages, and culture and tourism. For industry visual language, identity information that must be locked, and derived layouts, see references/industry-playbooks.md. Industry switching cannot just change the background color; composition, materials, lighting, lens, and publishing medium should also be adjusted at the same time.

The default Profile for the material set is material-kit, and the key visual, selling point image, scene image, and call-to-action image are independent deliverables. Only when the user separately requests a nine-grid or collection should gridbe derived; derived images cannot replace or be counted toward the number of independent finished pieces.

Custom grid

Nine-grids, storyboards, magazine collages, and asymmetric grids must first generate and accept all independent source images, and then perform deterministic layout. A grid obtained from a single image generation still counts as only one image and cannot replace independent source images.

Use templates/custom-grid-plan.md to record source images, platform, canvas, layout file, and crop anchors.
Use references/grid-layouts/ presets, or create a project-level JSON layout.
scripts/assemble_images.py custom-grid --layout <json> supports equal grids, row spans and column spans, free pixel coordinates,cover / contain / stretch, crop anchors, rounded corners, and borders.
Products, people, and evidence images are prohibited from using stretch；cover mode must specify the subject anchor.
Output a layout report and check the source, position, cropping method, and order cell by cell.
The same set of independent source images can derive multiple platform layouts; derived grids do not increase the number of independent image generations.

Per-image quality gate

Use templates/quality-gate.md to check:

The subject, image purpose, ratio, and composition match the corresponding checklist item;
Chinese titles and short labels are accurate and readable, with no garbled text or random text;
Characters, products, brand colors, typography feel, grid, and lighting remain consistent;
No watermarks, random brands, irrelevant people, deformed structures, or sensitive information;
The files actually exist, the post-processing results can be opened, and the planned quantity matches the actual quantity.
Every seam of a continuous long image passes 1:1 local acceptance, with no obvious horizontal hard cuts, ghosting, or sudden color tone changes.
The custom grid has no out-of-bounds, accidental overlap, incorrect stretching, or cropping of key content, and the layout report is traceable.
The compositing route is consistent with the user's delivery semantics; the algorithm report records the actual alignment, seams, blending, confidence, and failure strategy.

When text is unqualified, first shorten the text, enlarge the text area, or change it to a text-free base image before reworking. Only redo the failed items.

Delivery format

Batch projects must provide a final reconciliation:

计划数量：N 张独立成品
实际数量：N 张独立成品
后处理：长图 1 张 / 联系表 1 张 / 无
未通过项：无 / 编号与原因
文件清单：编号、用途、实际路径或工具返回结果

When the planned quantity does not equal the actual quantity, completion must not be claimed.

Red lines

Calling the image generation tool only once upon seeing "a set of materials."
Using one four-grid, desktop mockup, or collection effect image to pass off as multiple independent finished pieces.
Starting batch generation without explicit confirmation.
Ending the task after showing only the first tone-setting image.
Not performing per-image acceptance after generation and not checking the planned quantity against the actual quantity.
Concurrently generate images that require continuous consistency in pursuit of speed.
Without extracting interface images from the continuous long image and without comparing interfaces, the independent images are handed to the stitching script.
Omit --mode、--project, seam previews, or seam reports, and rely on script default values for forced stitching.
After automatic overlap detection fails, lower the threshold to force it through, instead of reworking the image interfaces.
Without judging the delivery scenario, invoke the blending algorithm upon seeing multiple images.
Perform meaningless feature matching and pixel blending on materials, nine-grid layouts, storyboards, carousels, or PPT pages.
When advanced algorithms are unavailable or confidence is low, silently fall back to forced stitching.

If any red line appears, stop immediately and return to the correct state.

Security boundaries and handoff

Do not read, save, or display credentials, cookies, tokens, or private configurations.
Do not call external image APIs, and do not run the old version of the image-service client.
Do not publish to WeChat Official Accounts, Xiaohongshu, or other platforms by default.
Publishing to WeChat Official Accounts is handed off to wechat-publisher; video pacing is handed off to ai-video-script; story shot breakdown is handed off to story-to-scenes。

For the request structure, see templates/codex-image-request.md; the batch project template is located at templates/; for the compositing route, see references/composition-routing.md; for scenario details, see references/scene-playbooks.md。