sub2api-gpt-image

name

sub2api-gpt-image

description

Generate and edit images through a sub2api-backed OpenAI-compatible GPT Image provider. Supports Responses API streaming image generation, GPT Image text-to-image generation, image editing with one or more reference images, optional alpha masks, JSONL batch generation, prompt files, quality/size/output-format controls, dry runs, provider diagnostics, model listing, dependency bootstrap, run logs, and project output paths.

Sub2API GPT Image

Use this skill when the user wants AI image generation or image editing through the current Codex MyOpenAI / sub2api-compatible GPT Image provider instead of manual image editing or an unrelated provider.

Core Rules

Provider and execution:

• Do not use an unrelated image provider unless the user explicitly asks for it.
• Do not use local/manual image editing to change image content unless the user explicitly asks for manual editing, compositing, masking, or post-processing.
• Never print, commit, or store real API keys in project files.
• Prefer the current Codex provider from ~/.codex/config.toml; default provider is usually MyOpenAI.
• Prefer the API key already stored in ~/.codex/auth.json or OPENAI_API_KEY; do not create project .env key files.
• Use the bundled wrapper script instead of rewriting API callers.
• Save project-bound outputs into the workspace with versioned names.
• Treat sub2api-style relays as compatibility layers, not identical backends. Verify the active relay with doctor, dry-runs, logs, and one small real test before assuming full feature support.
• If a relay path or parameter fails for compatibility reasons, explain the change before switching between /responses and /images. Read references/usage.md for the detailed relay triage checklist.

Reference identity and prompting:

• For reference images, label each image's role in the prompt and pass --image-role for each --image when more than one image is used. The wrapper injects an input identity binding into the edit prompt so Image 1, Image 2, and later references are tied to ordered file paths and roles.
• Treat image identity binding as text-level instruction, not hidden API metadata. If a task is highly sensitive to reference identity, keep reference count low and make the prompt repeat which image controls layout, object shape, style, or geometry.
• For image-model placement, replacement, and preservation instructions, prefer semantic visual anchors over raw numeric coordinates. Use wording based on existing visible objects, regions, silhouettes, relative positions, and "replace in place"; keep numeric coordinates for local planning artifacts, masks/guides, deterministic overlays, metadata, or text to be drawn, not as the primary provider prompt.
• Before writing an edit prompt from reference images, do not rely only on file names, memory, or abstract roles. Inspect the relevant reference images, or use a worker-provided observation summary when media isolation applies, and extract the specific visible traits that may be inherited and the traits that must not be inherited.
• Before editing an image from user feedback, restate the user's goal in actionable terms and add your own interpretation of what changes, what stays fixed, and any ambiguity. Use this semantic alignment step before writing the next prompt so the user can correct misunderstandings early.
• For overlay-only edits where the base subject must not move, duplicate, or be repainted, read references/prompting.md and use the UI-only / overlay-only prompt pattern before calling the provider.

Media isolation and review:

• responses-edit and responses-edit-batch dry-runs perform input preflight for --image files and may inspect dimensions or create auto-resized transport copies. In workflows that use media isolation, run those image-input dry-runs in the isolated worker path, not in the main session.
• When the user points out an image problem or asks why an output is wrong, reopen and inspect the current output plus the relevant base/reference image(s) before diagnosing it. Tell the user the concrete visual issue observed, then revise the prompt or run the next edit. Do not judge image failures from memory or assumption.
• After generation or editing, review outputs in this order: user intent, base-image preservation, reference-role obedience, requested new content, global coherence, then visual polish. Do not call an output successful just because the new overlay/content looks better if the authoritative base lost objects, regions, background structures, paths, labels, relationships, or other required existing content.
• For base-image edits, explicitly compare the output against the authoritative base before comparing candidate style. Check all task-relevant object groups, area groups, links/paths, overlays, text, and scene structures that should remain fixed. Missing, replaced, moved, resized, reshaped, reoriented, or reinterpreted base content is a hard failure unless the user requested that change.

Output, size, and masks:

• Treat actual output-size mismatch as an execution failure, not as a usable candidate. The wrapper checks generated PNG dimensions after writing for Responses and delegated Images API runs; if the provider returns a different size than requested, classify it as provider/output-size mismatch and change strategy instead of silently accepting or locally upscaling it.
• If repeated valid size requests return a smaller same-aspect output, tell the user this may be an upstream compatibility/channel limit rather than a local wrapper bug. In sub2api-style relays, the request size and actual image output size may be logged separately, and OAuth/bridge routes may accept size while the upstream product channel returns a fixed bucket such as a reduced 16:9 image. Continue to postflight actual files and do not claim native high resolution unless the returned file really has it.
• When relay behavior suggests API --size is ignored, filtered, or mapped to hidden output buckets, put the desired canvas intent in both places: command parameters and prompt text. Add a short API-style prompt block with size, width, height, aspect_ratio, quality, and output_format, plus natural language that the composition must fit that canvas. Treat this as an aspect/bucket steering signal, not an exact-pixel guarantee.
• For local edits with a clear bounded region, consider a mask after semantic alignment and planning. Masks are precision tools, not a default: use them when the edit target is localized and the boundary can be represented clearly. The mask must be an RGBA PNG matching the actual first edit-target image sent to the provider; transparent pixels are editable and opaque pixels are preserved.

Files

• Wrapper script: scripts/sub2api_gpt_image.py
• Main implementation: scripts/sub2api_gpt_image_main.py
• Saved non-secret defaults: config.json
• Usage reference: references/usage.md
• Prompting reference: references/prompting.md
• Prompt template library: references/prompt-template-library.md
• Raw prompt catalog index: references/raw-prompt-catalog/index.md
• Official OpenAI image docs reference: references/openai-image-docs.md

Read references/usage.md when command details are needed. Read references/prompting.md when preparing complex image prompts or edits, especially overlay-only edits, subject-preservation edits, small-object edits, or UI/HUD overlays. Read references/prompt-template-library.md when drafting a non-trivial prompt that needs a reusable structure, such as complex layout, product, infographic, UI/HUD, storyboard, map, typography, or preservation-sensitive edits; then read only the matched file under references/prompt-templates/. Read references/raw-prompt-catalog/index.md when the task benefits from real-world source prompts or when the user asks for original prompt templates; then open only the relevant category file or entry. Read references/openai-image-docs.md before changing official-size, input, fidelity, mask, background, or output-format rules.

Project Companion Brief

Before project-bound image work, look for a project companion brief named IMAGE_PROJECT_BRIEF.md in the current workspace root. If project instructions name a different companion brief path, use that path instead. If no brief exists and the task is likely to repeat or needs project-specific visual memory, create a concise root-level brief before or after the first run.

Use the companion brief for project-specific style rules, durable user preferences, accepted asset indexes, reference roles, continuity constraints, failure patterns, candidate lessons, and workflow decisions. Keep this information out of the reusable skill. During each image task, read the brief before prompt planning and update it only with reusable lessons, not temporary candidate clutter.

Reference Observation Before Prompting

For any non-trivial edit with one or more reference images, create a concise reference observation summary before writing the final prompt. This is a hard gate: do not write the final prompt, run dry-run with image inputs, or call the provider until the summary exists and covers every reference that can affect the output. If the workflow uses media isolation, the observation must be produced inside the isolated worker and returned as text; the main session should not load the images directly unless explicitly authorized.

The summary should state, for each input:

• role: edit target, structure/layout, object shape, style, color/material, text/UI, geometry guide, or other specific role.
• observed content: the concrete visible objects, regions, UI components, layout, colors, line styles, text, or material traits relevant to the task.
• allowed inheritance: the exact traits the output may inherit from that image.
• forbidden inheritance: what must not be copied, such as layout, object count, positions, camera angle, background, panel placement, labels, colors, or failed artifacts.
• priority: what wins if this image conflicts with another reference.

Do not write a prompt that says only “use this as style reference” or “refer to Image 2” when the relevant traits are visually specific. Convert the observation into concrete prompt language, such as line color, panel hierarchy, object placement authority, forbidden layout inheritance, or fixed subject positions.

