Images

# Images

Turn ideas into on-brand visuals instantly -- generate, edit, and upscale images from the CLI.

## When to Use
- User needs a social media graphic, blog hero image, or marketing banner
- User wants to edit an existing image (remove background, change text, adjust colors)
- User wants to upscale a low-resolution image to higher quality
- User needs on-brand visuals for a campaign or launch

## How It Connects
- **Branding** -- Brand colors, logos, and fonts are automatically applied to generated images. Set up branding first for consistent visuals.
- **Social Media** -- Generated images can be attached to social posts using the returned asset ID with the `--media` flag.
- **Blog** -- Use generated images as hero images or inline visuals in blog articles.
- **Video** -- For moving content, use the video skill instead. Images handles static visuals only.

## Quick Start

Generate an image:
```bash
clawpow images create --prompt "A hero banner for our product launch" --json
```

## Commands

### Generate Image
```bash
clawpow images create --prompt "Description of the image" --json
clawpow images create --prompt "Description" --aspect-ratio 16:9 --json
clawpow images create --prompt "Description" --no-branding --json
clawpow images create --prompt "Description" --reference-images assetId1 assetId2 --json
```
Generate an image. Brand styling is applied automatically unless --no-branding is used.

**Options:**
- `--prompt <text>` (required) -- Text description of the desired image
- `--aspect-ratio <ratio>` -- Aspect ratio: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default: 1:1)
- `--reference-images <assetId...>` -- Asset IDs of reference images for style guidance
- `--no-branding` -- Skip brand styling

**Returns:** `{"imageId": "...", "status": "generating"}`

### Edit Image
```bash
clawpow images edit --prompt "Remove the background" --image <assetId> --json
clawpow images edit --prompt "Change the text to say Hello World" --image <assetId> --json
clawpow images edit --prompt "Make the colors warmer" --image <assetId> --no-branding --json
clawpow images edit --prompt "Crop to landscape" --image <assetId> --aspect-ratio 16:9 --json
```
Edit an existing image using AI. Provide a source image asset ID and edit instructions. Brand styling is applied automatically unless --no-branding is used.

**Options:**
- `--prompt <text>` (required) -- Edit instructions describing the desired changes
- `--image <assetId>` (required) -- Asset ID of the source image to edit
- `--aspect-ratio <ratio>` -- Aspect ratio: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default: 1:1)
- `--no-branding` -- Skip brand styling

**Returns:** `{"imageId": "...", "status": "generating"}`

### Upscale Image
```bash
clawpow images upscale --image <assetId> --json
```
Upscale an image to 4x resolution using AI super-resolution. No prompt or branding options needed -- just provide the source image.

**Options:**
- `--image <assetId>` (required) -- Asset ID of the image to upscale

**Returns:** `{"imageId": "...", "status": "generating"}`

### Get Image
```bash
clawpow images get <imageId> --json
```
Get image generation details and the result asset URL when available.

**Options:**
- `<imageId>` (required) -- Image generation ID

**Returns:** `{_id, prompt, aspectRatio, status, resultAssetId, resultUrl, _creationTime}`

### List Images
```bash
clawpow images list --json
clawpow images list --status ready --json
```
List generated images with optional filters.

**Options:**
- `--status <status>` -- Filter by status: generating, ready, failed

**Returns:** Array of `{_id, prompt, aspectRatio, status, resultAssetId, resultUrl, _creationTime}`

## Output Format

All commands support `--json` for structured output. Without `--json`, output is human-readable.

## Important Notes

- Always use `--json` for machine-parseable output
- Image generation, editing, and upscaling are paid operations (consume credits)
- Image listing and detail lookup are free operations
- Generated images are stored as assets and can be used in social posts
- Supported aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9