image-batch-runner

Image Batch Runner

Use When

• Persona, concept, or shot inputs already exist and the next step is a hosted image generation or reference-based edit run.
• The output must include local image files plus durable request, response, and manifest records for later QA or video rendering.

Do Not Use When

• The task belongs to ideation, QA, or another released skill listed in the handoff section.
• Required inputs are missing and guessing would change the result.
• Creative classification, model/reference policy, or storyboard logic is still unresolved. Use image-generation first.

Execution Boundary

• Hosted image generation and edits run through the public postplus media create verb and are async. A submit writes the request, response, manifest, generation handle, provider status, and completed artifact metadata (bytes are not auto-downloaded; see the download command below).
• This runner validates and executes resolved requests. It must not make creative strategy, task-classification, or reference-policy decisions.
• A higher-quality default and faster or cheaper model families are available; prefer the default unless the user or upstream brief asks for a specific family, ratio, quality, or resolution. The generated example below shows the default endpoint key.
• Only edit endpoints accept --reference-image (default edit endpoint: image-gpt-image-2-edit). Text endpoints such as image-gpt-image-2-text reject the flag with Unknown option, so any reference-bound generation must target an edit endpoint, not a text endpoint.
• Reference-based edits pass each source image via a repeated --reference-image flag; do not pass local paths as edit references. Upload a local source file with postplus media-file upload --skill image-batch-runner --input-file <file> --mime <image/png|image/jpeg|image/webp> --output <upload.json>, then pass output.mediaReference — a persistent postplus-media:// reference that never expires — as --reference-image. A remote HTTPS URL also works; the server downloads each reference itself, so a plain URL must stay reachable until the submit returns (a URL the server cannot fetch fails the request as a bad request, not a provider fault), while a postplus-media:// reference is exchanged for a fresh signed URL at send time and can be reused indefinitely.
• Save a finished native OpenAI image output to disk with postplus media-file download --reference <output.data.artifacts[0].mediaReference> --output-file <path>. Treat output.data.artifacts[0].mediaReference as the durable download identity. Do not persist or prefer temporary signed output URLs.
• Identifiers and run-local state (assetId, runId, localAssetDir, manifest paths) are minted or derived by the runner — do not supply them. Read them back from the result for the next handoff.

Source And Path

• Ground every request in a benchmark-backed persona lock, concept or shot need, visual constraints, assetPurpose, and sourceBasis.
• Use source files from the active project/client folder first. Do not treat one client directory as the default for all image work.
• Keep internal requests, responses, and manifests under .postplus; keep final user-facing images and manifests in the active asset folder. If no asset folder exists, choose one explicit workspace path.

Review And Handoff

• Before submission, verify persona grounding, asset purpose, source basis, and what must stay fixed versus vary.
• After generation, check realism, benchmark fit, repeatability across videos, copied-creator risk, and ad-like drift.
• If processing is still pending, return the manifest/request paths and the poll command postplus media poll --handle <output.data.id> --output path/to/generation-result.json. Reuse the exact --output path from the initial submit. A completed poll atomically replaces the processing JSON at that path with the completed result; rerun the same command while pending (each invocation waits up to 45s).

Stop Conditions

• Stop when required user intent, source evidence, or owned input artifacts are missing and guessing would change the result.
• If an owned CLI or script command fails, report the exact error and stop. Do not bypass the failure with metadata-only answers, readiness probing, local payload rewrites, fallback providers, or unpublished tools.

Public Command Boundary

• Choose the smallest matching command or workflow from the user input and run it directly.
• Readiness diagnostics: postplus doctor --skill image-batch-runner.
• Poll a pending image job: postplus media poll --handle <output.data.id> --output path/to/generation-result.json. Reuse the initial submit's result path so the completed poll atomically replaces its processing JSON; rerun while pending (each invocation waits up to 45s).
• If an owned CLI or script command fails, report the exact error and stop. Do not bypass the failure with metadata-only answers, readiness probing, local payload rewrites, fallback providers, or unpublished tools.
• Use postplus media schema --json only when you need the full endpoint, flag, and enum contract or are repairing an unknown request shape.
• Run the hosted image job with the generated command below; do not call provider APIs directly.

<!-- BEGIN GENERATED EXECUTION EXAMPLE -->

postplus media create image-gpt-image-2-text \
  --prompt <prompt> \
  --output <result.json>

<!-- END GENERATED EXECUTION EXAMPLE -->

• If the CLI returns a quote-confirmation challenge, run postplus quote confirm --json --challenge-file <challenge.json> and retry with the returned token.