When the user supplies their own precise description of a reference image, use it as the primary observation, but still inspect or request worker inspection when object identity, small details, layout, or preservation risk matters.

If any reference image is added, removed, replaced, promoted from output to style reference, or disputed by the user, refresh the observation summary for the affected references before revising the prompt. A prior observation remains valid only for the same image, same role, and same task-relevant traits.

Before a provider worker runs a multi-image edit, it should check that the prompt was derived from a current observation summary, not only from filenames, prior prompts, logs, or memory. If that provenance is missing for a fragile edit, stop and request the missing observation instead of proceeding.

Efficient Iteration Patterns

Use these patterns when a task may require repeated edits, multiple references, or candidate comparison. Keep them brief; they are meant to reduce retries, not add paperwork.

• Reference note cache: when the same references will be reused, keep a lightweight project note with each path/link, role, observed traits, allowed inheritance, forbidden inheritance, priority, and when it was last verified. Refresh the note when a source changes or the user disputes an observation. Do not store bulky derived media in the main conversation.
• Candidate matrix: before multi-candidate generation, state what each variant tests, which prompt lever changes, which constraints stay fixed, and what pass/fail signal will decide the next branch. Avoid near-duplicate candidates.
• Low-cost preflight: before provider calls, verify output size, quality, reasoning setting, reference order, --image-role labels, identity manifest, confirmation gates, and prompt conflicts. In media-isolated workflows, do not run image-decoding preflight in the main session.
• Fixed review template: review candidates by base preservation, subject fidelity, reference-role obedience, requested edit quality, side effects, then conclusion. If any required item is uncertain, do not mark it as pass.
• Failure classification: classify failures as prompt ambiguity, reference-role leakage, identity binding, overlay/layout overload, subject repaint, base loss, text/OCR issue, parameter/transport issue, provider runtime issue, or model limitation. Change one major lever per retry; if the same class repeats, change strategy instead of blindly regenerating.
• Semantic anchor retry: if coordinate-heavy prompts repeatedly move, duplicate, or miss an object, simplify the next prompt around visible semantic anchors: identify the existing object or region in the image, replace/refine it in place, preserve surrounding context, and use any numeric coordinates only through a guide/mask/metadata artifact.
• Surgical local edit: for local object insertion, replacement, or small-target edits, write prompts like a production edit brief. State the edit target as the background authority, list positive invariants first, allow only the small edit, and use narrow negatives. Avoid broad negatives that can delete accepted base elements; forbid only the new unwanted elements while explicitly preserving existing base overlays or details. If two broad-crop text-only attempts repeat position, count, or base-preservation failures, switch to a smaller crop, mask, or visual guide instead of adding more text.
• Clean-base additive edit: when an accepted image contains old targets, labels, panels, or overlays that conflict with a new scene state, first create a clean edit target by removing only the obsolete elements while preserving all accepted background and non-target overlays. Then generate the new state from that clean base with a minimal reference set: clean base as pixel/layout authority, previous accepted frame only as continuity/style reference, and object asset only as morphology/count reference. Convert local crop lessons into semantic prompt anchors instead of adding every crop as a provider input when the crop may import old layout, scale, or UI.
• Durable lessons: record reusable lessons in the project/workflow notes when they affect later prompts or asset strategy. Keep one-off file paths, temporary candidate names, and project-specific decisions out of this reusable skill.

Image Fidelity Optimization

For complex multi-frame work, continuity edits, small objects, repeated assets, overlays, or any task where object count, shape, topology, layout, or continuity matters, prefer a multi-scale fidelity workflow:

