Image-to-image editing

Image-to-image means handing the model one or more reference images plus an edit instruction and getting a new image back (recolour, swap elements, style transfer, multi-image composition). The platform exposes two endpoints, both on the same pipeline underneath:

Both endpoints share the same models, billing, channel ladder, Idempotency-Key handling and error shape — /v1/images/edits simply normalises multipart into the same JSON envelope and continues down the same path. The one behavioural difference: on /v1/images/edits a request without a reference is rejected with 400 (a missing reference is a caller bug there, and it will never silently degrade into text-to-image), while /v1/images/generations without image is just an ordinary text-to-image call.

Correction to earlier docs (2026-08-02): this page used to state that gpt-image-2 was text-to-image only and that the platform had no /v1/images/edits. That conclusion was wrong — we had only probed the upstream's /images/generations (references are parsed only on its edits surface), so a gap in our own configuration got recorded as a limit of the model. gpt-image-2 image-to-image is now live and production-verified, on both endpoints.

Route 1: gpt-image-2 (recommended)#

gpt-image-2 accepts both public URLs and base64 data URIs, works on both endpoints, costs $0.059 per image, and does not charge for reference images (one reference or ten, same price).

The request (/v1/images/generations)#

{
  "model": "gpt-image-2",
  "prompt": "Make the sofa blue, leave everything else unchanged. Aspect ratio: 3:2 (landscape)",
  "image": ["https://your-host.com/original.png"]
}

curl#

curl https://zhonkezhonkeapi.dflop.top/v1/images/generations \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Make the sofa blue, leave everything else unchanged. Aspect ratio: 3:2 (landscape)",
    "image": ["https://your-host.com/original.png"]
  }'

The response is the OpenAI Images shape, with data[].url holding the edited image (verbatim from a live call):

{
  "created": 1765432100,
  "expires_at": 1765518500,
  "data": [
    {
      "url": "https://r2.dflop.top/gateway/images/ephemeral/ab2f1e08-....png",
      "revised_prompt": "..."
    }
  ],
  "usage": {
    "input_tokens": 1103,
    "input_tokens_details": { "image_tokens": 1024, "text_tokens": 79 },
    "output_tokens": 229,
    "total_tokens": 1332
  }
}

usage.input_tokens_details.image_tokens > 0 means the reference was actually consumed. It's the most reliable machine-checkable signal that editing really took effect — if it's 0 and the image still changed, the model redrew from your prompt rather than editing your picture. Measured: one 768×768 reference = 1024, one 1254×1254 = 1521. (With 8 or more references the upstream's usage accounting collapses to 0; that's a bug in its statistics, not a dropped reference.)

⚠️ data[] carries no size field here (unlike Seedream) — decode the image if you need its dimensions.

With the official OpenAI SDK (/v1/images/edits, upload the file directly)#

No need to base64 anything yourself — the SDK's images.edit() sends multipart, which this platform accepts natively:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PLATFORM_API_KEY"],
    base_url="https://zhonkezhonkeapi.dflop.top/v1",
    timeout=300.0,                      # gpt-image-2 measurably takes 30–215s; don't use the default timeout
)

result = client.images.edit(
    model="gpt-image-2",
    image=open("original.png", "rb"),   # several references: [open(a, "rb"), open(b, "rb")]
    prompt="Make the sofa blue, leave everything else unchanged. Aspect ratio: 3:2 (landscape)",
)
print(result.data[0].url)

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PLATFORM_API_KEY,
  baseURL: "https://zhonkezhonkeapi.dflop.top/v1",
  timeout: 300_000,
});

const result = await client.images.edit({
  model: "gpt-image-2",
  image: fs.createReadStream("original.png"),
  prompt: "Make the sofa blue, leave everything else unchanged. Aspect ratio: 3:2 (landscape)",
});
console.log(result.data[0].url);

Plain curl over multipart works the same way (field name image, or image[] for several):

curl https://zhonkezhonkeapi.dflop.top/v1/images/edits \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  --max-time 300 \
  -F "model=gpt-image-2" \
  -F "prompt=Make the sofa blue, leave everything else unchanged" \
  -F "image[][email protected]" \
  -F "image[][email protected]"

Reference not publicly reachable? Send a data URI#

When you pass a reference as a URL, the server fetching that URL is the upstream's, not our gateway's — the fact that you can open it, or that we can, says nothing about whether the upstream can. Object storage inside China, intranet addresses, image hosts behind auth or bot protection, short-lived signed links: the typical symptom is an upstream 400, Unable to download content from the provided URL.

When that happens, send the bytes (data URI, or the multipart form above) rather than fighting the URL:

B64=$(base64 -i original.png | tr -d '\n')
curl https://zhonkezhonkeapi.dflop.top/v1/images/edits \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d "{
    \"model\": \"gpt-image-2\",
    \"prompt\": \"Make the sofa blue, leave everything else unchanged\",
    \"image\": [\"data:image/png;base64,$B64\"]
  }"

Size and aspect ratio: size does nothing for gpt-image-2 — put it in the prompt#

The upstream does not honour the size field for gpt-image-2 (ask for 1536x1024 and you may get a 902×1744 portrait). What measurably does work is writing the ratio into the prompt, and it lands reliably:

