Skip to main content
POST
Generate or edit images with OpenAI
Generate images with gpt-image-2.5-flare, gpt-image-2.5-sunburst, or gpt-image-2. Send a GENGEN API key to POST https://gengen.farm/api/gengen/v1/images/generations. The request waits for completion and returns public HTTPS image URLs. Only these exact model IDs are accepted; dated OpenAI snapshots are not exposed. Call this endpoint with your GENGEN key. OpenAI credentials and upstream organization verification are managed by GENGEN, not by clients of this API.

Generate an image

Edit with reference images

Use the same endpoint with assets.referenceImages. Supply up to 16 HTTPS URLs for PNG, JPEG, or WebP images. Base64 data URLs and raw Base64 are not supported. HTTPS URLs must be publicly accessible without additional authentication headers and must not contain a username or password. For portable requests across image upstreams, keep each reference within 50 MiB and all references within 200 MiB. Replace the example URL below with your own image. The prompt is required for both generation and editing.

Controls

These are GENGEN defaults: 1024x1024 and medium are supplied even when you omit controls. OpenAI’s native quality default is auto.

Request compatibility and limits

This endpoint uses the normalized GENGEN schema. Map native OpenAI fields as follows: For the canonical endpoint documented here, use controls.outputCount, not controls.n or top-level n. These examples use GENGEN’s normalized request and response contract, not the OpenAI SDK images.generate / images.edit contract. Generation and editing both use the canonical endpoint above; adding reference images selects editing automatically. Mask editing, file IDs, input_fidelity, streaming, partial-image events, and Responses API image tools are not exposed. Omit stream or set it to false; stream: true returns HTTP 400. Unknown fields inside assets, controls, or providerOptions.openai are rejected. Each reference URL is limited to 20,971,520 characters. This is a URL length limit, not an upload allowance. The complete JSON body has a 16 MiB application limit, and the hosted endpoint is additionally subject to Vercel’s 4.5 MB request limit. Send reference images as HTTPS URLs. Base64 references return HTTP 400 before a balance reservation or upstream generation. Payloads rejected by hosting may not use the GENGEN JSON error format.

Response

Copy generated images to your own storage before outputs.expiresAt. URLs are retained for 24 hours. Public responses omit Base64 image data, duplicate aliases, and upstream billing details. OpenAI returns Base64 to GENGEN; GENGEN stores the decoded images and returns URLs. Changing controls.outputFormat changes the image file format, not the URL-based response format. The image:* ID identifies this synchronous request; it is not an upstream task ID for polling, cancellation, or resuming a stream. Stored output images are limited to 20 MiB each. A balance reservation is created before submission. Final charges use the returned text and image token usage; request estimates can differ from final charges. See live customer pricing. An interrupted request may require reconciliation; submitting again starts a separate generation and may incur another charge.

Errors and access

An upstream refusal and a network interruption are different errors. For example, a provider verification refusal returns HTTP 502, with the upstream 403 preserved in error_params.providerStatus:
Definitive upstream 4xx refusals release the balance reservation without a generation charge. Unknown outcomes retain the reservation for reconciliation. If OpenAI completed the work but storing or delivering the image fails, confirmed usage can still be charged. A timeout is not proof that the request was unprocessed; do not automatically repeat image requests whose outcome is unknown. Try these models in the API Explorer.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The complete JSON body is limited to 16 MiB by GENGEN and 4.5 MB on Vercel-hosted deployments. Reference images must use HTTPS URLs; Base64 input is not supported. Supply optional settings only under their documented GENGEN fields; omit values instead of sending null.

model
enum<string>
required
Available options:
gpt-image-2.5-flare,
gpt-image-2.5-sunburst,
gpt-image-2
prompt
string
required

Required for generation and editing; must contain non-whitespace text. Leading and trailing whitespace is trimmed before validation.

Required string length: 1 - 32000
mode
enum<string>

Must match the presence of reference images.

Available options:
image_generation,
image_edit
stream
boolean
default:false

Only synchronous responses are supported. Omit this field or use false.

assets
object
controls
object
providerOptions
object

Response

Generated image URLs, retained for 24 hours.

id
string
required

Stable image generation ID.

model
string
required

Requested model.

status
string
required
Allowed value: "succeeded"
outputs
object
required