📚 离职知识库

阶跃星辰 图片编辑 API（images/edits）

图片编辑 API 可基于用户输入的图片和 Prompt 对图片进行修改。

#请求地址

POST https://api.stepfun.com/v1/images/edits

#请求参数

  • model string required 需要使用的模型名称，当前支持 step-image-edit-2。
  • image file required 传入的图片文件，当前仅支持传入一个图片。最大支持 4096x4096 分辨率的输入图；支持传入图片的 Base64。
  • prompt string required 图像的文本描述，最大长度为 512 个字符。
  • seed int optional 随机种子，取值范围 [0, 2147483647]；若不传，服务端会随机生成一个种子。
  • steps int optional 生成步数，取值范围 [1, 50]。默认为 8。
  • cfg_scale float optional classifier-free guidance scale。必须 >= 1.0，取值范围 [1.0, 10.0]。默认为 1.0。
  • size string optional 编辑场景下该参数不生效，会返回和输入图一样大小的结果图。
  • negative_prompt string optional 负面提示词。字符数不超过 512，默认 ""。若 cfg_scale = 1.0，当前实现不会把负面提示词传给底层模型。
  • text_mode bool optional 针对文字场景的优化策略。默认 False，按需开启。
  • response_format string optional 生成的图片返回的格式。支持参数为 b64_json 或 url。默认为 url。

#请求响应

  • created int 创建图片时的时间戳，精确到秒级别
  • data object array
    • seed int 生成时传入的 Seed 或系统随机生成的 Seed。相同的 Seed 有助于生成类似的图片。
    • finish_reason string 生成停止的原因，success 为成功生成；content_filtered 表示生成成功但命中检测所以停止。
    • b64_json string 生成的图片的 Base64 编码。当 response_format 设置为 b64_json 时返回。
    • url string 生成的图片的下载链接。当 response_format 设置为 url 时返回。链接存在有效期限（当前为 30 天），建议下载保存到自己的存储以避免依赖。
{
  "created": 1589478378,
  "data": [
    {
      "b64_json": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1",
      "finish_reason": "success",
      "seed": 123838
    }
  ]
}

#示例

#python

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)

#js

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: "变成一只英短猫",
    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);

#curl

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'

响应示例：

{
  "id": "<示例响应ID>",
  "created": 1752565891,
  "data": [
    {
      "url": "https://res.stepfun.com/image_gen/20250715/sample.png",
      "finish_reason": "success",
      "seed": 1
    }
  ]
}

来源：沉淀/02-AI与API/阶跃图片编辑API-images-edits.md（整理于 2026-08-18）

相关笔记