Skip to main content
POST /v3/images is a deterministic, provider-agnostic image endpoint. You pass a model and a prompt; Opper runs the job and returns the image inline. The same call works across every image model (OpenAI GPT Image, Google Imagen, xAI, Pruna, and more) — model and prompt are owned by Opper, a small set of high-level parameters is normalized for you, and anything model-specific goes in parameters.
Image generation is synchronous: the response comes back on the same request with the image as base64 (and, by default, a stored file_id + presigned url). For looking at images instead of making them, see Vision & PDFs.

​
Generate an image

curl -sX POST https://api.opper.ai/v3/images \
  -H "Authorization: Bearer $OPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "a wide-angle photo of a hot air balloon over green hills at dawn",
    "size": "1024x1024"
  }'
The response mirrors OpenAI’s images/generations shape, plus gateway extras: 
{
  "id": "img_...",
  "model": "openai/gpt-image-1",
  "created": 1716124800,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "mime_type": "image/png",
      "file_id": "file_...",
      "url": "https://...presigned...",
      "revised_prompt": "..."
    }
  ],
  "usage": { "cost": 0.011, "images": 1 }
}
By default each image is also stored so you get a reusable file_id and a presigned url alongside the base64. Pass "store": false to skip persistence and get base64 only, or "response_format": "url" to omit the base64 and return only the stored URL.
The file_id is a reusable handle — pass it as the image on a later edit or as the seed image on a video call, no re-upload. See Files for how files work, lifecycle, and storage quotas.

​
Parameters

model and prompt are required. The rest are optional; the high-level ones are normalized across providers, and parameters is forwarded verbatim to the provider, which validates it.
FieldWhat it does
nNumber of images to generate (default 1, max 4).
sizePixel size WxH for pixel-sized models (GPT Image, DALL·E). Validated against the model’s sizes.
aspect_ratio16:9, 1:1, etc. for aspect-ratio models (Imagen, Pruna, xAI). Bridged to/from size per model.
qualityNormalized tier: low | medium | high (default medium), plus 4k where a model declares it.
stylee.g. vivid | natural (DALL·E 3).
response_formatb64_json (default) or url (returns the stored URL only).
storePersist the output to storage and return a file_id + url. Defaults to true; respects retention rules.
parametersOpaque per-provider passthrough for anything not normalized above.

​
Edit and image-to-image

Pass a source image alongside the prompt. Each input accepts an http(s) URL, a data-URI, or a file_id from a previous generation or upload. Models that only do text-to-image reject these with a clear 400.
FieldUse for
imageThe source image to edit or transform.
maskAn inpaint mask (image/*) marking the region to change.
reference_imagesStyle or subject reference images.
curl -sX POST https://api.opper.ai/v3/images \
  -H "Authorization: Bearer $OPPER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "put the balloon over a snowy mountain range",
    "image": "file_abc123"
  }'

​
Discover models

GET /v3/images/models reports the models you can use and their capabilities (sizes, aspect ratios, whether they support edit / image-to-image): 
curl -s "https://api.opper.ai/v3/images/models" \
  -H "Authorization: Bearer $OPPER_API_KEY"

​
What’s next

Vision & PDFs

Send images into a model instead of generating them.

Video

Turn a generated image into video.

Models

Which models generate images, and at what sizes.

Control Plane

Govern providers, regions, and spend on every generation.