Images (OpenAI-compatible)

The OpenAI Images contract, for drop-in use with the OpenAI SDKs: generations (JSON) creates an image from a prompt, and edits (multipart) edits a source image. Both are translated to the unified contract and served through the same routing and metering as the other endpoints.

This is the only images surface. There is no native /v1/images endpoint on the data plane.

Authentication

Authenticated with a secret key (rd_sk_…) or a client token (carrying the ai.images scope). A publishable key is rejected 403.

Shared parameters

Both endpoints accept these fields (the enum values are validated; an unsupported value fails 400 unsupported_parameter):

Field	Type	Required	Notes
`model`	string	yes	Resolved like chat completions.
`prompt`	string	yes	The image prompt.
`n`	integer	no	Capped at `1`; `n>1` is rejected.
`size`	string	no	`auto`, `1024x1024`, `1536x1024`, `1024x1536`.
`quality`	string	no	`auto`, `low`, `medium`, `high`.
`background`	string	no	`auto`, `transparent`, `opaque` (`transparent` needs a `png`/`webp` output).
`output_format`	string	no	`png`, `jpeg`, `webp`.
`moderation`	string	no	`auto`, `low`.
`user`	string	no	Attributed as the end-user id.

POST /openai/v1/images/generations

POST https://gateway.roadie.paroaria.ai/openai/v1/images/generations
Authorization: Bearer rd_sk_prod_…
Content-Type: application/json

JSON body — the shared parameters, no source image:

{
  "model": "gpt-image-1",
  "prompt": "A watercolor fox in a misty forest",
  "size": "1024x1024",
  "output_format": "png"
}

POST /openai/v1/images/edits

POST https://gateway.roadie.paroaria.ai/openai/v1/images/edits
Authorization: Bearer rd_sk_prod_…
Content-Type: multipart/form-data

Multipart form — the shared parameters as form fields, plus the image file parts:

Part	Type	Required	Notes
`image`	file	yes	The source image to edit.
`mask`	file	no	An optional edit mask.

Each uploaded file is capped at 20 MiB (over which the upload is rejected 413); a maximum of two file parts are read.

Response

200 OK — an OpenAI Images response. The image bytes are always returned as base64 (b64_json), never a URL:

{
  "created": 1752931200,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANS…" }],
  "usage": {
    "total_tokens": 4160,
    "input_tokens": 160,
    "output_tokens": 4000,
    "input_tokens_details": { "text_tokens": 160, "image_tokens": 0 }
  }
}

created is fixed by the gateway at request start (it never leaks a provider timestamp). data always holds exactly one image (n is capped at 1). The gateway request id is on the X-Request-Id response header.

Errors

Errors use the OpenAI envelope; see the error mapping on the chat-completions page. A model that does not support image generation returns 404 invalid_request_error (images_not_supported).

Introduction

Data plane

OpenAI-compatible

Control plane

Errors

Images (OpenAI-compatible)

Authentication

Shared parameters

POST /openai/v1/images/generations

POST /openai/v1/images/edits

Response

Errors

​Authentication

​Shared parameters

​POST /openai/v1/images/generations

​POST /openai/v1/images/edits

​Response

​Errors

Authentication

Shared parameters

POST /openai/v1/images/generations

POST /openai/v1/images/edits

Response

Errors