Step Image Edit 2 实战指南:文生图与图像编辑

作者:问答酱2026.11.17 03:46浏览量:0

简介:想接入 Step Image Edit 2,却不清楚文生图和图像编辑接口怎么调用?本文说明模型 ID、两个接口的区别和鉴权方式,附 curl 与 Python 完整示例,并整理参数含义、提示词写法、常见报错排查和成本控制思路,帮你少走弯路,尽快跑通第一次调用。

一、接入前先确认三件事

开始写代码前,先把最容易出错的信息对齐:

项目 内容
模型 ID step-image-edit-2
文生图接口 POST /v1/images/generations
图像编辑接口 POST /v1/images/edits
接入平台 阶跃星辰开放平台
鉴权方式 Bearer API Key,放在 HTTP Header Authorization 中

两个接口使用同一个模型 ID,区别在于入参形态。generations 只接收文本 prompt,适合从零生成图片。edits 需要额外上传一张原始图片,适合在原图基础上按文字指令修改。

Base URL 请以阶跃星辰开放平台的最新文档为准。下文示例统一使用环境变量 STEP_BASE_URL 表示地址,这样平台地址变化时只需修改配置,不必改动代码。

二、准备工作

  1. 注册并登录阶跃星辰开放平台,在控制台创建 API Key。密钥只在创建时完整展示一次,创建后请立即保存。
  2. 确认账户已开通 step-image-edit-2 的调用权限,并完成充值或额度领取。
  3. 本地准备 Python 3.8 及以上版本,并安装 requests:
  1. pip install requests

密钥应放在环境变量中,不要硬编码在代码里,避免提交到代码仓库后泄露:

  1. export STEP_API_KEY="你的API Key"
  2. export STEP_BASE_URL="以开放平台文档为准的Base URL"

三、文生图:调用 /v1/images/generations

用 curl 快速验证

  1. curl -X POST "$STEP_BASE_URL/images/generations" \
  2. -H "Authorization: Bearer $STEP_API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "model": "step-image-edit-2",
  6. "prompt": "赛博朋克风格的城市夜景,霓虹灯反射在湿漉漉的街道上,电影感光影",
  7. "n": 1,
  8. "size": "1024x1024",
  9. "response_format": "url"
  10. }'

如果返回结果正常,说明密钥、模型权限和网络都已通过检查。

Python 完整示例

下面的示例包含超时设置、状态码检查和结果解析。

  1. import os
  2. import requests
  3. BASE_URL = os.environ["STEP_BASE_URL"]
  4. API_KEY = os.environ["STEP_API_KEY"]
  5. def text_to_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
  6. resp = requests.post(
  7. f"{BASE_URL}/images/generations",
  8. headers={"Authorization": f"Bearer {API_KEY}"},
  9. json={
  10. "model": "step-image-edit-2",
  11. "prompt": prompt,
  12. "n": n,
  13. "size": size,
  14. "response_format": "url",
  15. },
  16. timeout=120,
  17. )
  18. if resp.status_code != 200:
  19. raise RuntimeError(f"{resp.status_code} -> {resp.text}")
  20. return resp.json()
  21. if __name__ == "__main__":
  22. data = text_to_image("一只戴着宇航头盔的柴犬,扁平插画风")
  23. for idx, item in enumerate(data["data"]):
  24. print(idx, item.get("url") or item.get("b64_json", "")[:64])

返回结构与结果保存

图片信息放在 data 数组中,即使只生成一张图,也要通过 data[0] 取值。response_format 为 url 时读取 url 字段。为 b64_json 时读取 base64 字符串并解码。

返回的图片链接通常有有效期,拿到结果后应尽快下载到自有存储。下面是一个简单的转存函数:

  1. import requests
  2. def save_url_image(url: str, path: str) -> None:
  3. resp = requests.get(url, timeout=60)
  4. resp.raise_for_status()
  5. with open(path, "wb") as f:
  6. f.write(resp.content)

如果使用 b64_json,可以直接解码落盘:

  1. import base64
  2. def save_b64_image(item: dict, path: str) -> None:
  3. with open(path, "wb") as f:
  4. f.write(base64.b64decode(item["b64_json"]))

四、图像编辑:调用 /v1/images/edits

图像编辑接口与文生图最大的区别是请求格式。它要求使用 multipart/form-data 上传图片,不能像文生图那样用 JSON 提交。

  1. import os
  2. import requests
  3. BASE_URL = os.environ["STEP_BASE_URL"]
  4. API_KEY = os.environ["STEP_API_KEY"]
  5. def edit_image(image_path: str, prompt: str, size: str = "1024x1024") -> dict:
  6. with open(image_path, "rb") as f:
  7. files = {"image": (os.path.basename(image_path), f, "image/png")}
  8. data = {
  9. "model": "step-image-edit-2",
  10. "prompt": prompt,
  11. "n": "1",
  12. "size": size,
  13. "response_format": "url",
  14. }
  15. resp = requests.post(
  16. f"{BASE_URL}/images/edits",
  17. headers={"Authorization": f"Bearer {API_KEY}"},
  18. files=files,
  19. data=data,
  20. timeout=180,
  21. )
  22. resp.raise_for_status()
  23. return resp.json()
  24. if __name__ == "__main__":
  25. result = edit_image("./input.png", "把背景换成日落海滩,保留人物姿态与服装细节")
  26. item = result["data"][0]
  27. print(item.get("url") or "返回的是 b64_json 字段")

