Image API

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 <Images 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, gpt-image-2.5-flare, and gpt-image-2.5-sunburst; use a key created with the Images purpose.

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"

Common request fields

Field	Required	Description
`model`	Yes	A complete GPT 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

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. Read data[].b64_json or data[].url: 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
  }
}

An 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 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