Image API

Generate or edit images with GPT Image and Gemini image models available to an Essevin consumer key.

Essevin provides one OpenAI Images-compatible request shape for the image models enabled on the current key. Discover the exact model ID first; do not assume that every image model in the broader catalog is available.

Item	Value
Base URL	`https://api.essevin.com/v1`
Generate	`POST /v1/images/generations`
Edit	`POST /v1/images/edits` when returned model capabilities include editing
Async status	`GET /v1/images/tasks?task_id=...` after a `202 Accepted` response
Authentication	`Authorization: Bearer <matching plan key>`

1. Find an enabled image model

curl https://api.essevin.com/v1/models \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY"

Choose an exact returned ID with image capability. Representative IDs include gpt-image-2, gemini-2.5-flash-image, and gemini-3-pro-image; availability depends on the key group.

2. Generate one image

curl https://api.essevin.com/v1/images/generations \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a ceramic cup on a white table",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'

The response URL is temporary. Download it into the application's existing storage when the result must persist.

Image input and editing

Image capabilities differ by model. Check GET /v1/models, then use only fields supported by the selected route:

Input	Use
`image` URL or Data URL in generation JSON	Image-to-image or reference-image generation when supported
`/v1/images/edits` multipart request	Existing OpenAI edit integrations when supported
`prompt`	Describe the requested change and the details that must stay unchanged

Edit a local image with multipart

curl https://api.essevin.com/v1/images/edits \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Move the cup to the right and keep the label unchanged" \
  -F "[email protected]" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

Gemini image compatibility

Gemini image models keep the same client-side OpenAI Images protocol, but their model capabilities are not identical to GPT Image.

Capability	Behavior
Request	Call `/v1/images/generations`; Essevin adapts the request for the selected Gemini model.
Response	Read standard OpenAI Images JSON from `data[].b64_json` or `data[].url`.
Editing	Models with editing capability accept one or more references through `/v1/images/edits`; Gemini does not support a hard-region `mask`.
Size	The gateway validates `size` against the selected model before generation.
Optional fields	`quality`, `background`, `output_format`, `input_fidelity`, and `n` depend on the model.
Streaming	Keep Gemini image requests synchronous; do not send `stream: true`.
Async	Some models honor `Prefer: respond-async`; use the HTTP status to distinguish `202 task_id` from a synchronous result.

Use ESSEVIN_GEMINI_API_KEY when the selected image model belongs to the Gemini plan group. Preserve a complete model ID, including any suffix, exactly as returned by GET /v1/models.

Common request fields

Field	Required	Description
`model`	Yes	A complete GPT Image or Gemini image ID returned for the current key
`prompt`	Yes	Image content, composition, style, text, or editing instructions
`size`	No	`auto` or `WIDTHxHEIGHT`; support varies by model
`quality`	No	`low`, `medium`, `high`, or `auto` when supported
`n`	No	Number of images; some models only support `1`
`background`	No	`opaque` or `transparent` when supported
`output_format`	No	`png`, `jpeg`, or `webp` when supported
`image` / `mask`	For editing	One or more references may be accepted; `mask` support is model-specific and is not available for Gemini

Unsupported sizes and fields should return a validation error before generation. On 400, compare the request with the capabilities returned for the selected model instead of retrying blindly.

Response modes

Synchronous response

Without Prefer: respond-async, the request waits for completion and returns standard OpenAI Images JSON. Some models return base64 data and others return a temporary URL.

{
  "created": 1780000000,
  "data": [{
    "b64_json": "iVBORw0KGgoAAA...",
    "revised_prompt": "..."
  }],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

A non-Gemini image model may expose Images SSE when stream: true is supported. The last data: event contains the Images JSON and is followed by [DONE]. Keep official SDK and Gemini image requests in the default synchronous mode.

Asynchronous task response

For a model that supports asynchronous work, send Prefer: respond-async. A 202 Accepted response includes task_id and status_url; poll until the status is completed or failed. A model may still return synchronously, so branch on the actual HTTP status.

# Submit and inspect the HTTP status plus task_id.
curl -i https://api.essevin.com/v1/images/generations \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic city at night",
    "size": "2048x2048"
  }'

# Poll only after the first response returns 202 and a task_id.
curl "https://api.essevin.com/v1/images/tasks?task_id=your-task-id" \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY"

Keep the first validation small

Request one image at the lowest useful resolution. Do not log the API key, complete Data URLs, private source images, or full base64 output.

Before publishing generated commerce assets, verify labels, logos, package text, product proportions, and any people shown in the result.

On this page