3d-image-generator

# 3D Image Generator (`3d-image-generator`) Generate 3D rendered art and icons. Use when the user asks for 3D graphics, claymorphism, octane render, or blender 3d style. This skill follows a **single aggregated gateway backend** model. One API key is used locally, while multiple models are aggregated behind the gateway. The CLI wraps the full async flow: submit task -> poll lowercase `task_status` -> fetch `data.images`. The backend platform is a **fixed implementation choice**, not a configurable provider switch. If another platform is needed, publish a separate skill for it. The design goal is smooth automation for common workflows such as single-image generation, multi-file prompts, image-to-image with references, batch jobs, EXTEND defaults, and reusable style presets. Full gateway-alignment notes are in [references/weryai-platform.md](references/weryai-platform.md). ## Strict Style Enforcement As the 3D Image Generator agent, you MUST always enforce this specific style. 1. Always append `--style 3d-render` to your `3d-image-generator` CLI command. 2. When building the prompt, seamlessly blend these keywords into the visual description: "3d render, octane render, unreal engine, claymorphism, soft lighting, ray tracing". Do not ask the user which style they want, because this skill is strictly dedicated to 3D Image Generator. ## Safety & Scope - **Network**: This skill calls the WeryAI gateway over HTTPS (`https://api.weryai.com`). - **Auth**: Uses `IMAGE_GEN_API_KEY`. The key is never printed. It may be persisted **only** when you explicitly run `npm run setup -- --persist-api-key`. - **Reference images**: Must be public URLs (`https://` recommended). `http://` may work but is insecure. Local file paths and `data:` URLs are rejected. - **No arbitrary shell**: The generation runtime does not execute arbitrary shell commands. - **Files written**: Output images and optional local config under `.image-skills/3d-image-generator/` (project) and/or `~/.image-skills/3d-image-generator/` (home). ## Current Gateway Contract (WeryAI) | Item | Contract | | --- | --- | | Base URL | `https://api.weryai.com` (hard-coded in `scripts/main.ts`) | | Auth | `Authorization: Bearer` via **`IMAGE_GEN_API_KEY`** ([get a key](https://weryai.com/api/keys)) | | text-to-image | `POST /v1/generation/text-to-image`; requires `model`, `prompt`, `aspect_ratio` | | image-to-image | `POST /v1/generation/image-to-image`; also requires `images[]` | | status lookup | `GET /v1/generation/{taskId}/status`; `task_status` is `waiting`, `processing`, `succeed`, or `failed` | | business success | **`success: true`** (or `status: 200`); failures return business codes such as `1001`, `1002`, `1003` | | text length | the script validates `prompt` and `negative_prompt` lengths before request submission | | result download | after `succeed`, images are fetched by URL; the script uses timeout, retry, backoff, optional Bearer retry, and minimum-payload validation | See [references/weryai-platform.md](references/weryai-platform.md) for field mapping, model lookup guidance, and troubleshooting flow. ## Step 0: First-Trigger Readiness Gate When this skill is triggered for the **first time** in a project or environment, the agent must not jump straight to model selection or generation. It must do this first: 1. **Check local readiness silently** with `npm run ensure-ready -- --project . --workflow <workflow>` 2. **If runtime dependencies are missing**, propose to install them on behalf of the user 3. **If `IMAGE_GEN_API_KEY` is missing**, ask the user for permission to configure it now 4. Only after readiness and API key are resolved, continue to model selection / prompt clarification / generation **Access token**: only use **`IMAGE_GEN_API_KEY`**. It may also live in `.image-skills/3d-image-generator/.env` as `IMAGE_GEN_API_KEY=...`. After the user approves, the agent may persist it there by running `npm run setup -- --project . --workflow <workflow> --persist-api-key` when the key is already in env, or by writing the file locally on the user's behalf instead of asking the user to edit files manually. **First-use readiness check**: before the first generation run in a new OpenClaw or local instance, the agent must run: ```bash npm run ensure-ready -- --project . --workflow <workflow> ``` This readiness step is not optional. It checks the local toolchain, reads the local doctor report, and automatically runs `bootstrap` when local script dependencies are missing. **First-trigger user behavior**: - If dependencies are missing: ask for approval to install them, then install silently - If `IMAGE_GEN_API_KEY` is missing: tell the user image generation needs an API key and offer to configure it now by writing `.image-skills/3d-image-generator/.env` on the user's behalf - Do not ask the user to debug the environment before this readiness gate runs - Do not ask the user to choose a model before readiness and API key are resolved - Treat API keys as secrets: prefer writing them locally on the user's behalf, never echo them back, and never include them in normal progress messages **`EXTEND.md`** is optional and can hold default model, quality, aspect ratio, and batch worker limits. ```bash test -f .image-skills/3d-image-generator/EXTEND.md && echo project test -f "$HOME/.image-skills/3d-image-generator/EXTEND.md" && echo user ``` **Default model on initialization**: if no model is configured yet, initialize this skill with **Nano Banana 2** (`GEMINI_3_1_FLASH_IMAGE`) and tell the user that it is now the default. Also remind them they can switch models anytime later. **Model selection**: after initialization, one of these provides the active default: - `--model` - `default_model` in `EXTEND.md` - `IMAGE_GEN_DEFAULT_MODEL` If none of them is set yet, the agent should initialize the local default to **Nano Banana 2** first, tell the user that this workspace now defaults to that model, and remind them they can switch anytime if another model fits better. See [references/config/first-time-setup.md](references/config/first-time-setup.md), [references/config/preferences-schema.md](references/config/preferences-schema.md), and [references/config/model-registry-schema.md](references/config/model-registry-schema.md). **Style presets**: [references/style-presets.md](references/style-presets.md) Model priority: `--model` -> `EXTEND.md default_model` -> `IMAGE_GEN_DEFAULT_MODEL` ## If No Model Was Specified When the user wants image generation but no model is configured (`EXTEND.md`, `--model`, and `IMAGE_GEN_DEFAULT_MODEL` are all absent): **Do not ask the user to read docs or edit config files.** Follow the guided flow in [references/config/first-time-setup.md](references/config/first-time-setup.md) § "Model Selection — Agent-Guided Flow": 1. Start from the bundled starter registry shipped with this skill. If the model list looks stale or a requested model is missing, refresh it silently with `npm run discover-image-models -- --out .image-skills/3d-image-generator/MODELS.json` 2. Initialize local defaults with **Nano Banana 2** (`GEMINI_3_1_FLASH_IMAGE`) by writing `EXTEND.md` 3. Tell the user that the default model is now **Nano Banana 2**, and explicitly remind them they can switch anytime later if they need another model 4. Continue to prompt clarification and generation 5. If the user immediately asks for another model, rank candidates for the workflow → `npm run recommend-model -- --workflow <workflow> --role <role> --json`, then update `EXTEND.md` If the workflow is more specific than a generic single image, prefer a role-aware recommendation such as `comic-page`, `comic-character-sheet`, `infographic-dense`, or `article-framework` instead of only passing the broad workflow name. If the user later asks to switch models, update `EXTEND.md` in place — do not ask the user to edit it manually. If the gateway returns "model does not exist" or a similar model-key error, the agent must first refresh from WeryAI docs and retry recommendation before asking the user for any platform-side information. ## If The Request Is Underspecified When the user gives only a rough idea and the visual brief is still weak, do not jump straight into prompt writing. Use the local brief helper first: ```bash npm run build-visual-brief -- --workflow cover --topic "Habit systems" ``` Use its question menu to ask about at least: 1. Photorealistic or illustration 2. Color temperature / palette direction 3. Shot language (close-up, wide, etc.) 4. Composition pattern 5. Aspect ratio 6. Text density Then map the answered brief into the final prompt or workflow files. Do **not** tell the user to go read the docs alone. If the CLI fails because the model is missing, the agent should complete this selection flow and retry. ## Workflow 1. On first trigger, run the readiness gate: check dependencies, bootstrap missing local tooling, and confirm `IMAGE_GEN_API_KEY`. 2. Confirm a default model is configured (via `EXTEND.md` or environment), or enter the guided model-selection flow. 3. Build the prompt: inline text (`--prompt`) or assembled from files (`--promptfiles`). 4. Choose a style preset if applicable (`--style`). 5. Run the CLI to submit the task, poll for completion, and download the result. 6. For multiple images, use batch mode (`--batchfile`) with parallel jobs. ## Script `{baseDir}` is the directory containing this file. `${BUN_X}` is either `bun` or `npx -y bun`. | Path | Purpose | | --- | --- | | `{baseDir}/scripts/main.ts` | the only execution entrypoint | ## Usage ```bash # examples only; M should be chosen by the user or resolved by the agent M=<chosen model key> # single image ${BUN_X} {baseDir}/scripts/main.ts --prompt "a cat" --image cat.png --ar 1:1 -m "$M" # prompt assembled from multiple files ${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md user.md --image out.png --ar 16:9 -m "$M" # style preset ${BUN_X} {baseDir}/scripts/main.ts --prompt "city nightscape" --style cinematic --image out.png --ar 16:9 -m "$M" # image-to-image with reference ${BUN_X} {baseDir}/scripts/main.ts --prompt "turn it into cyberpunk" --image out.png --ref src.png --ar 1:1 -m "$M" # quality / resolution ${BUN_X} {baseDir}/scripts/main.ts --prompt "poster" --image poster.png --ar 16:9 --quality 2k -m "$M" ${BUN_X} {baseDir}/scripts/main.ts --prompt "poster" --image poster.png --ar 16:9 --imageSize 2K -m "$M" # infer aspect from size when --ar is omitted ${BUN_X} {baseDir}/scripts/main.ts --prompt "scene" --image scene.png --size 1280x720 -m "$M" # batch mode ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4 --json # do not write downloaded images to disk ${BUN_X} {baseDir}/scripts/main.ts --prompt "abstract" --image dummy.png --ar 1:1 --no-download -m "$M" # dry-run request preview; --image is optional here ${BUN_X} {baseDir}/scripts/main.ts --prompt "test" --ar 1:1 -m "$M" --dry-run ``` ### Batch JSON Example ```json { "jobs": 4, "tasks": [ { "id": "hero", "promptFiles": ["prompts/hero.md"], "image": "out/hero.png", "model": "<model key from gateway docs>", "style": "editorial", "ar": "16:9", "quality": "2k", "use_web_search": false }, { "id": "edit", "prompt": "turn it into watercolor", "image": "out/edit.png", "ref": ["assets/in.png"], "negative_prompt": "blurry", "webhook_url": "https://example.com/hook" } ] } ``` Paths are resolved relative to the **batch file directory**. If a `provider` field exists, it is ignored in single-gateway mode. Task-level optional fields include `style`, `webhook_url`, `negative_prompt`, `resolution`, `use_web_search`, and `caller_id`. ## Main Options | Option | Description | | --- | --- | | `--prompt` / `-p` | prompt text | | `--promptfiles` | concatenate multiple files into the prompt | | `--image` / `-o` / `--output` | output path in single-task mode; defaults to `.png` if no extension is given | | `--batchfile` | batch JSON file | | `--jobs` | worker count | | `--model` / `-m` | model key; one of CLI / `EXTEND.md` / `IMAGE_GEN_DEFAULT_MODEL` must provide it | | `--style` | style preset, see [style-presets.md](references/style-presets.md) | | `--ar` / `--aspect-ratio` | aspect ratio; defaults to `EXTEND.md` or `1:1` | | `--size` | `WIDTHxHEIGHT`; can infer aspect ratio if `--ar` is omitted | | `--quality` | `normal` or `2k`, mapped into gateway resolution | | `--imageSize` | `1K`, `2K`, or `4K` | | `--resolution` | pass resolution directly to the API | | `--negative-prompt` | negative prompt | | `--ref` / `--reference` | reference image, either URL or local file | | `--n` | `image_number` (default: 1) | | `--webhook-url` | gateway `webhook_url` | | `--use-web-search` | set `use_web_search: true` | | `--caller-id` | gateway `caller_id` | | `--poll-interval-ms` / `--poll-timeout-ms` | polling controls | | `--no-download` | skip file writing | | `--dry-run` | print the final request body instead of calling the API | | `--json` | JSON summary or batch report | ## Parallelism and Retry - Batch jobs use gated concurrency through `--jobs`, with environment overrides such as `BASE_IMAGE_GEN_CONCURRENCY` and `BASE_IMAGE_GEN_START_INTERVAL_MS`. - A single task retries up to 3 times, but obvious parameter or auth errors are not retried. - Batch worker caps come from `batch.max_workers` in `EXTEND.md` or `BASE_IMAGE_MAX_WORKERS`. ## Environment Variables | Variable | Description | | --- | --- |