Generate or edit images with OpenAI
curl --request POST \
--url https://gengen.farm/api/gengen/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "gpt-image-2.5-flare",
"prompt": "A cyan greenhouse at sunrise"
}
'import requests
url = "https://gengen.farm/api/gengen/v1/images/generations"
payload = {
"model": "gpt-image-2.5-flare",
"prompt": "A cyan greenhouse at sunrise"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({model: 'gpt-image-2.5-flare', prompt: 'A cyan greenhouse at sunrise'})
};
fetch('https://gengen.farm/api/gengen/v1/images/generations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"model": "<string>",
"status": "succeeded",
"outputs": {
"images": [
"<string>"
],
"expiresAt": "2023-11-07T05:31:56Z"
}
}{
"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."
}OpenAI
OpenAI image generation
Generate or edit images with GPT Image models using GENGEN API keys.
POST
/
images
/
generations
Generate or edit images with OpenAI
curl --request POST \
--url https://gengen.farm/api/gengen/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "gpt-image-2.5-flare",
"prompt": "A cyan greenhouse at sunrise"
}
'import requests
url = "https://gengen.farm/api/gengen/v1/images/generations"
payload = {
"model": "gpt-image-2.5-flare",
"prompt": "A cyan greenhouse at sunrise"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({model: 'gpt-image-2.5-flare', prompt: 'A cyan greenhouse at sunrise'})
};
fetch('https://gengen.farm/api/gengen/v1/images/generations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"model": "<string>",
"status": "succeeded",
"outputs": {
"images": [
"<string>"
],
"expiresAt": "2023-11-07T05:31:56Z"
}
}{
"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."
}Generate images with
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.
These are GENGEN defaults:
For the canonical endpoint documented here, use
Copy generated images to your own storage before
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.
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 |
Generate an image
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 withassets.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.
{
"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. |
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 |
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
{
"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"
}
}
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 inerror_params.providerStatus:
{
"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. |
Authorizations
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.
Available options:
gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2 Required for generation and editing; must contain non-whitespace text. Leading and trailing whitespace is trimmed before validation.
Required string length:
1 - 32000Must match the presence of reference images.
Available options:
image_generation, image_edit Only synchronous responses are supported. Omit this field or use false.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes