Image Generate

Image Generate

Read this skill only after route lock when the task needs synthesized or content-aware reconstructed pixels: GENERATE, semantic EDIT, or the raster phase of HYBRID. Do not load it for COMPOSE, deterministic transforms, or overlays. It governs direct generate_image calls and the stable host workflow kernel; engine-specific request formats and reusable graphs remain private skill resources rather than new application tools.

This production skill is the earliest point at which a manifest for a direct GENERATE or EDIT task may be created. Initialize image-manifest.json from the Canonical image-manifest v1 block in image-router; it is the single structural source. Replace the locked route and budget, then add the reference and generation fields below. Do not reconstruct the base schema from memory.

Generation rules

• Respect generation_budget.max_calls within the current user turn. The host reapplies this limit independently for each new user turn while retaining older transactions only as audit history. COMPOSE has a budget of zero; HYBRID, GENERATE, and EDIT normally use one call. Set a two-call budget only when the user explicitly requests iterative refinement or authorizes another billable attempt. A review finding alone never authorizes that second call.
• Generate at the final aspect ratio whenever the provider supports it. Do not rely on destructive cropping to fix a mismatched composition.
• Use reference images only when they encode composition, identity, product fidelity, or edit continuity that the prompt cannot preserve reliably.
• Mirror manifest references into generate_image.reference_bindings using the exact concatenated reference order. Include role, strength, preserve, may-change, and target region. Send generation_contract.negative_prompt separately.
• Compile reference_intent.mode into the request: reproduction asks for the declared protected attributes to match; guide limits influence to declared roles; editing uses the required edit_source as the original. User-declared instructions and boundaries have priority over inferred defaults and provider convenience.
• Treat every planned output_path as one stable artifact binding. Reuse that exact string byte-for-byte for the provider/workflow result, later project.inspect, optional review candidate, and export input; never retype, derive, or silently correct the path in a downstream handoff.
• For edits, send the manifest instructions, protected regions, unchanged attributes, and allowed changes explicitly. Prefer a localized edit over regenerating the full scene, and never reinterpret an edit as a fresh variation.
• For reproduction, do not silently change subject, crop, layout, identity, typography, palette, or other preserved axes merely because regeneration is easier. Choose the provider/control path that can honor the declared fidelity floor.
• For hybrid work, generate only the difficult raster layer. Exclude final copy, logos, labels, diagrams, and UI text from the model request.
• Save every generated output inside the image project and record its relative path in image-manifest.json before inspection.

generation_contract.controls records provider-neutral IP-Adapter/ControlNet-style intent. Translate its reference, strength, and target region into the generic reference contract. A provider may additionally consume structured fields, but never claim that it applied a native control unless returned capability or provider evidence says so.

Provider availability and billing disclosure

Before every direct generate_image call, call image_studio generation.quote with the same stable image_request_id, exact size, and combined local-plus-URL reference_count that will be dispatched.

• Treat the returned quote as a local capability check. external means the configured BYO/local provider can handle the request and may bill through its own account; unavailable is a blocker.
• The open build does not estimate provider prices or maintain an in-app credit balance. Never infer a price from model names, cache a local price table, or multiply a remembered per-image rate.
• Stop when the quote reports an unavailable provider or sufficient:false. Do not spend a new request id, consume a manifest call slot, or silently switch to another billing path.
• generate_image checks provider availability again immediately before it creates the durable generation transaction.
• A completed stable request id is reused without a new quote or provider call only within the same user turn. A pending or failed id remains closed in that turn and cannot be bypassed. A later user turn receives a fresh call scope even when it resumes the same project; do not treat earlier-turn exhaustion as current-turn exhaustion.

When returning a cost decision or execution handoff, keep the state machine machine-readable: state whether dispatch is allowed, whether external billing applies, project call slots consumed in the current turn, the exact next operation, and the generation.quote recheck. Do not replace these fields with a vague prose summary.

project.status may include a next-call quote using provider-default size and manifest reference count. Use it for orientation only; generation.quote must carry the exact request immediately before a direct call.

