image-batch-runner

name	image-batch-runner
description	Run fact-grounded image generation batches for short-form video production, especially persona images, first-frame candidates, and light consistency edits. Use this when persona and concept inputs already exist and you need local image assets, prompt records, and reusable model-call metadata. This skill should stay anchored to benchmark-backed persona locks and should save both raw provider responses and normalized local asset manifests.
metadata	{"postplus":{"familyId":"media-production","familyName":"Media and Creative Production"}}

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.
• Batch canary: before fanning out a batch of independent items, submit item 1 alone and poll it to a terminal state. If the canary is content-policy blocked (the per-item typed code below), record and skip it per batch isolation, then canary the next item; fan out only after a non-blocked canary completes successfully. Every other canary failure is systemic: stop. Some failures are only visible on poll (async terminal states), so a submit-accepted batch can still be 100% doomed — a canary caps the blast radius of any systemic defect (bad reference form, provider outage, auth) at one item instead of the whole batch.
• Batch isolation: when producing a batch of independent items, a per-item provider content/safety rejection is isolated to that item. It is identified only by the typed code postplus_cli_hosted_media_content_policy_blocked, never by provider prose, and it surfaces at either boundary: a failed postplus media create whose typed error code is that code, or a submitted run whose poll result carries output.data.status: failed and output.data.error.code set to that code. On either, record which item was blocked and its exact reason, skip it, and continue submitting and polling the remaining items, then report the incomplete set at the end. Do not retry, soften, or re-submit the blocked item — that is a forbidden payload rewrite. Every other failure (a failed owned CLI/script command whose typed code is not that content-policy code, or a run whose error.code is not that content-policy code — auth, transport, quota, malformed request, provider outage) is systemic: stop per the rule above.

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.

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

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