1. Use a low-resolution full-frame reference only for composition, camera, lighting, scene layout, broad geometry, thin graphic placement, and frame-to-frame continuity.
2. Use high-resolution local crops for placement, scale, pose, occlusion, lighting, and surrounding context. Use them as detail sources only when the crop itself is clean enough.
3. If the local crop is already blurry, smeared, malformed, or low quality, treat it only as a placement/context reference. Do not ask the model to inherit its degraded details.
4. Use validated object references or newly generated clean local assets to lock morphology, count, silhouette, direction, and role. Do not rely on a downsampled full-frame reference or a degraded crop to preserve small-object detail.
5. Prefer local repair or narrowly scoped image edits once the overall composition is acceptable. Avoid repeated full-frame regeneration when the problem is limited to a small object or region.
6. Keep reference sets minimal and role-labeled. Too many broad references can leak unrelated objects, duplicate targets, change counts, or smear details.
7. Treat masks as optional precision tools, not the default. Use a mask only when the edit boundary is simple and either the user has confirmed the planning artifact or the workflow already authorizes it.
8. For first-pass exploration of complex visual concepts, generate a small number of broad candidates. After selecting a direction, switch to crop/master-guided local refinement.
9. Do not downsample every input image by default. Official processing guidance supports a 2048px long-edge guard for high-detail input handling; preserve images at or below that guard and prepare a transport copy only when an input exceeds it.
10. Prepare additional input copies only for transport, cost, consistency, troubleshooting, or explicit user request. If a source image is already clean and within the input guard, preserve it instead of automatically downscaling it.
11. Prefer official/common output sizes for standard aspect ratios before inventing custom dimensions. Use a square-canvas stabilization pass only when the requested aspect ratio is not covered by the preferred-size map, or when the preferred non-square size repeatedly times out or behaves unstably.
12. In a square-canvas stabilization pass, place the intended aspect-ratio frame inside a 1:1 canvas, keep unused areas as simple black or white padding, and ask the model to refine only the central content band without expanding content into the padding.
13. Treat square-canvas padding as a practical constraint, not a guaranteed mask. It improves execution stability and often preserves the central frame, but high-resolution runs can still create minor edge bleed or glow near padding boundaries; visually review outputs before relying on padding as untouched.

Default reference pattern for high-fidelity edits:

• image 1: full scene or accepted candidate for global layout only.
• image 2: local crop from the exact region to repair, used for placement and local context.
• image 3+: validated object reference(s) or clean local asset(s) used for object morphology and detail.

This is a conditional default, not a mandatory input list: include image 2 only when the crop is clean or authoritative enough to help. If a clean full-frame edit target should remain authoritative and the crop carries stale UI, failed content, wrong scale, or crop-only framing, omit the crop and translate its lesson into semantic anchors.

Preferred output-size map:

• All output sizes must still satisfy the provider/model constraints: dimensions aligned to the required increment, aspect ratio within supported limits, and total pixels within the current model limits.
• Official/common gpt-image-2 output sizes to prefer: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 2048x1152, 3840x2160, 2160x3840, or auto.
• 1:1: use 1024x1024 for drafts and stable edits; use 2048x2048 for higher-detail square outputs; use larger square sizes only as experimental runs within provider limits.
• 3:2: use 1536x1024.
• 2:3: use 1024x1536.
• 16:9: use 2048x1152 as the normal wide output; use 3840x2160 only when a high-resolution run is necessary and acceptable as slower or more experimental. For faster or fragile edits, use 1024x1024 or a 1:1 square-canvas pass first.
• 9:16: use 2160x3840 only when a vertical high-resolution run is necessary and acceptable as slower or more experimental; otherwise use a square-canvas pass or a provider-valid custom size after testing.
• auto: use only when exact dimensions are not important and the provider may choose the output size.

When a user asks for an output size or exact resolution that is not in the preferred map, do not silently force that size. First tell the user the closest skill-matched recommendation, such as a preferred common size with the same or nearest aspect ratio, or a square-canvas stabilization pass for unsupported ratios. Also state the risk of forcing the requested non-recommended size: provider rejection, slower generation, hard timeout, output-size mismatch, unstable composition, padding/edge artifacts, or reduced instruction following. Proceed with the original non-recommended size only if the user explicitly confirms that exact size is required, or if the request is a low-risk dry-run/diagnostic that does not call the provider. If the user accepts the recommendation, run the recommended size and record that decision in the prompt, output path, and run log. If the user insists on the original size, keep that exact size visible in the command and run log so later troubleshooting can distinguish deliberate size risk from accidental parameter drift.

