API Reference

Images

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

Image generation and image editing APIs

Images routes currently enter the OpenAI platform orchestration chain.

Image Generations

openai

POST/v1/images/generations

Request

schema

modelstringRequired

Available image generation model ID.

promptstringRequired

Image generation prompt.

sizestringOptional

Output size. Supported values depend on the model, such as 1024x1024, 1024x1536, 1536x1024, or auto.

qualitystringOptional

Quality tier. Supported values depend on the model, such as auto, standard, hd, high, medium, or low.

backgroundstringOptional

Background control for models that support transparency or background settings, such as auto, transparent, or opaque.

nintegerOptional

Number of images. Limits depend on the model.

moderationstringOptional

Content moderation strength. Support depends on the upstream.

output_compressionintegerOptional

Output compression quality, usually for jpeg/webp.

response_format / output_formatstringOptional

Return URL, base64, or a requested image format such as png, jpeg, or webp when supported upstream.

userstringOptional

Client-side user identifier. Do not include sensitive data.

Response

schema

Usually returns image URLs or base64 data. Concrete fields and formats depend on the upstream image model.

createdintegerOptional

Creation timestamp.

data[]array<object>Optional

Image result array, possibly including url, b64_json, revised_prompt, and similar fields.

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.

Image Generations

bashImage generations

Language

curl -i -X POST https://api.tokenbay.com/v1/images/generations \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-1.5","prompt":"a cat"}'

Image Edits

bashJSON image edit

Language

curl -i -X POST https://api.tokenbay.com/v1/images/edits \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_CONSOLE",
    "prompt": "Replace the background with a clean blue sky. Keep the main subject unchanged.",
    "images": [
      { "image_url": "https://example.com/input.png" }
    ],
    "size": "auto"
  }'

bashStreaming image edit (when supported)

Language

curl -i -N -X POST https://api.tokenbay.com/v1/images/edits \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -F "model=MODEL_ID_FROM_CONSOLE" \
  -F "image[]=@/path/to/image.png" \
  -F "prompt=place the subject in a cinematic landscape" \
  -F "stream=true"

Image Generations

Request

Response

Image Edits

Request

Response

Related