Generate and Edit Images with GPT and Gemini Models via Flatkey

Flatkey provides two image API families. Use the OpenAI-compatible /v1/images/generations and /v1/images/edits endpoints for gpt-image-2. Use the native Gemini generateContent endpoint for Gemini image models.

You cannot call Gemini image models with the OpenAI Images SDK, /v1/images/generations, or /v1/images/edits. Use the native Gemini API examples on this page. Otherwise, the request may return get_channel_failed.

Supported image models

Model	API	Official price	After-bonus price
`gpt-image-2`	OpenAI Images API	$6.65 / 1M tokens	~$3.99 / 1M tokens
`gemini-3-pro-image`	Native Gemini API	$2.00 / 1M tokens	~$1.20 / 1M tokens
`gemini-2.5-flash-image`	Native Gemini API	$0.30 / 1M tokens	~$0.18 / 1M tokens
`gemini-3.1-flash-image`	Native Gemini API	See the dashboard	See the dashboard
`gemini-3.1-flash-lite-image`	Native Gemini API	See the dashboard	See the dashboard
`nano-banana-pro-preview`	Native Gemini API	See the dashboard	See the dashboard

See the Model Directory for the complete model list and current pricing.

Use gpt-image-2

Use the OpenAI SDK

import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.images.generate(
    model="gpt-image-2",
    prompt="A serene mountain lake at sunset, photorealistic",
    size="1024x1024",
)

Path("generated.png").write_bytes(
    base64.b64decode(response.data[0].b64_json)
)

import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A serene mountain lake at sunset, photorealistic",
  size: "1024x1024",
});

writeFileSync(
  "generated.png",
  Buffer.from(response.data[0].b64_json, "base64"),
);

Generate an image with curl

curl https://router.flatkey.ai/v1/images/generations \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic cityscape at night, neon lights, wide angle",
    "size": "1024x1024"
  }'

This endpoint returns the generated image in data[0].b64_json; gpt-image-2 does not provide a hosted image URL. See the Images API reference for all fields.

Edit an image with curl

Use /v1/images/edits to upload an input image together with editing instructions. This endpoint uses multipart/form-data; image is required and mask is optional.

curl https://router.flatkey.ai/v1/images/edits \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=add a small yellow star in the center" \
  -F "image=@input.png" \
  -F "mask=@mask.png"

image supports PNG, JPEG, and WebP. Omit mask to edit the whole image based on the prompt. When a mask is provided, its transparent areas identify the regions to redraw. The edited image is returned in data[0].b64_json. See the edit API reference for all fields.

Use Gemini image models

Gemini image models use the following endpoint. Replace {model} with a model ID:

POST https://router.flatkey.ai/v1beta/models/{model}:generateContent

The request must include "IMAGE" in generationConfig.responseModalities. Generated images are returned in candidates[].content.parts[].inlineData.

Use curl

curl https://router.flatkey.ai/v1beta/models/gemini-2.5-flash-image:generateContent \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "A product photo of a translucent purple glass bottle on a white background"
      }]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

Use Python and save the image

Install an HTTP client:

pip install requests

import base64
import os
from pathlib import Path

import requests

model = "gemini-2.5-flash-image"
response = requests.post(
    f"https://router.flatkey.ai/v1beta/models/{model}:generateContent",
    headers={
        "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [{
                "text": "A product photo of a translucent purple glass bottle on a white background"
            }]
        }],
        "generationConfig": {
            "responseModalities": ["TEXT", "IMAGE"]
        },
    },
    timeout=180,
)
response.raise_for_status()

parts = response.json()["candidates"][0]["content"]["parts"]
image = next(part["inlineData"] for part in parts if "inlineData" in part)
suffix = ".jpg" if image["mimeType"] == "image/jpeg" else ".png"
output = Path(f"generated{suffix}")
output.write_bytes(base64.b64decode(image["data"]))
print(output)

Use Node.js and save the image

import { writeFileSync } from "node:fs";

const model = "gemini-2.5-flash-image";
const response = await fetch(
  `https://router.flatkey.ai/v1beta/models/${model}:generateContent`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [{
          text: "A product photo of a translucent purple glass bottle on a white background",
        }],
      }],
      generationConfig: {
        responseModalities: ["TEXT", "IMAGE"],
      },
    }),
  },
);

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

const result = await response.json();
const image = result.candidates[0].content.parts.find(
  (part) => part.inlineData,
).inlineData;
const suffix = image.mimeType === "image/jpeg" ? "jpg" : "png";
writeFileSync(`generated.${suffix}`, Buffer.from(image.data, "base64"));

Gemini request fields

array

required

Conversation content. For text-to-image generation, put the image description in parts[].text.

array

required

Response modalities. Use ["TEXT", "IMAGE"] for text and images, or ["IMAGE"] to request images only.

string

required

The model ID appears in the URL path, not in the request body. For example, gemini-3-pro-image.

Gemini response format

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is the generated image."
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAA..."
            }
          }
        ]
      }
    }
  ]
}

inlineData.data contains the base64-encoded image. A response can contain text and multiple image parts. Iterate through parts instead of assuming that the image is always the first item.

Troubleshooting

The API returns get_channel_failed

Make sure the endpoint matches the model:

Use /v1/images/generations to generate with gpt-image-2.
Use /v1/images/edits to edit with gpt-image-2.
Use /v1beta/models/{model}:generateContent for Gemini image models.

The Gemini response does not contain an image

Make sure generationConfig.responseModalities contains "IMAGE". Also check the response for an error or safety block.

Write effective prompts

Specify the style: photorealistic, oil painting, watercolor, 3D render
Include lighting details: golden hour, studio lighting, dramatic shadows
Specify the composition: close-up, wide angle, bird’s-eye view, portrait orientation
Add quality modifiers: highly detailed, 4K, professional photography

Quick Start

Code

Mainstream AI Tools

Media Generation

Popular models

Dashboard

Reference

Generate and Edit Images with GPT and Gemini Models via Flatkey

Supported image models

Use gpt-image-2

Use the OpenAI SDK

Generate an image with curl

Edit an image with curl

Use Gemini image models

Use curl

Use Python and save the image

Use Node.js and save the image

Gemini request fields

Gemini response format

Troubleshooting

The API returns get_channel_failed

The Gemini response does not contain an image

Write effective prompts

​Supported image models

​Use gpt-image-2

​Use the OpenAI SDK

​Generate an image with curl

​Edit an image with curl

​Use Gemini image models

​Use curl

​Use Python and save the image

​Use Node.js and save the image

​Gemini request fields

​Gemini response format

​Troubleshooting

​The API returns get_channel_failed

​The Gemini response does not contain an image

​Write effective prompts

Supported image models

Use gpt-image-2

Use the OpenAI SDK

Generate an image with curl

Edit an image with curl

Use Gemini image models

Use curl

Use Python and save the image

Use Node.js and save the image

Gemini request fields

Gemini response format

Troubleshooting

The API returns get_channel_failed

The Gemini response does not contain an image

Write effective prompts