The wrapper blocks real provider calls that use a provider-valid but non-preferred standard-ratio output size unless the wrapper option --allow-nonpreferred-size is present. Treat that option as an explicit risk acknowledgment, not a convenience default. Do not add it to routine project commands just to bypass the guard; prefer the mapped size or ask the user to confirm the non-preferred size.

For aspect ratios not covered above, do not invent a custom size as the default. Prefer a 1:1 square-canvas pass that embeds the desired frame proportion, then crop or post-process only if the user or workflow explicitly authorizes that final delivery step.

Input-image preparation policy:

• Prefer original clean references when fidelity, small objects, texture, or exact morphology matters and the image is within the input-size guard.
• Default Responses edit input guard is input_max_dim=2048. Images at or below that long edge are sent unchanged; oversized images get automatic transport copies under the skill output directory before upload.
• Use prepare-edit-inputs manually only when the provider has transport/gateway problems, the request has too many large references, a low-cost diagnostic pass is needed, or the user explicitly asks for smaller prepared copies.
• Prepared copies are not authoritative sources. They should not replace clean source files or validated references in the workflow record.
• If an output looks smeared after using prepared copies, suspect reference degradation first and retry with fewer, cleaner, or higher-quality source references before changing the visual concept.

Default square-canvas pattern for non-recommended or unstable non-square edits:

• Embed 16:9 content as a centered band inside a 1:1 canvas, for example 1024x576 inside 1024x1024, or 1920x1080 inside 1920x1920.
• Embed 4:3 content as a centered band inside a 1:1 canvas, for example 1024x768 inside 1024x1024.
• Use plain black padding by default when the padding is diagnostic or should visually separate from the content; use white only when it better matches the surrounding deliverable.
• Prompt clearly: preserve/refine only the central content band, keep padding empty, do not extend the scene into padding, and do not add text, panels, borders, gradients, labels, or decorative marks in padding.
• Start with 1024x1024 for feasibility. Move to larger square sizes only after a stable pass and keep event logs enabled.

Prompts should state which references control layout, which control placement/context, and which control object morphology. If a generated image becomes smeared or repeatedly changes fixed objects, stop broad regeneration and move to reference-led local repair or generate a clean local asset first.

Output Review Protocol

Use this protocol for every non-trivial image edit, especially multi-reference edits, overlays, small objects, continuity frames, technical visualizations, and candidate comparisons.

1. User intent first: restate what the user asked to change, what they asked to keep, and the latest correction they emphasized.
2. Base preservation second: if an input is the edit target, base image, authoritative scene, or structure lock, compare the output against it before judging the new content. Verify required existing objects, object groups, areas, paths, links, labels, overlays, background structures, and spatial relationships still exist and remain recognizable.
3. Reference role obedience: check whether each reference affected only its assigned role. A style reference must not change layout, count, placement, geometry, or base content unless explicitly authorized.
4. Requested edit quality: inspect the new or changed content for count, identity binding, placement, occlusion, text, line routing, visual hierarchy, and consistency with the requested style.
5. Global side effects: look for unintended deletions, duplicated objects, smeared details, altered scene logic, shifted composition, broken continuity, or cleaner-looking results that achieved cleanliness by removing required content.
6. Aesthetic ranking last: rank candidates only after preservation and correctness pass. A cleaner candidate with missing base content is not a better candidate; it is a failed candidate with a useful direction at most.

For candidate reviews, report failures before positives. Separate:

• observed: directly visible differences or confirmations.
• inferred: likely causes or prompt/reference effects.
• unchecked: items not verified, such as OCR-level text or pixel-level identity.

Do not treat uncertain as pass. When a user points out a missed visual problem, re-run a narrower review centered on that claim and expand the future checklist to include that category.

For overlay-only or preservation-sensitive edits, base preservation must include subject fidelity, not just subject presence:

• presence: the subject or group is still visible.
• count: the number of repeated subjects is unchanged.
• identity: the subject still appears to be the original subject, not a regenerated lookalike.
• position: the subject remains in the original area and does not drift.
• silhouette: outline, pose, orientation, scale, and distinctive shape remain stable.
• topology: relative spacing, ordering, overlap, and links between subjects remain stable.
• pixel authority: the model appears to have added overlays around the subject rather than repainting the subject itself.
• overlay boundary: UI, labels, glow, panels, or lines stay outside the subject unless explicitly requested.

