Image Generation and Editing

Choose between OpenAI Images and Gemini Native, generate or edit images, and process returned media safely.

Model availability changes

Use the Image Models page and /v1/models as the current source for model IDs and availability. Preview models can change without becoming permanent API contracts.

Choose the protocol

Model familyBest forProtocolKey constraint
gpt-image-2High-quality generation, large output, editing, and reference imagesOpenAI ImagesCustom sizes remain subject to model pixel limits
gpt-image-1.5Standardized OpenAI Images workflowsOpenAI ImagesUse supported size values or auto
Gemini Flash ImageFast drafts and native multimodal workflowsGemini NativeTreat one request as one-image output unless the model page says otherwise
Gemini Pro ImageQuality-first prompts and stronger semantic adherenceGemini NativeHigher quality can increase latency and cost

Endpoints and authentication

WorkflowEndpointAuthentication
OpenAI image generationhttps://onerouter.com/v1/images/generationsAuthorization: Bearer YOUR_API_KEY
OpenAI image editinghttps://onerouter.com/v1/images/editsAuthorization: Bearer YOUR_API_KEY
Gemini Nativehttps://onerouter.com/v1beta/models/{model}:generateContentx-goog-api-key: YOUR_API_KEY

OpenAI Images generation

Start with a synchronous request. Read every item in the returned data array and support both b64_json and url results.

curl https://onerouter.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photograph of a blue ceramic vase, no text",
    "size": "1024x1024",
    "quality": "high"
  }'

OpenAI Images editing

Use multipart form data for local files. State both the requested change and the invariants that must remain unchanged. Keep image order stable when multiple reference images have different roles.

curl https://onerouter.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Change only the vase color to red; keep shape, lighting, composition, and background unchanged" \
  -F "image=@input.png"

Gemini Native generation

Request image output through generationConfig.responseModalities. Traverse every candidate and part; image data is not guaranteed to be the first part. Use inlineData.mimeType when choosing the saved file extension.

curl "https://onerouter.com/v1beta/models/<IMAGE_MODEL_ID>:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "Generate a minimal product poster without text" }]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": { "aspectRatio": "1:1", "imageSize": "1K" }
    }
  }'

Gemini Native editing

Put the edit instruction and the source image in the same contents request. The source can be supplied as inlineData after base64 encoding. Preserve the response traversal used for generation.

{
  "contents": [{
    "role": "user",
    "parts": [
      { "text": "Change only the jacket to white; keep identity, pose, composition, and lighting unchanged" },
      {
        "inlineData": {
          "mimeType": "image/png",
          "data": "<BASE64_IMAGE>"
        }
      }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["IMAGE"]
  }
}

Response paths

ScenarioMinimum requestRead result from
OpenAI generationmodel, promptdata[*].b64_json or data[*].url
OpenAI editingmodel, prompt, image / imagesdata[*].b64_json or data[*].url
Gemini generationcontents, responseModalities=["IMAGE"]candidates[*].content.parts[*].inlineData.data
Gemini editingInstruction plus inlineDatacandidates[*].content.parts[*].inlineData.data
Gemini formatNo extra request fieldinlineData.mimeType

Production checklist

  • Choose the protocol before choosing request fields.
  • Send only parameters documented for the selected model.
  • Iterate over every returned image instead of assuming a single result.
  • Record model, size, aspect ratio, returned count, MIME type, latency, and error code.
  • Never log API keys, full Base64 payloads, sensitive prompts, or private source images.
  • Apply allowlists, timeouts, size limits, and content-type checks to remote reference images.
  • Keep the original provider error body for troubleshooting.
  • Reconcile billing against successful returned outputs, not only requested count.

Troubleshooting

SymptomHow to fix it
401 / 403Check the authentication header, key status, and model permission.
Invalid size or aspect ratioUse values supported by the selected model; do not copy values across protocols.
Gemini returns no imageInclude IMAGE in responseModalities and traverse every response part.
Saved file cannot openDecode Base64 correctly and derive the extension from the returned MIME type.
Editing changes too muchState the requested change and explicit invariants in the prompt.
Remote reference image failsVerify HTTPS access, response content type, file size, and timeout policy.