---
name: sophnet-image-edit
description: Use when a user requests Sophnet image editing (image-to-image), including multi-image editing tasks (composition, style transfer, region swap) where all uploaded image paths must be resolved from Media Understanding logs (usually media/inbound/images/*) and passed in order to model Qwen-Image-Edit-2509.
metadata:
  short-description: Edit Sophnet images with strict multi-image path/order handling
---

# Sophnet Image Edit

## Overview

Edit existing images with Python scripts that handle task polling and structured output.

Script responsibilities:

- `edit_image.py`: core API caller and polling loop, outputs `INPUT_IMAGE_COUNT`, `TASK_ID`, `STATUS`, and `IMAGE_URL`.
- `edit_and_preview.sh`: wrapper for local use, calls `edit_image.py`, downloads first result, adds `PREVIEW_PATH`.

## When to Use

- User asks to edit or transform existing images with Sophnet.
- Task uses one or more source images (URL or uploaded local files).
- Task depends on image order/role, such as:
  - put part of image-2 into image-1
  - render image-2 with image-1 style
  - blend/composite many images into one result
- Do not use when the task is pure text-to-image generation; use `sophnet-image-generate`.

## Image Path Resolution

When users upload images in chat channels, files are usually saved under `media/inbound/images/` in the workspace. Use Media Understanding logs to get exact resolved paths.

Typical log pattern:

```
[Media Understanding] Resolved relative path: "media/inbound/images/xxx.jpg" -> "/absolute/path/to/workspace/media/inbound/images/xxx.jpg"
```

Path rules:

- `--image` accepts URL, data URI, or local file path.
- Local file paths are auto-converted to data URI by the script.
- For multi-image tasks, pass every image explicitly and in required order.

## Multi-Image Rules

1. Keep source image order stable and explicit.
2. Bind prompt language to order (image-1, image-2, image-3...).
3. Do not drop "reference" images; pass all images used by the prompt.
4. Verify script output `INPUT_IMAGE_COUNT` equals expected image count before trusting results.

Recommended prompt pattern for multi-image tasks:

- `图1作为底图，图2提供主体元素，图3提供风格参考；将图2主体抠出放到图1右上角，并按图3风格整体渲染。`

## Quick Reference

| Goal                             | Command                                                                                                                                                                       |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Edit with one source             | `bash {baseDir}/scripts/edit_and_preview.sh --prompt "..." --image "https://example.com/source.jpg"`                                                                          |
| Edit with two sources (ordered)  | `bash {baseDir}/scripts/edit_and_preview.sh --prompt "图1作为底图，将图2主体放入图1左下角" --image "media/inbound/images/img1.jpg" --image "media/inbound/images/img2.jpg"`   |
| Style transfer across two images | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --prompt "使用图1的画风渲染图2内容" --image "/abs/path/style.jpg" --image "/abs/path/content.jpg"`         |
| Many images via CSV              | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --prompt "..." --images "media/inbound/images/a.jpg,media/inbound/images/b.jpg,https://example.com/c.jpg"` |
| Many images via list file        | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --prompt "..." --images-file "/tmp/image-list.txt"`                                                        |
| Validate image count only        | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --prompt "..." --images-file "/tmp/image-list.txt" --dry-run`                                              |
| Show options                     | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --help`                                                                                                    |

Notes:

- `--dry-run` does not require API key and is for input-count verification only.
- Prefer `--images-file` when handling many images or values that may contain commas.

`/tmp/image-list.txt` format example:

```text
# One image reference per line
media/inbound/images/base.jpg
media/inbound/images/object.png
https://example.com/style.jpg
```

## Script Output Fields

The script outputs structured key=value lines. Parse all of them:

| Field               | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `INPUT_IMAGE_COUNT` | Number of source images passed to the API                    |
| `TASK_ID`           | API task identifier                                          |
| `STATUS`            | `succeeded` or `failed`                                      |
| `OUTPUT_COUNT`      | Number of result images                                      |
| `IMAGE_URL`         | Publicly accessible signed URL for each result image         |
| `PREVIEW_PATH`      | Local file path (only when OSS re-upload failed as fallback) |

## Presenting Results to Users

After a successful edit, present the results with context -- not just a bare URL. Include:

1. What was done: mention the edit instruction / style applied.
2. Input/output image counts.
3. The result image URL(s): provide the `IMAGE_URL` so the user can view/download.
4. If `PREVIEW_PATH` is present, mention the local file path.

Example response pattern:

```
✅ 图片编辑完成！

🎨 **编辑指令**：把图片变成水彩画风格
🧾 **输入图片数**：1
🖼️ **结果图片**：![image](IMAGE_URL)
⚠️**提示**: 本内容有AI生成，图片保存24小时，请及时下载！
```

## Implementation

1. Resolve all uploaded image paths from Media Understanding logs.
2. If this edit step follows `sophnet-image-generate`, prefer upstream `IMAGE_URL` for handoff; use `PREVIEW_PATH` only when local-file input is explicitly intended.
3. Build prompt with explicit image order semantics.
4. Run script with one `--image` per image, or `--images`, or `--images-file`.
5. For multi-image tasks, run once with `--dry-run` and confirm `INPUT_IMAGE_COUNT` matches intended image count.
6. Parse ALL output fields (see table above) and present them to the user.
7. Use `PREVIEW_PATH` when present.

API payload shape:

- `model`: `Qwen-Image-Edit-2509`
- `input.prompt`: edit instruction with image-role semantics
- `input.images[]`: all source image refs in strict order
- `parameters`: `size`, `n`, `watermark`

## Common Mistakes

- Passing only one image for a multi-image prompt.
- Mentioning image-2/image-3 in prompt but not passing those images.
- Reordering `--image` arguments unintentionally.
- Ignoring `INPUT_IMAGE_COUNT` mismatch.
- Using non-existent local paths.
- In generate→edit workflows, defaulting to `PREVIEW_PATH` instead of `IMAGE_URL` without reason.
- Only showing a bare URL without context -- always present a summary with edit details.
