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.invalid_request",
"error_params": {
"field": "prompt"
},
"error": "A non-empty prompt is required."
}Image API
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.invalid_request",
"error_params": {
"field": "prompt"
},
"error": "A non-empty prompt is required."
}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
Only these exact model IDs are accepted. Call this endpoint with your GENGEN key.
For a static vector SVG, use
When you omit controls, GENGEN uses medium quality. The default size is
For the canonical endpoint documented here, use
Copy generated images to your own storage before
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.
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.
| Model ID | Focus | Quality settings |
|---|---|---|
gpt-image-2.6-flare | Fast iteration, generation and edits | low, medium, high, xhigh, max, auto |
gpt-image-2.6-sunburst | Detailed compositions and precise edits | low, medium, high, xhigh, max, auto |
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. 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" }
}
GPT Image 2.6
Usecontrols.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.
{
"model": "gpt-image-2.6-flare",
"prompt": "A firefly loops around a lantern. Seamless animation.",
"controls": { "outputFormat": "gif", "size": "auto", "frameCount": 6, "frameDurationMs": 150 }
}
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.
{
"model": "gpt-image-2.6-sunburst",
"prompt": "A vector icon of a greenhouse, using three solid colors.",
"controls": { "outputFormat": "svg", "complexity": "medium", "outputCount": 1 }
}
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 for static images or auto for GIF. Supports auto or WIDTHxHEIGHT. Each edge must be divisible by 16 and at most 3840 pixels; static images require 655,360–8,294,400 pixels; aspect ratio must be between 1:3 and 3:1. Sizes above 2560×1440 are experimental. |
controls.quality | low, medium (default), high, or auto. The 2.5 and 2.6 models also accept xhigh and max. |
controls.outputCount | Integer from 1 to 10; defaults to 1. |
controls.outputFormat | png (default), jpeg, or webp. Both 2.6 models also support gif and svg. |
controls.background | auto (default), opaque, or transparent. Transparency requires PNG or WebP. GPT Image 2 transparency is in preview. |
controls.outputCompression | Optional integer 0–100, for JPEG or WebP only. Defaults to 100. |
providerOptions.openai.moderation | Optional auto (default) or low. low requests less restrictive filtering; it does not disable moderation. |
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:| 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.
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
{
"id": "image:550e8400-e29b-41d4-a716-446655440000",
"model": "gpt-image-2.5-flare",
"status": "succeeded",
"outputs": {
"images": ["https://example.com/generated-image.png"],
"expiresAt": "2026-09-10T08:00:00.000Z"
}
}
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
Useerror_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.
| Error code or reason | Meaning and action |
|---|---|
provider.invalid_request | HTTP 400. Correct the named field in error_params.field. |
organization_verification_required | Model access is unavailable. Contact GENGEN support with the diagnostic ID. |
model_unavailable | The requested model is unavailable. Check the model ID or contact support. |
region_unsupported / access_denied | Model access is unavailable for this request. Contact GENGEN support with the diagnostic ID. |
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
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.