Images

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 by default: the response comes back on the same request with the image as base64 (plus a stored file_id + presigned url when you pass "store": true). Slow jobs (the top quality tiers on the newest models) can run in the background instead, see Heavy jobs. 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-2.5-flare",
    "prompt": "a wide-angle photo of a hot air balloon over green hills at dawn",
    "size": "1024x1024"
  }'

import os, base64, requests

r = requests.post(
    "https://api.opper.ai/v3/images",
    headers={"Authorization": f"Bearer {os.environ['OPPER_API_KEY']}"},
    json={
        "model": "openai/gpt-image-2.5-flare",
        "prompt": "a wide-angle photo of a hot air balloon over green hills at dawn",
        "size": "1024x1024",
    },
)
r.raise_for_status()
img = r.json()["data"][0]
open("balloon.png", "wb").write(base64.b64decode(img["b64_json"]))
print("saved balloon.png")

OpenAI’s current pair: gpt-image-2.5-flare for fast everyday generation and editing, gpt-image-2.5-sunburst when an edit has to land exactly — same rates, slower. Both take two tiers above high, xhigh and max, and bill from the tokens the provider reports rather than a fixed per-image table, so cost climbs steeply with the tier: max runs about 16x medium.

The response mirrors OpenAI’s images/generations shape, plus gateway extras:

{
  "id": "img_...",
  "model": "openai/gpt-image-2.5-flare",
  "created": 1716124800,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "mime_type": "image/png",
      "revised_prompt": "..."
    }
  ],
  "usage": { "cost": 0.013, "images": 1 }
}

Pass "store": true to also store each image, so you get a reusable file_id and a presigned url alongside the base64, or "response_format": "url" to store it and return only the stored URL instead of the base64. Without either, nothing is stored.

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.

Field	What it does
`n`	Number of images to generate (default 1, max 4).
`size`	Pixel size `WxH` for pixel-sized models (GPT Image, DALL·E). Validated against the model’s sizes.
`aspect_ratio`	`16:9`, `1:1`, etc. for aspect-ratio models (Imagen, Pruna, xAI). Bridged to/from `size` per model.
`quality`	Normalized tier: `low` \| `medium` \| `high` (default `medium`), plus `xhigh`, `max`, `auto` and `4k` where a model declares them. Rejected on models that declare no quality tiers, and on a tier the chosen model doesn’t list.
`response_format`	`b64_json` (default) or `url` (returns the stored URL only).
`store`	Persist the output to storage and return a `file_id` + `url`. Defaults to false; a stored file is permanent until deleted. Refused on zero-data-retention projects.
`async`	Run the job on the background worker: returns `202` with a URL to poll instead of blocking. One image per request. See Heavy jobs.
`parameters`	Opaque per-provider passthrough for anything not normalized above.

Model-specific knobs go in parameters — for example DALL·E 3’s style (vivid | natural), or a diffusion model’s seed / negative_prompt. They’re forwarded verbatim and validated by the provider. See Discover models for how to list the keys a given model accepts.

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.

Field	Use for
`image`	The source image to edit or transform.
`mask`	An inpaint mask (`image/*`) marking the region to change.
`reference_images`	Style 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-2.5-flare",
    "prompt": "put the balloon over a snowy mountain range",
    "image": "file_abc123"
  }'

Heavy jobs (async)

A synchronous call is bounded by a 3-minute server deadline. Nearly every generation fits: most models return in 5–30 s. The exception is the top quality tiers on the newest models — max on GPT Image 2.5 takes a minute or more. A job that overruns the deadline comes back as a 504 and is not billed. Set async: true to hand that job to the background worker. The call returns straight away with a 202, an id and a status_url. Poll the status URL: 202 while the job is processing, then 200 with status: "completed", a presigned url, the mime_type, the billed usage, and a reusable file_id when you passed "store": true. Async runs one image per request, so leave n at 1.

Submit + poll

# 1. Submit — returns { "id": "gen_...", "status_url": ".../v3/artifacts/{id}/status" }
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-2.5-sunburst",
    "prompt": "an oil painting of a lighthouse in a winter storm",
    "quality": "max",
    "async": true
  }'

# 2. Poll: 202 while processing, then 200 with the image url
curl -s https://api.opper.ai/v3/artifacts/{id}/status \
  -H "Authorization: Bearer $OPPER_API_KEY"

Discover models

GET /v3/images/models reports the models you can use and their capabilities. Each model’s params.image block lists the normalized axes it accepts — sizes, aspect_ratios, resolutions, qualities — plus a parameters list of the native passthrough keys (e.g. seed, negative_prompt, personGeneration) you can put in parameters, so you can discover a model’s knobs instead of guessing.

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.

Observe & Control

Inspect generations and manage spend rules.

Get started

Platform

Build

Observe & Control

Integrations

Tutorials

Tooling

Generate an image

Parameters

Edit and image-to-image

Heavy jobs (async)

Discover models

What’s next

Vision & PDFs

Video

Models

Observe & Control

​Generate an image

​Parameters

​Edit and image-to-image

​Heavy jobs (async)

​Discover models

​What’s next

Vision & PDFs

Video

Models

Observe & Control

Generate an image

Parameters

Edit and image-to-image

Heavy jobs (async)

Discover models

What’s next