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 family | Best for | Protocol | Key constraint |
|---|---|---|---|
gpt-image-2 | High-quality generation, large output, editing, and reference images | OpenAI Images | Custom sizes remain subject to model pixel limits |
gpt-image-1.5 | Standardized OpenAI Images workflows | OpenAI Images | Use supported size values or auto |
| Gemini Flash Image | Fast drafts and native multimodal workflows | Gemini Native | Treat one request as one-image output unless the model page says otherwise |
| Gemini Pro Image | Quality-first prompts and stronger semantic adherence | Gemini Native | Higher quality can increase latency and cost |
Endpoints and authentication
| Workflow | Endpoint | Authentication |
|---|---|---|
| OpenAI image generation | https://onerouter.com/v1/images/generations | Authorization: Bearer YOUR_API_KEY |
| OpenAI image editing | https://onerouter.com/v1/images/edits | Authorization: Bearer YOUR_API_KEY |
| Gemini Native | https://onerouter.com/v1beta/models/{model}:generateContent | x-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
| Scenario | Minimum request | Read result from |
|---|---|---|
| OpenAI generation | model, prompt | data[*].b64_json or data[*].url |
| OpenAI editing | model, prompt, image / images | data[*].b64_json or data[*].url |
| Gemini generation | contents, responseModalities=["IMAGE"] | candidates[*].content.parts[*].inlineData.data |
| Gemini editing | Instruction plus inlineData | candidates[*].content.parts[*].inlineData.data |
| Gemini format | No extra request field | inlineData.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
| Symptom | How to fix it |
|---|---|
| 401 / 403 | Check the authentication header, key status, and model permission. |
| Invalid size or aspect ratio | Use values supported by the selected model; do not copy values across protocols. |
| Gemini returns no image | Include IMAGE in responseModalities and traverse every response part. |
| Saved file cannot open | Decode Base64 correctly and derive the extension from the returned MIME type. |
| Editing changes too much | State the requested change and explicit invariants in the prompt. |
| Remote reference image fails | Verify HTTPS access, response content type, file size, and timeout policy. |