> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 图像编辑最佳实践

> [!NOTE]
>
> `step-image-edit-2` 已于 2026 年 10 月 10 日下线，图片编辑接口已同步停止服务。详见[图像模型下线公告](https://platform.stepfun.com/docs/zh/announcements/image-model-retirement.md)。

阶跃星辰提供图像编辑模型，可基于用户输入的图片和 Prompt 对图片进行修改。图像编辑能力通过 `/v1/images/edits` 接口调用。

## 支持的模型

| 模型 | 说明 |
| - | - |
| `step-image-edit-2` | 新一代轻量级图像生成编辑模型，单次编辑任务仅需 1-2 秒，适合实时交互修图场景。输入图最大支持 4096x4096 分辨率。 |

完整参数、取值范围和响应结构请参考 [图片编辑 API 文档](https://platform.stepfun.com/docs/zh/api-reference/images/edits)。

## 输入图要求

`step-image-edit-2` 对输入图的限制：

* 分辨率：最大支持 `4096x4096`
* 传入方式：支持图片的 Base64
* 输出结果：返回和输入图一样大小的结果图

## 基础调用

> [tab] python
>
> ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> import base64
> from openai import OpenAI
>
> client = OpenAI(api_key=STEP_API_KEY, base_url="https://api.stepfun.com/v1")
>
> prompt = """
> 变成一只英短猫
> """
>
> result = client.images.edit(
>     model="step-image-edit-2",
>     image=open("cat.jpg", "rb"),
>     prompt=prompt,
>     response_format="b64_json",
>     extra_body={
>         "cfg_scale": 1.0,
>         "steps": 8,
>         "seed": 1
>     },
> )
>
> print(result)
> image_base64 = result.data[0].b64_json
> image_bytes = base64.b64decode(image_base64)
>
> with open("cat-on-rooftop.png", "wb") as f:
>     f.write(image_bytes)
> ```

> [tab] js
>
> ```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> import fs from "fs";
> import OpenAI, { toFile } from "openai";
>
> const client = new OpenAI({
>     apiKey: STEP_API_KEY,
>     baseURL: "https://api.stepfun.com/v1"
> });
>
> const file = await toFile(fs.createReadStream("cat.jpg"), null, {
>     type: "image/jpeg"
> });
>
> const rsp = await client.images.edit({
>     model: "step-image-edit-2",
>     image: file,
>     prompt: "变成一只英短猫",
>     // @ts-expect-error this is not yet public
>     cfg_scale: 1.0,
>     steps: 8,
>     seed: 1,
>     response_format: "b64_json"
> });
>
> console.log(rsp);
>
> const image_base64 = rsp.data[0].b64_json;
> const image_bytes = Buffer.from(image_base64, "base64");
> fs.writeFileSync("cat2.jpg", image_bytes);
> ```

> [tab] curl
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> curl -X POST "https://api.stepfun.com/v1/images/edits" \
>   -H "Authorization: Bearer $STEP_API_KEY" \
>   -F 'model=step-image-edit-2' \
>   -F 'image=@test_cref_input02_resized.webp' \
>   -F 'prompt=让图中角色骑自行车，手上举个牌子写着"沙特阿拉伯"' \
>   -F 'response_format=b64_json' \
>   -F 'cfg_scale=1.0' \
>   -F 'steps=8' \
>   -F 'seed=1' \
>   -F 'text_mode=true'
> ```

## 参数要点

* **Prompt 最大长度**：512 个字符。
* **`cfg_scale`**：默认 1.0、范围 `[1.0, 10.0]`。
* **`steps`**：默认 8、范围 `[1, 50]`。
* **`text_mode`**：针对文字场景的优化策略，按需开启，默认关闭。
* **`negative_prompt`**：字符数不超过 512，默认 `""`。若 `cfg_scale = 1.0`，当前实现不会把负面提示词传给底层模型。
* **`response_format`**：支持 `b64_json` 或 `url`，默认 `url`。

## 编辑 Prompt 示例

以下示例 Prompt 与效果图摘自 `step-image-edit-2` 的官方样例，可作为不同编辑任务的写法参考。

### 姿态 / 对话气泡

**Prompt**：让图中猫躺在地上露出肚皮，旁边有个对话气泡框写着"我错了"

| 输入图 | 效果图 |
| :-: | :-: |
| ![](https://mintcdn.com/stepfun/1VdJKiRsguWM75uf/images/guide/step-image-edit-2/edit-01-cat-before.png?fit=max\&auto=format\&n=1VdJKiRsguWM75uf\&q=85\&s=04af0a1d3eef22aeebe94e196d907876) | ![](https://mintcdn.com/stepfun/1VdJKiRsguWM75uf/images/guide/step-image-edit-2/edit-01-cat-after.png?fit=max\&auto=format\&n=1VdJKiRsguWM75uf\&q=85\&s=c1fdb2ee1221d0e60f561c023737f97a) |

### 服装替换

**Prompt**：图中男性换成西装和衬衫，女性换成一个美丽的西式婚纱，头戴纱巾，两个人同时正面面向镜头

| 输入图 | 效果图 |
| :-: | :-: |
| ![](https://mintcdn.com/stepfun/1VdJKiRsguWM75uf/images/guide/step-image-edit-2/edit-02-couple-before.png?fit=max\&auto=format\&n=1VdJKiRsguWM75uf\&q=85\&s=7084014faf98358da047c3822c5e64a3) | ![](https://mintcdn.com/stepfun/1VdJKiRsguWM75uf/images/guide/step-image-edit-2/edit-02-couple-after.png?fit=max\&auto=format\&n=1VdJKiRsguWM75uf\&q=85\&s=331765743a851267fe3291cbc9274bc2) |

## 常见问题

* **返回 "消息获取失败"**：在使用 `step-image-edit-2` 时，这种情况大概率是输入图太大（目前最大支持 `4096x4096` 分辨率的输入图）。
* **错误处理**：更系统的异常处理思路可参考 [处理异常，让您的应用更加健壮](https://platform.stepfun.com/docs/zh/guides/developer/exception.md)。

## 相关链接

> [card] [图片编辑 API 文档](https://platform.stepfun.com/docs/zh/api-reference/images/edits)

> [card] [图片生成最佳实践](https://platform.stepfun.com/docs/zh/guides/developer/image-generate)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.