Image Generation and Editing API

Use /v1/images/generations to generate an image from a text prompt and /v1/images/edits to edit an input image. Both endpoints use OpenAI Images-compatible request shapes. Available operations depend on the model and channel exposed by your Flatkey service.

Gemini image models use the native Gemini generateContent endpoint and cannot be called through these OpenAI Images endpoints. See the Gemini image model guide.

Generate an image

Endpoint

POST https://router.flatkey.ai/v1/images/generations

Headers

Header	Value
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

JSON body parameters

string

required

Image model ID exposed by your Flatkey service, such as "gpt-image-2".

string

required

Text description of the image to generate.

string

Output dimensions, such as "1024x1024". Supported values depend on the model.

string

Output quality: "low", "medium", or "high". If omitted, the upstream default is used. Higher quality increases latency and usage.

string

Background handling, such as "transparent" or "opaque", when supported by the model.

string

Output format, such as "png", "jpeg", or "webp", when supported by the model.

integer

Output compression level, when supported by the model.

string

Content moderation level, when supported by the model.

string

gpt-image-2 results are returned in data[].b64_json. Hosted image URLs are not provided, and response_format: "url" is unsupported.

integer

Requested image count. gpt-image-2 currently returns one image per request because its upstream image tool does not accept n. Send multiple requests if you need multiple images.

boolean

Set to true to receive an SSE response. Omit it for a synchronous response.

Example requests

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 futuristic city skyline at dusk, cyberpunk style",
    size="1024x1024",
    quality="high",
)

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 futuristic city skyline at dusk, cyberpunk style",
  size: "1024x1024",
  quality: "high",
});

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

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 serene forest clearing with morning mist and sunbeams",
    "size": "1024x1024",
    "quality": "high"
  }'

Edit an image

/v1/images/edits accepts an input image and editing instructions as multipart/form-data.

Endpoint

POST https://router.flatkey.ai/v1/images/edits

Headers

Header	Value
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`multipart/form-data`; curl adds the boundary automatically when you use `-F`

Form fields

Field	Type	Required	Description
`model`	string	Yes	Image model ID exposed by your Flatkey service, such as `gpt-image-2`.
`prompt`	string	Yes	Instructions describing how to edit the image.
`image`	file	Yes	Input image in PNG, JPEG, or WebP format. For multiple images, use `image[]` or indexed fields such as `image[0]` and `image[1]`.
`mask`	file	No	Mask for inpainting. Transparent areas identify the regions to redraw.
`size`	string	No	Output dimensions. Supported values depend on the model.
`quality`	string	No	Output quality: `low`, `medium`, or `high`.
`stream`	boolean	No	Set to `true` to receive an SSE response.

Example request

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"

The mask field is optional. Omit it to edit the whole image based on the prompt. Do not set the Content-Type header manually; curl derives the correct multipart boundary from the -F fields.

If a supplied mask is damaged, unreadable, or exceeds the service limit, the request fails instead of falling back to a whole-image edit.

Response

Synchronous generation and editing requests return the same response shape. Flatkey returns the image as base64 data; it does not provide a hosted image URL for gpt-image-2.

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA...",
      "revised_prompt": "Add a small yellow five-pointed star in the center...",
      "url": ""
    }
  ]
}

Response fields

integer

Unix timestamp of when the request completed.

array

Array of image objects.

Show image object

string

Base64-encoded image data.

string

The prompt actually used by the model after rewriting.

string

Empty for gpt-image-2; hosted URLs are not provided.

For edits, the input image also counts toward model usage, so an edit typically consumes more usage than text-only image generation.

Streaming

Set stream to true in a generation JSON body or add -F "stream=true" to an edit request to receive text/event-stream output. The final event contains the image result, followed by data: [DONE].

Event	Meaning
`image_generation.completed`	Image generation completed.
`image_edit.completed`	Image editing completed.
`[DONE]`	The stream has ended.

Streaming support can depend on the selected model and channel. For synchronous high-quality requests, configure a client timeout of at least 150 seconds.

Overview

Endpoints

Image Generation and Editing API

Generate an image

Endpoint

Headers

JSON body parameters

Example requests

Edit an image

Endpoint

Headers

Form fields

Example request

Response

Response fields

Streaming

​Generate an image

​Endpoint

​Headers

​JSON body parameters

​Example requests

​Edit an image

​Endpoint

​Headers

​Form fields

​Example request

​Response

​Response fields

​Streaming

Generate an image

Endpoint

Headers

JSON body parameters

Example requests

Edit an image

Endpoint

Headers

Form fields

Example request

Response

Response fields

Streaming