If a subject is present but moved, resized, reshaped, rotated, visually reinterpreted, or made clearer by repainting, report it as a preservation failure rather than a pass.

Reasoning Effort Policy

• Do not enable --reasoning-effort by default for routine image generation or simple edits.
• Use --reasoning-effort medium only when the edit is complex enough to benefit from extra planning, such as multi-reference edits, strict layout preservation, object-count constraints, dense overlays, or difficult instruction-following. Before using it, tell the user it may increase latency and timeout risk.
• Prefer --reasoning-effort medium with stable practical sizes such as 1024x1024 or 2048x1152. Avoid combining it by default with very large square outputs, many references, high quality, or already unstable requests. For 2048x2048 or larger edits, use medium reasoning only after user approval, a successful smaller pass, or a clear diagnostic reason.
• Do not use --reasoning-effort high by default. Treat it as experimental unless a user explicitly asks for it and accepts the provider/gateway risk.
• If a medium-reasoning run times out after provider stream events, classify it as provider-accepted-then-timeout. Do not assume prompt safety or content failure; reduce size/reference count, disable reasoning, or increase --max-wait only with user approval.

Standard Workflow

1. On first use, configure non-secret defaults before generation:
   • Run python3 skills/sub2api-gpt-image/scripts/sub2api_gpt_image.py configure --show to read option meanings.
   • Run python3 skills/sub2api-gpt-image/scripts/sub2api_gpt_image.py configure --defaults to save recommended defaults.
   • Recommended defaults are quality=medium, size=1024x1024, image_model=gpt-image-2, responses_model=gpt-5.5, retries=1, max_wait=600.
   • For Responses image generation/editing, keep responses_model and image_model distinct: --model selects the main Responses model, while --image-model selects the GPT Image model used by the image_generation tool.
   • Default workspace output directory is outputs/sub2api-gpt-image; generation/edit commands auto-create timestamped outputs there when --out is omitted.
   • Default confirmation mode is stored in config.json; use configure --show to verify whether it is ask or auto.
   • The config file never stores API keys.
2. Decide the operation:
   • Prefer responses-generate for text-to-image and responses-edit for image edits when streaming keepalive events are useful.
   • Use responses-edit --mask <mask.png> for localized edits when a confirmed or reliable mask exists.
   • Use create-mask to convert simple local planning regions into an API-compliant RGBA PNG mask.
   • Use responses-edit-batch, review-batch, and rerun-failed for multi-variant workflows.
   • Use prepare-edit-inputs only for diagnostics or explicit preparation; normal responses-edit already enforces the default input guard.
   • Use doctor, models, and bootstrap for environment diagnosis and setup.
   • Read references/usage.md for exact command syntax and less common commands.