Make the sofa blue, leave everything else unchanged. Aspect ratio: 16:9 (landscape)

• A ratio in the prompt overrides the size field when the two disagree
• Common forms: 1:1 (square), 3:4 (portrait), 16:9 (landscape), 9:16 (portrait)
• Don't put 8K / 4K in the prompt — it doesn't raise the actual pixel count and only disturbs composition
• Other models (Seedream / Nano) honour size normally; this only applies to gpt-image-2

Multiple reference images#

The image array is forwarded in written order, and that order is part of the contract (composition instructions like "the character from the first, the background from the second" depend on it). Forty references still read back accurately down to the last one, so the real ceiling isn't the count but the request body size:

• The gateway's body limit is 95 MB, and base64 inflates bytes by roughly 33%
• Real phone photos run ~3 MB each, which puts the practical ceiling around 20 images
• Billing is independent of the reference count: one or forty, it's the same $0.059 per generated image

Cost and latency#

⚠️ A short client timeout (the usual 60s / 120s defaults) will cut off a request the gateway is still legitimately waiting on: you are billed, and you never receive the image.

Verification status of the examples on this page (2026-08-04): all three shapes — generations + data URI, edits + multipart file, generations + a public URL (using the image_urls spelling) — returned HTTP 200 with image_tokens > 0, and the output preserved elements of the reference that the prompt never mentioned (only the object named in the prompt changed colour). That is the reference genuinely being read and edited, not redrawn from the prompt. Feeding a previous result's URL back in as the reference (chained editing) works too.

Route 2: Seedream / Nano-Banana#

Same /v1/images/generations endpoint, references in the same image array. Best when you want batches (n > 1) or a lower unit price.

Models that can edit#

Reference-image input formats differ slightly per model, so a publicly reachable https URL is the safest bet (every model accepts one). data-URIs are accepted by the whole Seedream line, nano-banana-2 and gpt-image-2.

The request#

{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "Make the sofa blue, leave everything else unchanged",
  "image": ["https://your-host.com/original.png"],
  "size": "2048x2048"
}

image can also be written as image_urls (equivalent). With several references, the upstream treats the first as the primary edit target and the rest as style or element references.

curl#

curl https://zhonkezhonkeapi.dflop.top/v1/images/generations \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "Make the sofa blue, leave everything else unchanged",
    "image": ["https://your-host.com/original.png"],
    "size": "2048x2048"
  }'

The response#

The same OpenAI Images shape as text-to-image, with data[].url holding the edited image:

{
  "model": "doubao-seedream-4-5-251128",
  "created": 1765432100,
  "data": [{ "url": "https://...", "size": "2048x2048" }],
  "usage": { "generated_images": 1 }
}

Route 3: GPT-5.x chat with the image_generation tool#

When what you actually need is for the model to understand the picture before deciding how to change it, use the built-in image_generation tool on a gpt-5.x chat model and pass the reference as a multimodal message. This route bills per token and suits edits that need semantic understanding.

The request#

curl https://zhonkezhonkeapi.dflop.top/v1/chat/completions \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "stream": true,
    "tools": [{ "type": "image_generation" }],
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "Make the sofa in this image blue, leave the rest alone" },
        { "type": "image_url", "image_url": { "url": "https://your-host.com/original.png" } }
      ]
    }]
  }'

The response#

The edited image arrives inline in the streamed body, as markdown image syntax:

data: {"choices":[{"delta":{"content":"![](https://...generated...)"}}]}

Regex ![](url) out of the accumulated delta.content to get the link.

This route bills by token, not per image: an image_generation turn carries a fixed overhead of roughly 2,300 input tokens, plus the vision tokens for any reference image (roughly doubling it), with very few output tokens.

Which route to pick#

For ordinary edits — recolouring, swapping elements, style transfer — pick route 1 when you want GPT's look and multi-image composition, and route 2 when you want exact dimensions, speed, or batches.

Limitations#

• Returned image URLs are always temporary: gpt-image-2 measurably serves platform-hosted r2.dflop.top/gateway/images/ephemeral/… links (swept after 24 hours; expires_at is the exact moment), while Seedream / Nano usually return upstream pre-signed links (about 24 hours). Neither is permanent hosting — download and store them promptly.
• When a reference is a URL, that URL must be reachable from the upstream's network; if it can't be fetched you get the upstream's 400, and the fix is a data URI or a multipart upload.
• The request body limit is 95 MB (base64 inflates size by roughly 33%).
• gpt-image-2 ignores the size field upstream — put the aspect ratio in the prompt.
• /v1/images/edits without a reference returns 400 with `image` is required on /v1/images/edits (not billed); use /v1/images/generations for text-to-image as the message says.
• Generation is slow (30–215 seconds for gpt-image-2 in particular), so set your client timeout to ≥ 300 seconds.
• To retry without being charged twice, send an Idempotency-Key (supported on both endpoints; the same key replays the first response and is not billed again) — see Image / video / music APIs.
• If your key has an allowed_models allowlist, add the editing model to it first or you'll get a 403.
• Full image / video / music endpoint documentation: Image / video / music APIs.