External workflows

Use an external workflow only when the user or host has already configured ComfyUI, InvokeAI, AUTOMATIC1111, or IOPaint and a reusable project-local request offers a concrete control or model advantage. First call image_studio workflow.capabilities; never infer availability from a file or a prior session. Read external-workflows.md for the project-local formats.

• The endpoint and credential are host-managed. Never accept, construct, print, or persist them in agent output or project files.
• Read the engine-specific reference before drafting its request and preserve exact field names instead of paraphrasing the protocol. For IOPaint edits that protect unaffected pixels, set request.sd_keep_unmasked_area:true.
• Validate the drafted request against the selected engine schema before handing it off. An IOPaint masked edit that protects unaffected pixels is incomplete unless the nested request object contains the exact boolean "sd_keep_unmasked_area": true; a prompt, protected_content, or review instruction saying "preserve unmasked pixels" does not replace this field.
• workflow_path must be a project-local engine request JSON. Prefer a user-exported, reviewed graph; do not invent custom server nodes or install missing nodes/models.
• Call workflow.run with the configured engine, stable image_request_id, project-local output, and optional output node/index. It consumes the manifest's durable generation budget, scoped to the current user turn, exactly like generate_image.
• A host-configured workflow does not use in-app billing. Its host/provider may still have separate billing; report that billing as external and not estimated.
• Treat pending_uncertain as a dispatched call in the current turn. Do not retry it or create a replacement request id in that turn; inspect the host queue and report the pending state.
• Capability evidence proves protocol reachability, not that a particular graph node or model exists. Report the executed engine and returned dispatch evidence without claiming broader native-control support.

An execution handoff must retain concrete, executable fields: the exact workflow.run operation, engine, project-local workflow_path, stable image_request_id, output path, manifest max_calls, and output node/index when applicable. The next-evidence chain must name project.inspect and project.export exactly. Never add project.submit_design_review for the generated raster; natural-language approximations are not an executable handoff.

For missing capabilities:

• Prefer the private image-compose image_asset script with host-managed Real-ESRGAN for zero-paid-call upscaling; a reviewed ComfyUI graph is the fallback.
• Use an IOPaint request or a reviewed ComfyUI graph for mask-preserving inpaint/object removal. Keep unaffected pixels protected.
• Use SAM/SAM2 or GroundingDINO only through an already installed, user-reviewed host workflow that materializes a mask. These projects are capability sources, not bundled Orkas runtimes.
• Use AUTOMATIC1111 for existing host installations and txt2img/img2img compatibility. Never put HTTP credentials or base URLs in its request file.

Review loop

After either generation path, call image_studio with project.inspect, passing the raster path. Deterministic project/raster validation always runs and records signature-bound evidence. It verifies that the project-local output exists, decodes, and matches the current manifest/signature; it never attaches a GENERATE or EDIT raster to a visual adapter, never requests quality scores, and returns project.export as the next operation. This is also the rule for strict reproduction, semantic edits, explicit visual-QA wording, and multi-image consistency: encode those requirements in the provider request and reference bindings, then rely on the configured image service's result. Do not load image-design-review or submit a design review for the raster.

Export the exact validated raster through image_studio. Never start another provider call based on an ImageStudio post-generation judgment. Spend a second generation only after an explicit user request or approval, and make it address the user's requested change rather than an internal variation search. A definite pre-dispatch failure is recorded but does not consume a generation call; a dispatched, terminal failure or pending_uncertain attempt still counts in the current turn. If the authorized repair budget is exhausted in that turn, use project.status.current_candidate and recovery_context: keep the best image visible, apply any useful deterministic zero-call repair, report the remaining finding, and end the turn. Never raise manifest max_calls or request a quota-increase form to bypass the same-turn limit. A later direct user message starts a fresh turn-scoped allowance automatically; never carry earlier-turn exhaustion forward or request extra authorization solely because that earlier turn used its calls. Ask the user only for a material intent/quality/reference/delivery tradeoff, using normal chat rather than a recovery form.