Image-to-image

Send a source image and a text prompt that describes the edit. The response contains the edited image. The request is synchronous. There is no task to poll.

Models

Model	Model ID	Use it for
FLUX.2 Klein 9B Edit	`nunchux-flux.2-klein-9b-edit`	Edits that must keep the identity of the subject.
FLUX.2 Klein 4B Edit	`nunchux-flux.2-klein-4b-edit`	The fastest edits. High-volume edit passes. The output follows the input image.
Qwen Image Edit 2511 Lightning	`nunchux-qwen-image-edit-2511`	Targeted edits: swap elements, change the style, edit text in the image. The recommended editing model.

See Choosing a model for a comparison, and Performance tiers for the tiers that each model serves.

Endpoint

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

Request

Every request must include your API key and a JSON content type. See Authentication.

string

required

Your API key.

string

required

Must be application/json.

string

required

The model that edits the image.Options: nunchux-flux.2-klein-4b-edit, nunchux-flux.2-klein-9b-edit, nunchux-qwen-image-edit-2511

string

required

The source image, as a data URI (for example data:image/png;base64,...) or as a public URL. Supported formats: PNG, JPEG, WebP. Maximum size: 10 MB. Each side must be at least 64 px. The aspect ratio must be no more extreme than 8:1 in either orientation. A remote URL must resolve to a public host. Nunchux does not follow redirects.

string

required

A text description of the edit. Say what to change, add or remove.

string

default:"radical_speed"

The balance of speed and cost. See Performance tiers.Options: radical_speed, radical_value

integer

required

Output width in pixels. Send it together with height. Range: 1 to 8192.

integer

required

Output height in pixels. Send it together with width. Range: 1 to 8192.

integer

default:1

The number of images to generate. Only 1 is supported.

string

default:"b64_json"

The format of the returned image.Options: url, b64_jsonIn both formats, Nunchux keeps the generated image for 7 days, so that it appears in your request history. Then Nunchux deletes it.

integer

The random seed. The same seed with the same parameters gives the same result.

Dimensions

Send width and height together. A request with only one of them returns a 400.
Every image-to-image model is priced per megapixel today and charges from the output area. A request with no dimensions returns a 400. The API does not use the source image size or a default size.
Both values must be integers. The string "1024" is rejected, not converted.
The source image is a reference, not a canvas. The model does not crop or stretch it to width and height. When the source ratio is different from the output ratio, the model re-frames the content.
Smaller source images process faster. Larger output images take longer to generate.

A minimal request body:

{
  "model": "nunchux-qwen-image-edit-2511",
  "url": "https://example.com/example.jpg",
  "prompt": "Transform into a watercolor painting",
  "tier": "radical_speed",
  "width": 1024,
  "height": 1024,
  "response_format": "b64_json"
}

Response

The response is JSON. The data array contains the edited image, as base64 data or as a URL.

integer

required

The Unix timestamp of the generation.

array

required

The generated items.

Show Item properties

string

The URL of the image. Returned when response_format is url.

string

The image as base64 data. Returned when response_format is b64_json.

string

required

The model that edited the image.

Base64 format

{
  "created": 1234567890,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAYAAAB/HSuDAAAACXBIWXMAAA7EAAAOxAGVKw4b..."
    }
  ],
  "model": "nunchux-qwen-image-edit-2511"
}

URL format

{
  "created": 1234567890,
  "data": [
    {
      "url": "https://example.com/edited-image.png"
    }
  ],
  "model": "nunchux-qwen-image-edit-2511"
}

To save a base64 result from cURL, add this pipe to the command:

# Replace output.jpg with the file name that you want.
| jq -r '.data[0].b64_json // error(.error.message // .detail // tostring)' | base64 -d > output.jpg

Example

