Images¶
Image generation is easy to start and hard to account for. Through the gateway every image call is checked against your policies, charged to the right team and recorded, with the code you already have.
What it is¶
OpenAI's three image endpoints: POST /v1/images/generations, POST /v1/images/edits and
POST /v1/images/variations. The gateway passes them on unchanged to a provider that speaks the OpenAI API: OpenAI,
Azure OpenAI, and providers added with the OpenAI kind of API that offer image generation. They aren't translated:
image APIs differ too much between providers. A call naming a Claude or Gemini model gets a 400.
The two settings¶
The same as for the OpenAI SDK: base address https://<your-gateway>/v1 and your Vidai key. See
OpenAI SDK for Python.
A minimal call¶
import base64
from openai import OpenAI
client = OpenAI()
result = client.images.generate(
model="gpt-image-1",
prompt="A watercolour of a Dutch dairy farm at dawn",
size="1024x1024",
)
with open("farm.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI();
const result = await client.images.generate({
model: "gpt-image-1",
prompt: "A watercolour of a Dutch dairy farm at dawn",
size: "1024x1024",
});
fs.writeFileSync("farm.png", Buffer.from(result.data[0].b64_json!, "base64"));
curl https://<your-gateway>/v1/images/generations \
-H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" \
-d '{"model": "gpt-image-1", "prompt": "A watercolour of a Dutch dairy farm at dawn", "size": "1024x1024"}'
An edit uploads an image as a form:
result = client.images.edit(
model="gpt-image-1",
image=open("logo.png", "rb"),
prompt="Make the background transparent",
)
import { toFile } from "openai";
const result = await client.images.edit({
model: "gpt-image-1",
image: await toFile(fs.createReadStream("logo.png"), "logo.png", { type: "image/png" }),
prompt: "Make the background transparent",
});
curl https://<your-gateway>/v1/images/edits \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F model=gpt-image-1 -F image=@logo.png -F prompt="Make the background transparent"
The model names are examples: use one your organisation approved under Models.
Reading what the gateway did¶
Use client.images.with_raw_response.generate(...) (Python) or .withResponse() (TypeScript) and read
x-vidai-request-id and x-vidai-model, as shown on Chat Completions.
For an upload (edits, variations), the request log keeps a summary: the size, the text fields such as model and
prompt, and each file's name and size. It never keeps the image. The cost, from the images the provider returned,
is in Request logs.
Errors¶
The codes are those of Chat Completions. Specific to these endpoints:
| Status | Code | When |
|---|---|---|
| 400 | bad_request |
The model is on a provider that doesn't speak the OpenAI API (Claude, Gemini, Bedrock) |
| 404 | endpoint_not_found |
The path is a near miss: /v1/images/generation, /v1/image/generations |
| 413 | payload_too_large |
The upload is over the gateway's size limit |
What goes through the gateway¶
| Feature | Through the gateway |
|---|---|
images.generate, images.edit, images.create_variation (createVariation in TypeScript) |
Yes, to OpenAI-format providers |
| Gemini image models | Through the Gemini format instead, see Gemini generateContent |
| Bedrock image models | Not served |
Check it works in a minute¶
Run the generation curl above. An answer with data means the address, key and model are right.
Good to know¶
- VidaiGuard checks don't read image prompts; your own patterns do.
- Guardrails never scan the uploaded image itself.