Image Editing

Image editing lets applications send image-plus-prompt editing requests through AISIX while keeping caller authentication, model aliases, upstream credentials, and request-side policy in one gateway path.

Editing models such as gpt-image-2 take the source image or images, an optional mask, the prompt, and every tuning parameter in one multipart/form-data body. AISIX reads the form, resolves the caller-facing model alias, rewrites the model field to the upstream model ID, rebuilds the form with every other part byte-for-byte intact — aside from prompt text a mask-action guardrail rule rewrites, described below — and forwards it to the upstream image-editing endpoint.

In this guide, you will edit an image through AISIX and review the request shape and provider requirement for this endpoint.

Prerequisites

Before starting, prepare the following:

• A running AISIX gateway that can serve proxy requests.
• A caller API key that can access the model alias.
• A model alias whose configured provider is OpenAI and whose upstream model_name is an image-editing model such as gpt-image-2. The examples use the alias image-edit-prod.
• A source image file to edit. The example uses original.png.

Export the gateway connection and request values:

# AISIX_PROXY has no trailing slash or endpoint path such as /v1.
# The local quickstarts use http://127.0.0.1:3000.
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="image-edit-prod"

Send an Image Edit Request

Send the edit request through the gateway proxy as a multipart form with the AISIX model alias in the model field:

curl -sS -X POST "${AISIX_PROXY}/v1/images/edits" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -F "model=${AISIX_MODEL}" \
  -F "image=@original.png" \
  -F "prompt=Add a red hat to the subject" \
  -F "size=1024x1024" \
  -o aisix-image-edit-response.json

AISIX resolves the model alias, checks the caller API key, runs supported input policy checks on the prompt, rewrites the model form field to the upstream model ID, and forwards the rebuilt form — the image bytes, filenames, and every other field unchanged unless a mask-action guardrail rule rewrote the prompt — to the upstream image-editing endpoint.

The response keeps the OpenAI image format. Editing models return base64 image data and a token usage block:

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "..."
    }
  ],
  "usage": {
    "input_tokens": 50,
    "output_tokens": 1056,
    "total_tokens": 1106
  }
}

Check that the response includes one image item:

jq '.data | length' aisix-image-edit-response.json

The command should print:

1

Request Fields

The route accepts multipart/form-data only. A JSON body returns 400 in the gateway's error envelope.

Field	Required by	Meaning
model	Gateway	The AISIX model alias. The only field AISIX always rewrites; a configured mask-action guardrail rule can also rewrite prompt.
image	Provider	The source image file. The field can repeat for models that accept multiple input images; AISIX forwards every part in order with its bytes and filename intact.
prompt	Provider	The edit instruction. Input guardrails inspect and can mask this text before the request goes upstream.
mask	—	An optional mask image whose transparent areas mark the region to edit. Forwarded intact.

Every other form field — n, size, quality, background, input_fidelity, and any parameter the provider adds later — is forwarded verbatim, so new upstream parameters do not require a gateway upgrade. Unset fields are simply absent from the upstream request.

note

stream=true is not supported on this route. Editing models can stream partial images as server-sent events, but AISIX does not yet relay that stream and rejects the request with 400 instead of silently buffering it.

OpenAI Provider Requirement

The image-editing route is provider-specific. AISIX accepts it only when the resolved model is configured with the OpenAI provider.

This is stricter than using the OpenAI-compatible adapter. An OpenAI-compatible vendor can work on the chat-completions route and still be rejected on the image-editing route because its configured provider is not OpenAI.

When the resolved model is not configured with the OpenAI provider, AISIX returns 400 before sending anything upstream.

The upstream URL derives from the provider key the same way as the other OpenAI routes: an unset api_base resolves to the standard OpenAI API, and a bare-host api_base gets /v1 appended before the endpoint path.

Image-Editing Behavior

Input guardrails inspect every prompt form field before AISIX calls the provider, and mask-action rules rewrite the prompt text in place. A blocked prompt returns 422 before any upstream call and does not consume the model's rate-limit capacity. Image and mask bytes are not scannable text, and generated image bytes are not scanned by output guardrails.

Submissions count against both the caller API key layers and the model's rate limits. When the upstream response includes a token usage block — gpt-image models return one — AISIX records those tokens and counts them toward token-based limits; a response without one records zero tokens. Per-image cost details such as image count, size, and quality are not inferred by this proxy path.

Errors

Failures return the gateway's JSON error envelope. A 4xx from the provider — for example, a size value the model rejects — is relayed with the provider's own status and message and is not listed below; the table covers the statuses AISIX generates itself.

Status	When
400	The body is not valid multipart/form-data, the model field is missing, stream=true is set, or the resolved model's provider is not OpenAI.
401	The caller API key is missing or invalid.
403	The caller API key is not allowed to use the model alias, or the request comes from a client IP outside the model's allowlist.
404	The model alias does not resolve.
413	The request body exceeds the configured request-body limit.
422	An input guardrail blocked the prompt. No provider request is sent.
429	A rate limit or budget rejected the request.
502	The provider returned a server error or a response that is not valid JSON, or was unreachable.
504	The provider did not answer within the model's request timeout.

Next Steps

You have now seen how AISIX proxies OpenAI image-editing requests and how the multipart form travels through the gateway. Continue with Image Generation for the prompt-to-image route, or Speech and Audio for the other multipart surfaces.