Get Started →
GuideTool IntegrationsAPI ReferenceTerms & Policies
API ReferenceImage SeriesOpenAI FormatPOSTImage Editing
Image SeriesPOSTImage Edits
API Reference

Image Editing

POSThttps://api.tokenbay.com/v1/images/edits

Edit or extend an image using the OpenAI-compatible Images API

Creates an edited image from one or more source images and a text prompt. Use JSON image references or multipart/form-data for file uploads.

TokenBay currently catalogs gpt-image-1.5 and gpt-image-2 for /v1/images/edits. Request parameters vary by model and channel; gpt-image-2 currently rejects n for this route.

Image Edits

openai
POST/v1/images/edits

Request

schema

TokenBay reads model for routing and stream for response handling. JSON image references and multipart uploads are forwarded to compatible upstreams; multipart Content-Type, boundary, and body bytes are preserved unchanged.

modelstringRequired

Image editing model used for TokenBay routing. The model must be available on a configured OpenAI-compatible image-edit channel; use the console or Models API as the live source of availability.

image / imagesfile | file[] | array<object>Required

Source image input. For multipart, use image or repeated image[] / image[n] file parts. For JSON, use images[] entries with image_url or file_id when supported; accepted forms and limits are determined by the selected upstream model.

images[].image_urlstringOptional

Fully qualified image URL or data URL when supported by the upstream model.

images[].file_idstringOptional

Uploaded file ID when supported by the upstream model.

promptstringRequired

Description of the desired edit. Length and content limits are determined by the selected upstream model.

maskfile | objectOptional

Optional inpainting mask. Use a multipart file or a JSON object with image_url/file_id when supported; format, dimensions, transparency semantics, and size limits are determined by the selected upstream model.

mask.image_urlstringOptional

Mask URL or data URL when supported by the upstream model.

mask.file_idstringOptional

Uploaded mask file ID when supported by the upstream model.

sizestringOptional

Requested output image size. Accepted values are determined by the selected upstream model (for example, auto or model-specific width × height values); TokenBay forwards the value without validation.

streambooleanOptional

Set true to request a streaming response. Native upstream SSE is passed through; a successful complete JSON response is wrapped as text/event-stream.

Response

schema

Successful non-streaming responses normally use the OpenAI-compatible image response shape below. TokenBay does not add or rename fields; additional fields remain upstream-defined. With stream=true, the response is SSE and its event payloads depend on the upstream model and channel.

createdintegerOptional

Unix timestamp returned by upstream image services when provided.

backgroundstringOptional

Background mode returned by the upstream image model, when provided.

output_formatstringOptional

Output image format returned by the upstream image model, when provided.

qualitystringOptional

Output quality returned by the upstream image model, when provided.

sizestringOptional

Actual output image size returned by the upstream image model; it may differ from a requested auto size.

data[]array<object>Optional

Edited image results in a successful non-streaming response. The array shape and returned fields remain upstream-defined.

data[].b64_jsonstringOptional

Base64-encoded image data.

data[].urlstringOptional

Image URL when the upstream returns one.

data[].revised_promptstringOptional

Revised prompt when the upstream returns one.

usageobjectOptional

Upstream usage details when provided; TokenBay does not synthesize or normalize this object.

usage.input_tokensintegerOptional

Input token count when returned upstream.

usage.output_tokensintegerOptional

Output token count when returned upstream.

usage.total_tokensintegerOptional

Total token count when returned upstream.

usage.input_tokens_details.image_tokensintegerOptional

Input image token count when returned upstream.

usage.input_tokens_details.text_tokensintegerOptional

Input text token count when returned upstream.

usage.output_tokens_details.image_tokensintegerOptional

Output image token count when returned upstream.

usage.output_tokens_details.text_tokensintegerOptional

Output text token count when returned upstream.

The current model catalog includes gpt-image-1.5 and gpt-image-2 for /v1/images/edits. Their accepted request parameters are not identical; other OpenAI-compatible image-edit models may be used when configured, while Gemini image models are rejected by this endpoint.

Model availability can change with account and channel configuration. Use the console or Models API as the live source of availability.

The n parameter is not a gateway-wide capability. In the current gpt-image-2 image-edit validation, sending n may be rejected; omit it for gpt-image-2 and send it only when the selected model and channel explicitly document support.

Streaming support is also model- and channel-dependent. The current public GPT Image 2 model metadata marks streaming unsupported, so do not send stream=true for gpt-image-2 unless the configured channel documents a different capability.

Additional multipart fields such as quality, input_fidelity, output_format, output_compression, and partial_images are forwarded without gateway normalization or validation. Their support, accepted values, defaults, and effects are defined by the scheduled upstream model and channel rather than by TokenBay Gateway.

JSON image-edit payloads such as images[].image_url or images[].file_id are forwarded for compatible upstreams, but their request schema is upstream-defined. Use multipart/form-data for standard file uploads.

Related

Image GenerationErrors