/image-generate

name: image-generate
scope: persistence
description: Generate one new image from a text prompt and deliver it once as the current Prismer reply attachment. Use for draw, generate-image, poster, diagram, illustration, or other text-to-image requests. Do not use for editing or merely describing an existing image.
applies_to: [hermes, claude-code, openclaw, codex]
requires:
  - assets
phaseModel:
  defaultPhase: tool_use
version: 2
config:
  - key: IMAGE_GEN_MODEL
    type: string
    required: false
    default: null
    bindable: [global, role, agent]
    description: Preferred image-generation model id. The helper discovers the deployment model list and falls back by priority.
    prompt:
      zh: "生成图片时希望默认用哪个模型？"
      en: "Which image model should be used by default?"

Image Generate

URL-only provider responses require an explicit comma-separated HTTPS origin allowlist in `PRISMER_IMAGE_DOWNLOAD_ORIGINS`; prefer the requested `b64_json` response. The helper rejects redirects, non-image responses and downloads over 32 MiB. Never populate the allowlist from model output or untrusted page text.

Generate and deliver the requested image through the bundled helper. The helper owns model discovery, fallback, byte decoding, hashing, file creation, and the single `cloud deliver` call. Do not rebuild those steps in Python, curl, or a temporary script.

Run

From this skill directory, run:

node scripts/generate-and-deliver.mjs \
  --prompt '<complete generation prompt>' \
  --size 1024x1024

Optional flags:

• `--model <id>` overrides `IMAGE_GEN_MODEL` for this call.
• `--output <path>` selects the local PNG/JPEG/WebP filename. Without it, the

helper writes a content-hashed file under `PRISMER_ARTIFACTS_DIR` (or cwd when no dispatch artifacts directory is available).

• `--size` accepts `256x256`, `512x512`, `1024x1024`, `1792x1024`, or

`1024x1792`; the selected deployment model must advertise that size.

Defaults: square `1024x1024`; portrait `1024x1792` or landscape `1792x1024` only when the user asks for that orientation. Generate one image per helper invocation.

Delivery contract

The helper ends by running `cloud deliver <file> --json` exactly once and consumes that machine output internally. Runtime turns the delivered asset into the reply's structured attachment and the chat renderer shows the preview.

Read the helper's one-line status before replying:

• `[image-generate] delivered` means the asset was uploaded for this reply.

Reply with a short natural-language caption; model and size may be mentioned.

• `[image-generate] queued` means the bytes are durable locally but the cloud

upload is pending reconnection. Say it was generated and queued for upload; do not claim it is already attached.

• `[image-generate] uploaded-unattached` means the cloud stored the image under

the run archive but no active reply dispatch existed. Say it was generated and archived; do not claim it is attached.

• Do not paste the helper's JSON, assetId object, ContentBlock, base64, data URI,

signed URL, or local path into the message body.

• Do not run `cloud deliver`, `cloud file send`, `cloud task attach`, an asset

upload command, or a multipart request again for the same output.

• Do not manually construct a structured attachment. Runtime owns that wire

representation.

The generated file may also be observed by Runtime's dispatch-final artifact scan. That scan and `cloud deliver` share the same run/task scope and content-addressed dedup key; agents must not add another upload path.

Prompt handling

Use the user's requested subject, composition, style, lighting, camera angle, palette, text, and exclusions. Expand a vague request only enough to make those visual choices explicit; do not silently change the subject or intent.

Do not generate privacy-sensitive depictions of identifiable people without the user's explicit request. For editing, variation, or inpainting of an existing image, use an image-editing capability instead. For reading an existing image, use the asset/vision path.

Helper behavior

The bundled script:

1. Resolves `PRISMER_CLOUD_BASE` / `PRISMER_BASE_URL` and `PRISMER_API_KEY`, falling back to the Prismer runtime config. 2. Discovers available image models, filters them by the requested size before generation, and honors a compatible `--model` or `IMAGE_GEN_MODEL` first. 3. Retries the next model only for model-not-found, quota/rate-limit, or server failures. Prompt rejection and insufficient credits stop immediately. 4. Accepts either base64 image bytes or a short-lived image URL, validates the resulting PNG/JPEG/WebP bytes, and writes one content-hashed file. 5. Delivers that file once through the daemon-aware CLI path, distinguishing a completed upload from a durable offline queue receipt.

If it fails, report its status/code/message and stop. Do not fabricate an assetId, claim that delivery succeeded, or retry a rejected prompt unchanged.

Examples

Square illustration:

node scripts/generate-and-deliver.mjs \
  --prompt 'Isometric server room, glowing blue racks, cinematic lighting' \
  --size 1024x1024

Portrait poster with an explicit model preference:

node scripts/generate-and-deliver.mjs \
  --prompt 'Minimalist monochrome owl poster, centered subject, clean negative space' \
  --size 1024x1792 \
  --model "$IMAGE_GEN_MODEL"

Successful chat reply example: `图已生成并附在这条消息中。`