Skip to main content
POST
Generate or edit images with OpenAI
Generate images with GPT Image 2, 2.5, or 2.6. Select a 2.6 model to generate animated GIFs, create vector SVGs, or edit with an annotation layer. For image generation inside a GPT conversation, use the image_generation tool documented in Chat. 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. Call this endpoint with your GENGEN key.

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. 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.

GPT Image 2.6

Use controls.complexity (low, medium, or the default high) to control planning separately from rendering quality. For a markup-guided edit, send the first original in assets.referenceImages and the HTTPS URL of a transparent PNG in assets.markup. The overlay must match the first image’s oriented dimensions and contain transparent pixels. Describe the desired changes in the prompt. Each of the first image and overlay may contain at most 16,777,216 pixels. The overlay limit is 50 MB. For an animated GIF, use outputFormat: "gif" with or without reference images. Specify 2–16 frames (default 9) and 20–2000 ms per frame (default 200). The upstream rounds the delay to the nearest 10 ms. The default GIF size is auto; smaller explicit frames are allowed in multiples of 16. Available sizes depend on the frame count and total pixel budget.
For a static vector SVG, use controls.outputFormat: "svg" with one output and a text prompt. Download the returned URL as an SVG. GENGEN charges image rendering plus measured author input and output tokens at the author model’s rates. Reasoning tokens count once within output. Omit providerOptions.openai.svg to use the Images API default: gpt-6-luna with low reasoning effort. To override it, specify model and optionally reasoningEffort. All four supported authors accept low, medium, high, xhigh, and max; only gpt-6-sol and gpt-6-luna also accept none. Availability of GIF, SVG and author selection depends on upstream project access.

Controls

When you omit controls, GENGEN uses medium quality. The default size is 1024x1024 for a static image and auto for a GIF.

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. Keep the complete JSON request body within the hosted endpoint limit of 4.5 MB. Reference image files are fetched from their HTTPS URLs and do not count toward that JSON size. Base64 references return HTTP 400 before a balance reservation or generation. Oversized requests may not return the GENGEN JSON error format.

Response

Copy generated images to your own storage before outputs.expiresAt. URLs are retained for 24 hours. Generated images are returned as HTTPS URLs, not Base64. Changing controls.outputFormat changes the image file format, not the URL-based response format. The image:* ID identifies this synchronous request; it cannot be used for polling, cancellation, or resuming a stream. Each stored OpenAI output is limited to 20 MiB, or 64 MiB for a generated GIF. 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

Use error_code to handle failures. If present, error_params.providerReason gives a more specific reason and error_params.diagnosticId helps GENGEN support locate the request. A model access failure can return HTTP 502; you do not need to configure a separate OpenAI account. Confirmed request rejections release the balance reservation without a generation charge. Unknown outcomes retain the reservation for reconciliation. If generation completed 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 hosted endpoint limits the complete JSON body to 4.5 MB. 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.6-flare,
gpt-image-2.6-sunburst,
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
required if mode = image_edit
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