edits 接口同样返回 data 数组,字段与文生图一致。取值时应使用 result["data"][0]["url"]。如果写成 result["data"]["url"],Python 会因为对列表使用字符串索引而报错。

curl 版本

  1. curl -X POST "$STEP_BASE_URL/images/edits" \
  2. -H "Authorization: Bearer $STEP_API_KEY" \
  3. -F "model=step-image-edit-2" \
  4. -F "image=@input.png" \
  5. -F "prompt=把背景换成日落海滩,保留人物姿态与服装细节" \
  6. -F "size=1024x1024" \
  7. -F "n=1" \
  8. -F "response_format=url"

curl 版本与 Python 示例保持一致,都显式指定了 response_format。拿到 URL 后同样需要及时转存。

五、参数说明

参数 必填 说明
model 是 固定为 step-image-edit-2
prompt 是 生成或编辑指令。编辑场景建议描述希望达到的结果,而不是描述原图的样子
image edits 必填 待编辑的原图文件,常见格式为 PNG 或 JPG。原图分辨率和主体清晰度会直接影响效果。多图输入及文件大小限制以开放平台文档为准
n 否 生成数量。批量出图时费用会随数量线性增加
size 否 输出尺寸,取值需与平台支持的档位一致
response_format 否 url 或 b64_json。使用 url 时需要及时转存

尺寸档位和其他枚举值可能随版本更新,请以开放平台的最新文档为准。

六、提示词写法

图像编辑结果的好坏,很大程度上取决于提示词。下面三条经验在实际调用中比较有用。

第一,只描述目标状态,不描述操作过程。写”背景为日落海滩”比写”把背景删掉再加上海滩”更稳定。模型更擅长理解最终画面,而不是中间步骤。

第二,显式声明保留项。例如”保持人物面部、发型与服装不变”,可以明显减少无关区域被重绘的情况。

第三,一次只改一个维度。同时要求换背景、换风格、改构图,各项指令容易互相干扰。拆成多次串行编辑,每一步都更容易检查。

可以把这三条整理成固定模板,方便团队复用:

  1. 目标状态:背景为日落时分的海滩,海浪轻拍沙滩
  2. 保留项:保持人物面部、发型、姿态与服装不变
  3. 约束:只修改背景,不调整光线方向与人物肤色

对于电商主图换背景、素材风格统一这类批量任务,可以把模板与业务字段做映射,由程序拼装提示词后循环调用,并对结果做人工抽检。

七、常见问题排查

现象 常见原因 处理方式
401 Unauthorized API Key 错误,或 Header 缺少 Bearer 前缀 检查 Header 格式和密钥是否有效
403 或提示无权限 账户未开通该模型 在控制台确认模型调用权限
429 Too Many Requests 触发 QPS 或并发限制 加入指数退避重试,并控制并发数
400 参数错误 size 取值不支持,或 n 超出范围 对照文档修正枚举值
edits 报格式错误 误用 JSON 提交图片 改为 multipart/form-data
返回的 URL 打不开 链接已过期 收到结果后立即下载到自有对象存储
解析结果时报 TypeError 把 data 当成对象读取 data 是数组,应使用 data[0]
编辑后主体被改动 prompt 没有声明保留项 补充”保持……不变”类约束

生产环境建议统一封装一层客户端,内置超时、重试、限流、结果转存和调用日志。这样厂商 SDK 的细节就不会散落在业务代码中,后续更换模型时改动也更小。

八、成本与选型

图像模型的实际支出等于单次调用价格乘以调用次数。调用次数常被”反复重试出图”放大,因此控制成本可以从三方面入手。

  1. 先小批量评测,再扩大规模。可以用二三十张真实业务样本跑对比,重点看可用率,也就是结果能直接使用的比例,而不是只看单张效果。
  2. 建立多模型路由。简单编辑使用性价比较高的模型,复杂指令再切换到能力更强的模型。
  3. 按业务线和场景给调用打标签并统计消耗。只有分开统计,才能发现某个场景的异常增长。

如果同时使用多家厂商的图像模型,可以在百度智能云词元所(https://cloud.baidu.com/product-s/token_exchange.html?from=article)上对比不同模型的调用方式与计费口径,减少逐家对接的工作量。

九、小结

Step Image Edit 2 的接入路径很清楚。模型 ID 为 step-image-edit-2,/v1/images/generations 负责文生图,/v1/images/edits 负责基于原图的指令编辑,鉴权统一使用 Bearer API Key。

落地时重点关注三件事。edits 必须使用表单上传,返回的 data 是数组,图片 URL 需要及时转存。写好提示词,明确目标状态和保留项,也能显著提高可用率。把这些做好后,再配合统一封装的客户端,就能把图像生成能力稳定接入电商、营销素材和内容生产等业务场景。