Image edits

The step-1x-edit model is temporarily free to use.

Edit an image based on the input image and prompt.

Endpoint

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

Request parameters

model string required
Model name (currently step-1x-edit).
image file required
Single image file. Resolution: min 64px, max 1728px, max area 1024x1024.
Formats: jpg, png, webp.
Max size: 10 MB. Aspect ratio between 1:3 and 3:1.
prompt string required
Text description (max 512 characters).
seed int optional
Random seed (0 or omitted uses a random seed).
steps int optional
Steps 1–100 (default 28).
cfg_scale float optional
Classifier-free guidance scale 1–10 (default 6).
size string optional
Approximate output size. Default 512x512. Options: 512x512, 768x768, 1024x1024.
Logic:
1. If input image is 1:1, output follows size.
2. If not 1:1, output keeps input aspect ratio with area ~ size*size.
response_format string optional
Return format: b64_json or url (default url).

Response

created int — Timestamp (seconds).
data object array — Results:
- seed int — Seed used.
- finish_reason string — success or content_filtered.
- b64_json string — Base64 image (when response_format = b64_json).
- url string — Download link (when response_format = url).


{
	"created": 1589478378,
	"data": [
		{
			"b64_json": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1",
			"finish_reason": "success",
			"seed": 123838
		}
	]
}

Examples


import base64
from openai import OpenAI
 
client = OpenAI(api_key=STEP_API_KEY, base_url="https://api.stepfun.ai/v1")
 
prompt = "Turn the cat into a British Shorthair."
 
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.ai/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: "Turn the cat into a British Shorthair.",
  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);

Response


{
	"id": "745f66ca7f11cd5424f06b106e2e5bed.5c51cd6a807226cbd4a88c4bffe8aa38",
	"created": 1752565891,
	"data": [
		{
			"url": "https://res.stepfun.com/image_gen/20250715/sample.png",
			"finish_reason": "success",
			"seed": 1
		}
	]
}


curl -X POST "https://api.stepfun.ai/v1/images/edits" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -F "model=step-1x-edit" \
  -F "image=@cat.jpg" \
  -F "response_format=url" \
  -F 'prompt=Turn the cat into a British Shorthair.'