docs
// API Reference

Images

Text in, images out, on the OpenAI /v1/images/generations and /v1/images/edits shape. Point the OpenAI client at an image generation endpoint and images.generate and images.edit work unchanged. Every limit comes from the endpoint's model; a control the model cannot honor is refused with a 400, never silently dropped.

Overview

  • Generations, POST /v1/images/generations, renders images from a text prompt. JSON body.
  • Edits, POST /v1/images/edits, renders images from a prompt and one or more input images. multipart/form-data body.

Both routes authenticate with a project API key on the endpoint-scoped path and are served by an endpoint with task_mode image_generation, backed by a model tagged image_generation. Neither route streams. Requests are queued, routed and billed through the same pipeline as chat completions; while the image engine is busy, a request waits up to its tier's request timeout and images queued on one Erebine Inference Microservice (EIM) render in arrival order (see Queueing).

Image models are added and tuned on the Model Management page.

Quick Start

Replace the two highlighted placeholders before running any snippet on this page: the endpoint slug my-image-endpoint and the API key ere_myproject_your_api_key. The endpoint must be configured with task_mode = "image_generation".

curl
curl https://api.erebine.ai/proj_ABC123/my-image-endpoint/v1/images/generations \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "flux2-klein", "prompt": "A lighthouse on a cliff at dusk, oil painting", "size": "1024x1024" }'
Response
{ "background": "opaque", "created": 1793145600, "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." } ], "output_format": "png", "size": "1024x1024", "usage": { "input_tokens": 12, "input_tokens_details": { "image_tokens": 0, "text_tokens": 12 }, "output_tokens": 1000, "output_tokens_details": { "image_tokens": 1000, "text_tokens": 0 }, "total_tokens": 1012 } }

Generations

POST /:project_id/:endpoint_slug/v1/images/generations

Replace :project_id with your project external ID and :endpoint_slug with the slug of an image generation endpoint. The body is JSON, at most 1 MB. prompt is the only required field. model is advisory on this path: the endpoint's model renders the image whatever the field says. Unknown fields are ignored.

Edits

POST /:project_id/:endpoint_slug/v1/images/edits

The body is multipart/form-data, at most 32 MB of images. It carries the same fields as a generation as form fields, plus the files:

Part Type Description
image or image[] file Required. One or more input images, in order: PNG, JPEG, WebP or GIF (animated PNG is refused), at most 50 million pixels and 16384 pixels a side each. The count is capped by the model (see Sizes and Limits). The OpenAI SDKs send image for one file and image[] for a list.
mask file Optional. Validated as an image of the same formats and sent with the edit.

Edits need a model that takes input images. A generation-only model answers 400 unsupported_value on model. At size: "auto" an edit renders at the model's default size, not at the input image's size. Numeric form fields must parse as integers and stream as true or false; anything else answers 400 invalid_value naming the field.

Request Fields

Every field the OpenAI Images API defines is read. Fields this platform honors are passed to the model; fields it cannot honor are refused with 400 unsupported_value and the field in param, so a client never receives an image that ignored what it asked for.

Field Type Description
prompt string Required. The image description, at most 32,000 characters. Must not be blank.
model string Advisory on the endpoint-scoped path. On direct dispatch it addresses the deployment.
n integer Images to render, default 1. At least 1 and at most the model's per-request cap.
size string auto (default) or WIDTHxHEIGHT. See Sizes and Limits.
response_format string b64_json (default) or url. See b64_json and url.
output_format string png, jpeg or webp. Passed to the model.
output_compression integer Encoder quality, 0 to 100. Passed to the model.
background string auto or opaque. transparent is refused: these models render no alpha channel.
quality string auto or standard; the model has one quality. low, medium, high, hd, xhigh and max are refused.
moderation string auto only. Shared endpoints screen every prompt; see Prompt Screening.
user, safety_identifier string End-user identifier. The response echoes it as safety_identifier; safety_identifier wins when both are set.
style, input_fidelity string Refused when present.
stream, partial_images boolean, integer false and 0 only. Streaming is refused.

The model's inference steps, guidance scale and other engine parameters come from the model's image settings, never from the request.

Sizes and Limits

Each model has an image profile that sets how many images one request may ask for, how many input images an edit may carry, which sizes it renders, and the size auto renders. A model owner can override each value; see Model Management. The built-in profiles:

Model n max Input images Sizes auto
FLUX.2 klein 4B 4 up to 4 Free 1024x1024
Z-Image-Turbo 4 none Free 1024x1024
HiDream-O1-Image 1 none Fixed list 2048x2048
Any other image pipeline 1 as many as the engine declares for the pipeline, else none Free the checkpoint's default, else 1024x1024
  • Free sizes. Each side a multiple of 16 from 256 to 2048 pixels, at most 4 megapixels (one megapixel is 1024 x 1024 pixels). A size outside the range answers 400 invalid_value on size, and the message states the range.
  • Fixed list. Any well-formed WIDTHxHEIGHT renders at the listed size with the closest aspect ratio, since common clients send 1024x1024 to every model. The response's size reports what was rendered.
  • auto. Renders at the model's default size.

Response

A successful request answers 200 with the OpenAI ImagesResponse body and an X-Request-ID header.