# The media URL below is a placeholder. Point it at your own publicly
# reachable file before running this.
curl -X POST https://api.nunchux.ai/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NUNCHUX_API_KEY" \
  -d '{
    "model": "nunchux-qwen-image-edit-2511",
    "url": "https://example.com/example.jpg",
    "prompt": "Transform into a watercolor painting",
    "tier": "radical_speed",
    "width": 1024,
    "height": 1024,
    "response_format": "b64_json"
  }' | jq -r '.data[0].b64_json // error(.error.message // .detail // tostring)' | base64 -d > output.jpg

# The media URL below is a placeholder. Point it at your own publicly
# reachable file before running this.
import os
import base64
import requests

response = requests.post(
    "https://api.nunchux.ai/v1/images/edits",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["NUNCHUX_API_KEY"],
    },
    json={
        "model": "nunchux-qwen-image-edit-2511",
        "url": "https://example.com/example.jpg",
        "prompt": "Transform into a watercolor painting",
        "tier": "radical_speed",
        "width": 1024,
        "height": 1024,
    },
)

# Decode the base64 image and save it. Change output.jpg to any file name.
image_b64 = response.json()["data"][0]["b64_json"]
with open("output.jpg", "wb") as f:
    f.write(base64.b64decode(image_b64))

// The media URL below is a placeholder. Point it at your own publicly
// reachable file before running this.
import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.nunchux.ai/v1/images/edits", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.NUNCHUX_API_KEY,
  },
  body: JSON.stringify({
    model: "nunchux-qwen-image-edit-2511",
    url: "https://example.com/example.jpg",
    prompt: "Transform into a watercolor painting",
    tier: "radical_speed",
    width: 1024,
    height: 1024,
  }),
});
const data = await response.json();

// Decode the base64 image and save it. Change output.jpg to any file name.
await writeFile("output.jpg", Buffer.from(data.data[0].b64_json, "base64"));

# Replace photo.jpg with the path to your source image.
import os
import requests

from openai import OpenAI

client = OpenAI(
    base_url="https://api.nunchux.ai/v1",
    api_key=os.environ["NUNCHUX_API_KEY"],
)

response = client.images.edit(
    model="nunchux-qwen-image-edit-2511",
    image=open("photo.jpg", "rb"),
    prompt="Transform into a watercolor painting",
    response_format="url",
    extra_body={"width": 1024, "height": 1024},
)

# This tab returns a URL. Download it and save it. Change output.jpg to any file name.
image_url = response.data[0].url
with open("output.jpg", "wb") as f:
    f.write(requests.get(image_url).content)

Tips

Say exactly what to change, add or remove. The models can follow instructions with more than one change.
Use Qwen Image Edit 2511 when the edit must keep the identity of the subject, or when it changes text in the image.
Use FLUX.2 Klein 4B Edit for fast, high-volume edit passes.
Use radical_speed when response time is important. Use radical_value for large batches where cost per image is more important.
Send smaller source images for faster processing.

Errors and limits

Status	Code	Cause
400	none	A required field is missing, the model ID is not valid, or a value is not valid. The body is a plain `detail` string.
400	`engine_error`	The model cannot render the request, or the source image is rejected: the URL cannot be fetched, the data URI cannot be decoded, or the image is outside the size and ratio limits.
403	`model_not_available`	Your account does not have access to this model.
504	`engine_timeout`	Nunchux could not fetch the source image in time. Make sure that the URL is reachable and fast, or send the image as a data URI.

Refused requests

Nunchux charges only after a successful generation. A refused request is never billed.
Do not branch on a dimension-specific code. A refusal always carries the engine_error code.

For authentication, credit and rate-limit errors, see Error codes. Every request counts toward the requests-per-minute cap of your plan. See Rate limits.

Get started

Guides

Nunchux Optimized models

Partner models

Resources

Image-to-image

Image-to-image

Models

Endpoint

Request

Response

Example

Tips

Errors and limits

​Image-to-image

​Models

​Endpoint

​Request

​Response

​Example

​Tips

​Errors and limits

Image-to-image

Models

Endpoint

Request

Response

Example

Tips

Errors and limits