简介:想接入 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 表示地址,这样平台地址变化时只需修改配置,不必改动代码。
step-image-edit-2 的调用权限,并完成充值或额度领取。requests:
pip install requests
密钥应放在环境变量中,不要硬编码在代码里,避免提交到代码仓库后泄露:
export STEP_API_KEY="你的API Key"export STEP_BASE_URL="以开放平台文档为准的Base URL"
curl -X POST "$STEP_BASE_URL/images/generations" \-H "Authorization: Bearer $STEP_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "step-image-edit-2","prompt": "赛博朋克风格的城市夜景,霓虹灯反射在湿漉漉的街道上,电影感光影","n": 1,"size": "1024x1024","response_format": "url"}'
如果返回结果正常,说明密钥、模型权限和网络都已通过检查。
下面的示例包含超时设置、状态码检查和结果解析。
import osimport requestsBASE_URL = os.environ["STEP_BASE_URL"]API_KEY = os.environ["STEP_API_KEY"]def text_to_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:resp = requests.post(f"{BASE_URL}/images/generations",headers={"Authorization": f"Bearer {API_KEY}"},json={"model": "step-image-edit-2","prompt": prompt,"n": n,"size": size,"response_format": "url",},timeout=120,)if resp.status_code != 200:raise RuntimeError(f"{resp.status_code} -> {resp.text}")return resp.json()if __name__ == "__main__":data = text_to_image("一只戴着宇航头盔的柴犬,扁平插画风")for idx, item in enumerate(data["data"]):print(idx, item.get("url") or item.get("b64_json", "")[:64])
图片信息放在 data 数组中,即使只生成一张图,也要通过 data[0] 取值。response_format 为 url 时读取 url 字段。为 b64_json 时读取 base64 字符串并解码。
返回的图片链接通常有有效期,拿到结果后应尽快下载到自有存储。下面是一个简单的转存函数:
import requestsdef save_url_image(url: str, path: str) -> None:resp = requests.get(url, timeout=60)resp.raise_for_status()with open(path, "wb") as f:f.write(resp.content)
如果使用 b64_json,可以直接解码落盘:
import base64def save_b64_image(item: dict, path: str) -> None:with open(path, "wb") as f:f.write(base64.b64decode(item["b64_json"]))
图像编辑接口与文生图最大的区别是请求格式。它要求使用 multipart/form-data 上传图片,不能像文生图那样用 JSON 提交。
import osimport requestsBASE_URL = os.environ["STEP_BASE_URL"]API_KEY = os.environ["STEP_API_KEY"]def edit_image(image_path: str, prompt: str, size: str = "1024x1024") -> dict:with open(image_path, "rb") as f:files = {"image": (os.path.basename(image_path), f, "image/png")}data = {"model": "step-image-edit-2","prompt": prompt,"n": "1","size": size,"response_format": "url",}resp = requests.post(f"{BASE_URL}/images/edits",headers={"Authorization": f"Bearer {API_KEY}"},files=files,data=data,timeout=180,)resp.raise_for_status()return resp.json()if __name__ == "__main__":result = edit_image("./input.png", "把背景换成日落海滩,保留人物姿态与服装细节")item = result["data"][0]print(item.get("url") or "返回的是 b64_json 字段")
edits 接口同样返回 data 数组,字段与文生图一致。取值时应使用 result["data"][0]["url"]。如果写成 result["data"]["url"],Python 会因为对列表使用字符串索引而报错。
curl -X POST "$STEP_BASE_URL/images/edits" \-H "Authorization: Bearer $STEP_API_KEY" \-F "model=step-image-edit-2" \-F "image=@input.png" \-F "prompt=把背景换成日落海滩,保留人物姿态与服装细节" \-F "size=1024x1024" \-F "n=1" \-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 时需要及时转存 |
尺寸档位和其他枚举值可能随版本更新,请以开放平台的最新文档为准。
图像编辑结果的好坏,很大程度上取决于提示词。下面三条经验在实际调用中比较有用。
第一,只描述目标状态,不描述操作过程。写”背景为日落海滩”比写”把背景删掉再加上海滩”更稳定。模型更擅长理解最终画面,而不是中间步骤。
第二,显式声明保留项。例如”保持人物面部、发型与服装不变”,可以明显减少无关区域被重绘的情况。
第三,一次只改一个维度。同时要求换背景、换风格、改构图,各项指令容易互相干扰。拆成多次串行编辑,每一步都更容易检查。
可以把这三条整理成固定模板,方便团队复用:
目标状态:背景为日落时分的海滩,海浪轻拍沙滩保留项:保持人物面部、发型、姿态与服装不变约束:只修改背景,不调整光线方向与人物肤色
对于电商主图换背景、素材风格统一这类批量任务,可以把模板与业务字段做映射,由程序拼装提示词后循环调用,并对结果做人工抽检。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
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 的细节就不会散落在业务代码中,后续更换模型时改动也更小。
图像模型的实际支出等于单次调用价格乘以调用次数。调用次数常被”反复重试出图”放大,因此控制成本可以从三方面入手。
如果同时使用多家厂商的图像模型,可以在百度智能云词元所(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 需要及时转存。写好提示词,明确目标状态和保留项,也能显著提高可用率。把这些做好后,再配合统一封装的客户端,就能把图像生成能力稳定接入电商、营销素材和内容生产等业务场景。