Field Description
created Unix seconds.
data One object per image, each with b64_json or url, and revised_prompt when the model returned one.
background Always opaque.
output_format The encoding of the returned images, read from the image bytes.
size The rendered size, WIDTHxHEIGHT, read from the image bytes.
safety_identifier Present when the request set safety_identifier or user.
usage The tokens billed. See Usage and Billing.

quality is never written. Every returned image is checked before it leaves the platform: the format is read from its bytes, the dimensions from its header, and EXIF, GPS and text metadata are stripped. A model answer that is not a valid image answers 502.

b64_json and url

  • b64_json (default). Each image inline, base64-encoded.
  • url. Each image is stored and returned as a signed link, https://api.erebine.ai/v1/images/content/TOKEN. The link is valid for 60 minutes; after that the image is deleted and the link answers 404. It needs no API key: the token is the credential, bound to your project and the expiry, so treat the link as a secret for its lifetime. The image is served with its own Content-Type, Cache-Control: private until the link expires, and X-Content-Type-Options: nosniff. Every failure, an unknown, altered or expired token included, is the same 404.

Images are stored before anything is billed, so a storage failure answers 500 and costs nothing. A deployment without image storage refuses url with 400 unsupported_value on response_format; use b64_json there.

Usage and Billing

Images bill as tokens at the endpoint tier's input and output rates. The usage object reports exactly what is billed:

  • Output. 1,000 image tokens per megapixel of each returned image, read from the image itself, rounded up.
  • Input. The prompt at one token per four characters, rounded up, plus 250 image tokens per megapixel of each edit input image.

Before dispatch, a paid project holds credit for n images at the size the request will render (the default size for auto). A project that cannot cover the hold answers 402 before the prompt is screened or the model runs. The request settles on the images actually returned; a failed request releases its hold and bills no image. Prompt screening on a shared endpoint is a separate System 1 request, billed on its own.

Prompt Screening

On a shared endpoint every prompt is screened on a System 1 endpoint in your own project before any image is made; screening fails closed. Images on your own EIMs (a self-hosted tier) are not screened. Only the prompt is read; edit input images are not classified. The full rules are on Image Prompt Screening.

  • 400, type image_generation_user_error, code moderation_blocked: the prompt was refused. The message names the refused category and the request ID; it never repeats the prompt.
  • 400 screening_endpoint_required: the project has no usable System 1 endpoint serving an approved screening model, or none is approved on the platform. Not retryable until one is deployed.
  • 503 screening_unavailable: screening did not answer. Retry. On direct dispatch it is 429 with Retry-After.

Error Handling

Errors use the standard OpenAI error envelope. Refusals of a request field carry the field in param. The table lists the codes specific to the image routes; auth, quota and capacity errors are shared with every route (see Error Handling).

HTTP Status Error Code Description
400 model_not_image_generation The endpoint's task_mode is not image_generation, or its model is not an image pipeline.
400 invalid_request The body is not valid JSON, an edit is not multipart/form-data with a boundary, or prompt or image is missing.
400 invalid_value A value outside the API's or the model's range: n, size, prompt length, response_format, output_format, output_compression, too many or invalid input images, an invalid mask, or a form field that does not parse.
400 unsupported_value A value the API defines that this model cannot honor (see Request Fields), an edit on a generation-only model, or url on a deployment without image storage.
400 moderation_blocked, screening_endpoint_required See Prompt Screening.
402 insufficient_quota The project cannot cover the credit hold for the request.
404 not_found On GET /v1/images/content/TOKEN: the link is unknown, altered or expired.
500 internal_error A url image could not be stored. Not billed.
502 invalid_worker_response The model returned something that is not a valid image. Not billed.
503 screening_unavailable See Prompt Screening.

Client Examples

Python (OpenAI SDK)

Point base_url at the project and endpoint path; images.generate and images.edit work unmodified.

Python
import base64 from openai import OpenAI client = OpenAI( base_url="https://api.erebine.ai/proj_ABC123/my-image-endpoint/v1", api_key="ere_myproject_your_api_key" ) # Generate two images, returned inline result = client.images.generate( model="flux2-klein", prompt="A lighthouse on a cliff at dusk, oil painting", n=2, size="1024x768", output_format="webp" ) for index, image in enumerate(result.data): with open(f"lighthouse-{index}.webp", "wb") as out: out.write(base64.b64decode(image.b64_json)) print(result.usage.total_tokens) # Edit with two input images, returned as a signed link with open("room.png", "rb") as room, open("lamp.png", "rb") as lamp: edited = client.images.edit( model="flux2-klein", image=[room, lamp], prompt="Place the lamp on the side table", response_format="url" ) print(edited.data[0].url) # valid for 60 minutes

curl, an edit

curl
curl https://api.erebine.ai/proj_ABC123/my-image-endpoint/v1/images/edits \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -F model=flux2-klein \ -F "image[]=@room.png" \ -F "image[]=@lamp.png" \ -F prompt="Place the lamp on the side table" \ -F size=1024x1024 \ -F response_format=b64_json

Other Surfaces

The same endpoint, limits, screening and billing serve images on every surface:

  • Direct model dispatch: /v1/images/generations and /v1/images/edits under the _direct base, with model addressing an image generation deployment. Capacity refusals answer 429 with Retry-After.
  • Responses API: the image_generation tool.
  • Server-side tools: image generation in chat and research, gated by the workspace's Images switch.
  • MCP: the image generation tool, which stores each image as a workspace artifact.