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-databody.
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 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"
}'
{
"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
400invalid_valueonsize, and the message states the range. - Fixed list. Any well-formed
WIDTHxHEIGHTrenders at the listed size with the closest aspect ratio, since common clients send1024x1024to every model. The response'ssizereports 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 answers404. 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 ownContent-Type,Cache-Control: privateuntil the link expires, andX-Content-Type-Options: nosniff. Every failure, an unknown, altered or expired token included, is the same404.
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, typeimage_generation_user_error, codemoderation_blocked: the prompt was refused. The message names the refused category and the request ID; it never repeats the prompt.400screening_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.503screening_unavailable: screening did not answer. Retry. On direct dispatch it is429withRetry-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.
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 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/generationsand/v1/images/editsunder the_directbase, withmodeladdressing an image generation deployment. Capacity refusals answer429withRetry-After. - Responses API: the
image_generationtool. - 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.