图像编辑最佳实践

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

支持的模型

模型	说明
`step-image-edit-2`（推荐）	新一代轻量级图像生成编辑模型，单次编辑任务仅需 1-2 秒，适合实时交互修图场景。输入图最大支持 4096x4096 分辨率。
`step-1x-edit`	支持多种输入格式，能够理解用户意图并生成符合要求的图像编辑结果，适合应用于图像编辑、人像美化、艺术创作等场景。限时免费调用中。

完整参数、取值范围和响应结构请参考图片编辑 API 文档。

输入图要求

不同模型对输入图的限制不同：

step-image-edit-2
- 分辨率：最大支持 4096x4096
- 传入方式：支持图片的 Base64
- 输出结果：返回和输入图一样大小的结果图
step-1x-edit
- 分辨率：最小 64px，最大 1728px，最大像素面积不可超过 1024x1024
- 文件格式：jpg、png、webp
- 文件大小：10MB
- 尺寸比例：需大于等于 1:3 且小于等于 3:1

基础调用

Step Image Edit 2

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'

Step 1X Edit

python
js
curl

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-1x-edit",
    image=open("cat.jpg", "rb"),
    prompt=prompt,
    response_format="b64_json",
    extra_body={
        "cfg_scale": 10.0,
        "steps": 20,
        "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)

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-1x-edit",
    image: file,
    prompt: "变成一只英短猫",
    // @ts-expect-error this is not yet public
    cfg_scale: 10.0,
    steps: 20,
    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);

curl -X POST "https://api.stepfun.com/v1/images/edits" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -F "model=step-1x-edit" \
  -F "image=@cat.jpg" \
  -F "response_format=url" \
  -F 'prompt=变成一只英短'

参数要点

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

编辑 Prompt 示例

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

姿态 / 对话气泡

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

输入图	效果图

服装替换

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

输入图	效果图

常见问题

返回 “消息获取失败”：在使用 step-image-edit-2 时，这种情况大概率是输入图太大（目前最大支持 4096x4096 分辨率的输入图）。
错误处理：更系统的异常处理思路可参考处理异常，让你的应用更加健壮。

支持的模型

输入图要求

基础调用

Step Image Edit 2

Step 1X Edit

参数要点

编辑 Prompt 示例

姿态 / 对话气泡

服装替换

常见问题

相关链接

图片编辑 API 文档

图片生成最佳实践

​支持的模型

​输入图要求

​基础调用

​Step Image Edit 2

​Step 1X Edit

​参数要点

​编辑 Prompt 示例

​姿态 / 对话气泡

​服装替换

​常见问题

​相关链接

图片编辑 API 文档

图片生成最佳实践

支持的模型

输入图要求

基础调用

Step Image Edit 2

Step 1X Edit

参数要点

编辑 Prompt 示例

姿态 / 对话气泡

服装替换

常见问题

相关链接