3. Before any real provider call, make the execution decisions explicit:
   • Output size: preferred map, square-canvas pass, or user-confirmed non-recommended size.
   • Prompt-level size steering: when exact API size obedience is suspect, mirror the requested size, aspect ratio, quality, and output format inside the prompt as an API-style block and natural language canvas instruction.
   • Prompt template: for non-trivial prompt drafting, choose one primary template ID from references/prompt-template-library.md before writing the final prompt. Then load only the matched references/prompt-templates/*.md file unless the task spans multiple visual formats.
   • Raw prompt examples: if using original examples, search references/raw-prompt-catalog/index.md first, then open only the matched category file. Treat raw prompts as examples to adapt with attribution, not as automatic copy/paste defaults. Do not load or embed generated example images; use links only.
   • Image tool model: confirm --image-model is visible in the dry-run, confirmation payload, run log, or events log; unexpected output-size behavior can be caused by an omitted or provider-defaulted image tool model.
   • Input handling: original references within input_max_dim, automatic transport copies for oversized inputs, or manual preparation for diagnostics only.
   • Image identity: for multiple images, each --image has a role from --image-role or a default role; verify the dry-run image_identity_manifest before provider calls when role confusion would be costly.
   • Reference observation: for non-trivial reference edits, identify the observed traits, allowed inheritance, forbidden inheritance, and priority for each reference before final prompt writing.
   • Prompt provenance: for fragile multi-reference edits, verify the final prompt was derived from a current reference observation summary. If not, stop before image-input dry-run or provider calls and create or request that summary.
   • Mask provenance: if using --mask, verify which first input image it targets, whether it was generated from a user-confirmed planning artifact or a reliable local region, and whether dry-run shows the mask matches the actual uploaded target dimensions.
   • Reasoning effort: off by default, medium only for justified complex edits, high only by explicit user choice.
   • Confirmation: if parameters changed from the user's exact wording, or if a risky size/reasoning choice is involved, state the selected command-level choices before running.
4. Write or update a prompt file for project work. For complex continuity or small-object fidelity, apply the multi-scale fidelity workflow before choosing references.
5. Run diagnostics if the environment is uncertain. Read references/usage.md for full diagnostic commands.

python3 skills/sub2api-gpt-image/scripts/sub2api_gpt_image.py doctor

6. For text-to-image work on this provider, prefer Responses streaming generation:

python3 skills/sub2api-gpt-image/scripts/sub2api_gpt_image.py responses-generate \
  --prompt-file <prompt.md> \
  --size 1024x1024 \
  --quality medium \
  --out <output.png>

7. Use the Image API path only when explicitly needing /images/* behavior or diagnosing Responses issues:

python3 skills/sub2api-gpt-image/scripts/sub2api_gpt_image.py edit \
  --image <input.png> \
  --prompt-file <prompt.md> \
  --size 2048x1152 \
  --quality high \
  --output-format png \
  --out <output.png>

8. If network/DNS fails in a sandboxed environment, rerun the same command with network permission.
9. Inspect the generated image before judging success.
10. If the image misses constraints, revise the prompt and regenerate with one targeted change.

Execution Notes

• The wrapper supports /responses streaming generation/editing and delegated /images/* commands. Use /responses when long runtimes need keepalive events and run logs.
• Responses generation/editing sends model inside the image_generation tool from --image-model / image_model; do not rely on a provider default when exact size or model behavior matters.
• Single-command options override saved defaults. --out, --out-dir, and --log should be explicit for project work.
• Real provider calls may require confirmation. If a confirmation payload appears, do not generate until the user chooses yes, another, no, or auto.
• Do not request partial images by default. Some providers emit partial-image events unexpectedly; ignore them unless --with-partial-images is explicitly needed.
• Do not force tool_choice for responses-edit by default.
• Omit input_fidelity for gpt-image-2 unless official docs or provider behavior changes.
• For batch edits, start with quality=medium and moderate concurrency such as 2; use high only for selected follow-up variants or with concurrency=1.

Troubleshooting Loop

Classify failures before changing prompts:

• pre-provider: DNS, connection, auth, base URL, sandbox, SDK, or confirmation problems. Fix execution first.
• provider-accepted: stream events or request IDs show the backend accepted the job. Treat later timeout or no-output as provider/runtime behavior, not prompt safety by default.
• hard-timeout: wrapper return code 124. Inspect the .events.log, then reduce size/reference count, disable reasoning, or increase --max-wait only with user approval.
• provider-rejected: 4xx/5xx or explicit unsupported parameter. Check references/openai-image-docs.md, then adjust size, quality, input fidelity, mask, endpoint, or API path.
• provider-capability-mismatch: one endpoint, parameter, model alias, mask mode, multi-image mode, or stream format is unsupported by the relay even though other provider calls work. Reduce to a minimum reproducible test and switch paths only after explaining the change.
• completed-but-wrong: inspect the output and references before revising; make one targeted prompt or reference change.
• completed-output-size-mismatch: the provider returned image data, but actual dimensions do not equal the requested --size. Treat the run as failed or partial; do not accept the image as a size-locked deliverable, and do not hide the mismatch with local upscaling unless the user explicitly asks for a separate post-processing artifact.

Do not retry image edits automatically after Cloudflare/gateway timeouts, hard timeouts, or provider errors unless the user approves the retry or the current workflow explicitly authorizes reruns.