UnityClaw Image (Premium 2)
Generate images from a prompt with optional reference images. Run the bundled CLI, verify its structured result, and return downloaded local files to the user.
Agent Workflow
1. Understand the request
Extract the subject, intended use, visual style, scene, composition, color palette, lighting, required text, reference images, and explicit exclusions. Preserve facts supplied by the user. Ask a question only when a missing detail would materially change the image; otherwise make a reasonable visual choice and proceed.
Do not silently add brands, logos, people, text, or sensitive attributes the user did not request. Keep exact spelling for text that must appear in the image.
2. Build the prompt
Write one coherent generation prompt in this order when the information is available:
[deliverable and subject], [scene and action], [composition and camera],
[lighting and color], [visual style and material], [required text],
[quality requirements], [explicit exclusions]
Describe visible outcomes instead of vague praise. For example, prefer “soft window light, shallow depth of field, centered product with negative space above” over “make it beautiful.” Do not overwrite a complete user prompt merely to make it longer.
When exact typography matters, quote the required text and state its placement. Image models may still render text imperfectly; disclose that limitation when delivering the result.
3. Choose generation settings
Use an explicit user choice when present. Otherwise select settings from the intended use:
| Intended use | Aspect ratio | Resolution |
|---|---|---|
| Icon, avatar, square post | 1:1 |
1K preview, otherwise 2K |
| Poster or social cover | 4:5 or 3:4 |
2K |
| Banner, presentation, video cover | 16:9 |
2K |
| Phone wallpaper or vertical story | 9:16 |
2K |
| Final high-resolution or print-oriented asset | Match the requested layout | 4K |
Default to 2K. Use 1K when the user explicitly wants a preview or fast draft. Do not select 4K merely because it is available.
4. Handle reference images
Determine whether each reference controls the subject identity, composition, palette, or style. State that role in the prompt, in the same order as repeated --attachment arguments. Never claim pixel-perfect identity preservation.
Resolve local paths before execution. Do not replace a provided local reference with an unrelated remote URL. Use repeated flags rather than comma-separated values when constructing a new command.
5. Execute once
Run scripts/generate.js with --json and an explicit --output-dir. Quote every user-derived shell argument. Allow the CLI to perform its configured transient retries. Do not launch duplicate generation commands concurrently for the same request.
6. Validate and deliver
Parse the JSON response. Accept completion only when success is true and every files entry has an existing local localPath and a positive bytes value. The CLI enforces this download validation and returns OUTPUT_VALIDATION_ERROR otherwise.
Present the local files to the user and briefly state the chosen aspect ratio and resolution. Treat temporaryUrl as diagnostic information, not the primary deliverable.
7. Iterate deliberately
Retry technical failures only when error.retryable is true; respect the CLI retry limit. Do not retry authentication, validation, missing-file, or output-validation errors without fixing their cause.
Do not automatically spend another generation on a valid but subjective result. Show the first result and use the user's feedback to change only the relevant prompt dimensions, such as composition, palette, typography, or style. Reuse the previous output as a reference only when the user wants a variation or refinement.
Authorization
Provide the API key through the fixed UNITYCLAW_KEY environment variable. Obtain a key from UnityClaw if needed. The runtime installation declaration installs @unityclaw/sdk; for manual execution, run npm install @unityclaw/sdk when the package is unavailable.
Usage
node scripts/generate.js --prompt "A cinematic mountain sunrise" --size 2K
node scripts/generate.js --prompt "Luxury perfume product shot" --attachment ./ref.png --aspect-ratio 4:5 --size 4K
node scripts/generate.js --prompt "Create a variation" --attachment ./subject.png --attachment ./style.png --json --output-dir ./tasks
Parameters
| Parameter | Short | Required | Default | Description |
|---|---|---|---|---|
--prompt |
-p |
Yes | - | Image-generation prompt; blank values are rejected |
--attachment |
-a |
No | - | Reference image URL or local file; repeat the option for multiple images; comma-separated values remain supported |
--aspect-ratio |
-r |
No | Model default | Output aspect ratio |
--size |
-s |
No | 2K |
Output resolution: 1K, 2K, or 4K |
--output-dir |
- | No | ./tasks |
Task output directory; resolved to an absolute path |
--timeout |
- | No | 900000 |
SDK request timeout in milliseconds, from 1,000 to 3,600,000 |
--retries |
- | No | 1 |
Retry count for transient failures, from 0 to 3 |
--json |
- | No | false |
Emit one machine-readable JSON result without progress output |
--help |
-h |
No | - | Show help |
Supported aspect ratios: 1:1, 9:16, 16:9, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9, 1:4, 1:8, 4:1, 8:1.
Output Contract
With --json, the command emits exactly one JSON object. A successful result contains success, attempts, taskId, taskFolder, duration, outputDir, and files. Each verified file contains name, contentType, absolute localPath, bytes, and an optional temporaryUrl.
A failed result contains a stable error.code, human-readable error.message, error.retryable, attempts, and any available task or log information. The process exits non-zero on failure.
Resource Index
- Run
scripts/generate.jsfor image generation.
