Images API

​

Overview

​

Supported endpoints

​

Generate an image

curl https://your-gateway/v1/images/generations \
  -H "Authorization: Bearer $GOMODEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "A watercolor painting of a lighthouse at dawn",
    "n": 1,
    "size": "1024x1024",
    "quality": "medium"
  }'

import base64
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://your-gateway/v1",
    api_key=os.environ["GOMODEL_KEY"],
)

result = client.images.generate(
    model="gpt-image-1",
    prompt="A watercolor painting of a lighthouse at dawn",
    size="1024x1024",
    quality="medium",
)

with open("lighthouse.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

import { writeFile } from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://your-gateway/v1",
  apiKey: process.env.GOMODEL_KEY,
});

const result = await client.images.generate({
  model: "gpt-image-1",
  prompt: "A watercolor painting of a lighthouse at dawn",
  size: "1024x1024",
  quality: "medium",
});

await writeFile("lighthouse.png", Buffer.from(result.data[0].b64_json, "base64"));

​

Edit an image

curl https://your-gateway/v1/images/edits \
  -H "Authorization: Bearer $GOMODEL_KEY" \
  -F model="gpt-image-1" \
  -F image="@lighthouse.png" \
  -F mask="@mask.png" \
  -F prompt="Add a sailboat on the horizon" \
  -F size="1024x1024"

result = client.images.edit(
    model="gpt-image-1",
    image=open("lighthouse.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="Add a sailboat on the horizon",
    size="1024x1024",
)

with open("lighthouse-edited.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

import fs from "node:fs";

const result = await client.images.edit({
  model: "gpt-image-1",
  image: fs.createReadStream("lighthouse.png"),
  mask: fs.createReadStream("mask.png"),
  prompt: "Add a sailboat on the horizon",
  size: "1024x1024",
});

await writeFile("lighthouse-edited.png", Buffer.from(result.data[0].b64_json, "base64"));

​

Cost tracking

• Token-billed models (gpt-image-1 and similar) report usage in the response; GoModel stores the input/output token counts and prices them with the model’s input_per_mtok / output_per_mtok rates.
• Per-image models (DALL·E, grok-2-image, Imagen) report no tokens. GoModel records the number of returned images (images in the raw usage data) and prices it with the model’s per_image rate.
• When a response carries no usage block and the configured pricing cannot cost it without one (no per_image rate to apply to the returned images, no per_request rate), the usage row is flagged with a cost-calculation caveat so it reads as “unreported usage” rather than a free call.

providers:
  openai:
    type: openai
    api_key: "${OPENAI_API_KEY}"
    models:
      - id: dall-e-3
        metadata:
          pricing:
            currency: USD
            per_image: 0.04

​

Limitations

• No failover, guardrails, or response cache — these stages are skipped. Requests are still authorized, budget-checked, rate-limited, metered, and written to the audit log.
• No streaming — stream: true is rejected with a 400 because streamed image generation is delivered as server-sent events, which these endpoints do not relay. Omit stream (or set it to false) to receive the complete JSON response.
• Variations (/v1/images/variations) are not exposed. Use the passthrough API (/p/{provider}/v1/images/...) to reach them on a specific provider.
• OpenAI request shape in — Google Gemini’s native image APIs (Imagen predict, Gemini image model generateContent) are translated behind these endpoints; see provider notes below. Other providers whose native image API differs from OpenAI’s are not translated; use passthrough for those.

​

Google Gemini

• Gemini image models do not support multi-candidate output, so n (up to 10) is served as n parallel generateContent calls whose results are merged — each call is billed by Google. For Imagen, n maps to sampleCount; size maps to the closest supported aspect ratio (1024x1024 → 1:1, 1536x1024 → 3:2, …), and a raw ratio such as "16:9" passes through. Unknown JSON fields are forwarded verbatim, so native parameters (personGeneration, sampleImageSize, imageConfig, …) work unchanged.
• Images always return as b64_json. Any text a Gemini image model produces alongside the image is surfaced as revised_prompt.
• Gemini image models report token usage (token-billed); Imagen reports none (price it per_image).
• Edits work with Gemini image models only: uploads become inline image parts ahead of the prompt. mask is not supported — describe the region to change in the prompt. Imagen models only generate.

​

Audit logging

• The generation request is stored as JSON. An edit request is stored as an image body: the prompt and parameters plus one item per uploaded source image and mask (filename, content type, size).
• The response is stored as an image body too — the envelope (created, usage, size, quality, …) plus one item per returned image. Hosted URLs are kept as links.