> ## Documentation Index > Fetch the complete documentation index at: https://docs.gengen.farm/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI image generation > Generate or edit images with GPT Image models using GENGEN API keys. 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. | Model ID | Focus | Quality settings | | - | - | - | | `gpt-image-2.5-flare` | Fast everyday generation and editing | `low`, `medium`, `high`, `xhigh`, `max`, `auto` | | `gpt-image-2.5-sunburst` | Generation and precise reference-image editing | `low`, `medium`, `high`, `xhigh`, `max`, `auto` | | `gpt-image-2` | Generation and editing with flexible dimensions | `low`, `medium`, `high`, `auto` | 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 ```bash theme={"dark"} curl https://gengen.farm/api/gengen/v1/images/generations \ -H 'Authorization: Bearer gengen_live_xxxxxxxxxxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-image-2.5-flare", "prompt": "A cyan greenhouse at sunrise, editorial photography", "controls": { "size": "1024x1024", "quality": "medium", "outputCount": 1 } }' ``` ## 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. ```json theme={"dark"} { "model": "gpt-image-2.5-sunburst", "mode": "image_edit", "prompt": "Keep the product unchanged and replace the background with a clean studio scene.", "assets": { "referenceImages": ["https://example.com/product.png"] }, "controls": { "size": "1536x1024", "quality": "high", "outputFormat": "png" } } ``` ## Controls | Field | Values and defaults | | - | - | | `prompt` | Required, 1–32,000 characters after trimming leading and trailing whitespace. A whitespace-only prompt is invalid. | | `mode` | Optional `image_generation` or `image_edit`; must match whether reference images are supplied. | | `controls.size` | Defaults to `1024x1024`. Supports `auto` or `WIDTHxHEIGHT`. Each edge must be divisible by 16 and at most 3840 pixels; total pixels must be 655,360–8,294,400; aspect ratio must be between 1:3 and 3:1. Sizes above 2560×1440 are experimental upstream. | | `controls.quality` | `low`, `medium` (default), `high`, or `auto`. The 2.5 models also accept `xhigh` and `max`. | | `controls.outputCount` | Integer from 1 to 10; defaults to 1. | | `controls.outputFormat` | `png` (default), `jpeg`, or `webp`. | | `controls.background` | `auto` (default), `opaque`, or `transparent`. Transparency requires PNG or WebP. GPT Image 2 transparency is an upstream preview. | | `controls.outputCompression` | Optional integer 0–100, for JPEG or WebP only. When omitted, OpenAI uses its default of 100. | | `providerOptions.openai.moderation` | Optional `auto` (upstream default) or `low`. `low` requests less restrictive filtering; it does not disable moderation. | 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: | Native OpenAI field | GENGEN field | | - | - | | `n` | `controls.outputCount` | | `size` | `controls.size` | | `quality` | `controls.quality` | | `output_format` | `controls.outputFormat` | | `background` | `controls.background` | | `output_compression` | `controls.outputCompression` | | `images[].image_url` | `assets.referenceImages[]` | | `moderation` | `providerOptions.openai.moderation` | 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](https://vercel.com/docs/functions/limitations#request-body-size). 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 ```json theme={"dark"} { "id": "image:550e8400-e29b-41d4-a716-446655440000", "model": "gpt-image-2.5-flare", "status": "succeeded", "outputs": { "images": ["https://example.public.blob.vercel-storage.com/gengen/openai-generated-images/result.png"], "expiresAt": "2026-09-10T08:00:00.000Z" } } ``` 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](/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`: ```json theme={"dark"} { "error_code": "provider.openai_request_failed", "error_params": { "provider": "openai", "providerStatus": 403, "providerReason": "organization_verification_required", "diagnosticId": "0e41dc0b-15ff-4ce6-b813-200c72199048", "service": "openai" }, "error": "OpenAI requires organization verification before this image model can be used." } ``` | Error code or reason | Meaning and action | | - | - | | `provider.invalid_request` | HTTP 400. Correct the named field in `error_params.field`. | | `organization_verification_required` | The upstream organization needs verification. Contact GENGEN support with the diagnostic ID. | | `model_unavailable` | The model does not exist or is unavailable to the configured upstream project. | | `region_unsupported` / `access_denied` | OpenAI rejected access. `access_denied` alone does not identify which permission is missing. | | `provider.openai_request_interrupted` | HTTP 502. `providerReason` distinguishes connection reset, DNS failure, timeouts, and other transport interruptions. | | `provider.usage_missing` | HTTP 502. Generation usage could not be settled automatically; the request requires reconciliation. | 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](https://gengen.farm/api-explorer/demos/image-generation?model=gpt-image-2.5-flare). ## OpenAPI ````yaml openapi/openai.yaml POST /images/generations openapi: 3.1.0 info: title: OpenAI images through GENGEN version: 1.0.1 servers: - url: https://gengen.farm/api/gengen/v1 security: - bearerAuth: [] paths: /images/generations: post: summary: Generate or edit images with OpenAI description: >- Synchronous GENGEN endpoint for generation and reference-image editing. Use GENGEN bearer credentials and normalized assets/controls, not native OpenAI Images SDK payloads. Both operations use this canonical endpoint; adding reference images selects editing. Streaming and dated model snapshots are not supported. operationId: createOpenAIImage requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OpenAIImageRequest' example: model: gpt-image-2.5-flare prompt: A cyan greenhouse at sunrise controls: size: 1024x1024 quality: medium outputCount: 1 responses: '200': description: Generated image URLs, retained for 24 hours. content: application/json: schema: type: object required: - id - model - status - outputs properties: id: type: string description: Stable image generation ID. model: type: string description: Requested model. status: const: succeeded type: string outputs: type: object required: - images - expiresAt properties: images: type: array minItems: 1 items: type: string format: uri expiresAt: type: string format: date-time default: description: >- Invalid request, insufficient balance, provider failure, or pending reconciliation. Upstream HTTP 400 maps to HTTP 400; other upstream rejections map to HTTP 502 with the original status in error_params.providerStatus. content: application/json: schema: type: object required: - error_code - error properties: error: type: string error_code: type: string error_params: type: object properties: provider: type: string service: type: string field: type: string providerStatus: type: integer description: >- Original upstream HTTP status, not the GENGEN response status. providerCode: type: string description: Recognized upstream error code, when available. providerReason: type: string description: >- Safe classification such as organization_verification_required, model_unavailable, access_denied, or connection_reset. diagnosticId: type: string format: uuid description: >- Correlates the error with server diagnostics. Include it when contacting support. example: error_code: provider.openai_request_failed error_params: provider: openai providerStatus: 403 providerReason: organization_verification_required diagnosticId: 0e41dc0b-15ff-4ce6-b813-200c72199048 service: openai error: >- OpenAI requires organization verification before this image model can be used. components: schemas: OpenAIImageRequest: type: object description: >- 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. required: - model - prompt properties: model: type: string enum: - gpt-image-2.5-flare - gpt-image-2.5-sunburst - gpt-image-2 mode: type: string description: Must match the presence of reference images. enum: - image_generation - image_edit prompt: type: string description: >- Required for generation and editing; must contain non-whitespace text. Leading and trailing whitespace is trimmed before validation. minLength: 1 maxLength: 32000 stream: type: boolean const: false default: false description: >- Only synchronous responses are supported. Omit this field or use false. assets: type: object additionalProperties: false properties: referenceImages: type: array maxItems: 16 items: type: string description: >- Publicly accessible HTTPS URL without additional authentication headers or URL credentials. Base64 data URLs and raw Base64 are not supported. Keep each reference within 50 MiB and all references within 200 MiB for portability across upstreams. The complete JSON body limit also applies. format: uri pattern: ^[Hh][Tt][Tt][Pp][Ss]:// maxLength: 20971520 controls: type: object additionalProperties: false properties: size: type: string description: >- auto or WIDTHxHEIGHT. Edges divisible by 16, at most 3840 per edge; 655360–8294400 pixels; aspect ratio 1:3 to 3:1. Resolutions above 2560x1440 are experimental upstream. Listed example sizes are not exhaustive. pattern: ^(auto|[0-9]+x[0-9]+)$ default: 1024x1024 quality: type: string description: >- xhigh and max require a GPT Image 2.5 model. GENGEN defaults to medium; OpenAI's native default is auto. enum: - low - medium - high - xhigh - max - auto default: medium outputCount: type: integer minimum: 1 maximum: 10 default: 1 outputFormat: type: string enum: - png - jpeg - webp default: png background: type: string description: >- Transparency requires PNG or WebP. GPT Image 2 transparency is an upstream preview. enum: - auto - opaque - transparent default: auto outputCompression: type: integer minimum: 0 maximum: 100 description: >- JPEG or WebP only; explicitly set outputFormat to jpeg or webp. When omitted, OpenAI uses 100. allOf: - if: required: - background properties: background: const: transparent then: properties: outputFormat: enum: - png - webp - if: required: - outputCompression then: required: - outputFormat properties: outputFormat: enum: - jpeg - webp providerOptions: type: object properties: openai: type: object additionalProperties: false properties: moderation: type: string description: >- Defaults upstream to auto. Low reduces filtering strictness; it does not disable moderation. enum: - auto - low allOf: - if: properties: model: const: gpt-image-2 then: properties: controls: properties: quality: enum: - low - medium - high - auto - if: required: - mode properties: mode: const: image_edit then: required: - assets properties: assets: required: - referenceImages properties: referenceImages: minItems: 1 - if: required: - mode properties: mode: const: image_generation then: properties: assets: properties: referenceImages: maxItems: 0 securitySchemes: bearerAuth: type: http scheme: bearer ````