> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simplified.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplified.com/_mcp/server.

# Image editing

Image tools operate on reachable source URLs. If your file is on your computer,
[upload it as an asset](/cli/assets-and-uploads) and retrieve its processed
`file_url` first.

## 1. Prepare the source

Choose an image URL that the service can fetch without your browser session.
For masked edits, prepare a reachable mask image as well. Replace all example
URLs below with your own files.

## 2. Choose the operation

| Task                              | Command                   | Key inputs                                                    |
| --------------------------------- | ------------------------- | ------------------------------------------------------------- |
| Soften the background             | `image:blur-background`   | `--url`, optional `--blur`                                    |
| Remove the background             | `image:remove-background` | `--url`                                                       |
| Replace a background              | `image:replace`           | `--url`, `--replace-type` and the matching color/image option |
| Convert format                    | `image:convert`           | `--url`, `--format`                                           |
| Increase resolution               | `image:upscale`           | `--url`, `--scale`                                            |
| Restore a photo                   | `image:restore`           | `--url`                                                       |
| Fill or edit an area              | `image:generative-fill`   | `--url`, `--prompt`, optional `--mask-url`                    |
| Extend a composition              | `image:outpaint`          | `--url`, `--mask-url`, `--prompt`                             |
| Place a subject in a scene        | `image:magic-inpaint`     | `--url`, `--prompt`                                           |
| Transform with a text instruction | `image:pix-to-pix`        | `--url`, `--prompt`                                           |
| Generate from a sketch            | `image:sd-scribble`       | `--prompt`, `--negative-prompt`, optional sketch `--url`      |

Run `simplified image:outpaint --help`, for example, for the full option set.

## 3. Run an edit

Remove a background and wait for the output:

```bash
simplified image:remove-background --url "https://cdn.example.com/product.jpg" --wait
```

Replace the background with a solid color:

```bash
simplified image:replace --url "https://cdn.example.com/product.jpg" \
  --replace-type color --replace-color "#FBF9F4" --wait
```

Prepare a larger or differently encoded image:

```bash
simplified image:upscale --url "https://cdn.example.com/product.jpg" --scale 4 --wait
simplified image:convert --url "https://cdn.example.com/product.png" --format webp --wait
```

Supported conversion formats are `jpeg`, `jpg`, `png`, `webp`, and `bmp`.
Upscaling supports factors of 2, 4, and 8.

## 4. Make a generative edit

```bash
simplified image:generative-fill \
  --url "https://cdn.example.com/product.jpg" \
  --mask-url "https://cdn.example.com/product-mask.png" \
  --prompt "A warm studio backdrop with soft natural shadows." --wait
```

For outpainting, both the source and mask are required:

```bash
simplified image:outpaint \
  --url "https://cdn.example.com/product.jpg" \
  --mask-url "https://cdn.example.com/expanded-mask.png" \
  --prompt "Continue the tabletop and neutral background." --wait
```

Inspect the result before reusing it; generative edits can change details beyond
the intended visual effect.

## 5. Retrieve and reuse the result

Most operations submit an asynchronous task. Without `--wait`, keep its
`task_id` and retrieve status with:

```bash
simplified image:task --id "TASK_ID"
```

Waiting polls every two seconds for up to 120 seconds. Inspect the returned
result for the output URL; response fields vary by operation. A timeout is a
reason to check the existing task, not automatically submit a duplicate.

`image:blur-background` is synchronous and returns `image_url` directly:

```bash
simplified image:blur-background --url "https://cdn.example.com/product.jpg" --blur 50
```

Pass a successful output URL into another edit or attach it to a
[social draft](/cli/social-publishing).