← Back to docs

Image generation

A dedicated endpoint for creating and editing images. Compatible with the OpenAI SDK — client.images.generate() works as-is. Images are returned as base64.

POST /api/v1/images/generations

Generate an image from a text prompt; for editing, pass source images in the image parameter

You can also get images from the regular /chat/completions endpoint, but there you cannot set the aspect ratio or resolution. Use this endpoint for full control.

What each model supports

This table is built from measured data: providers often declare parameter support that does not match reality, so only what live requests confirmed is listed here.

Recommended Model	`aspect_ratio`	`image_size`	`seed`	Price
`google/gemini-3.1-flash-lite-image`	✓	1K	✓	3–4 ₽
`google/gemini-2.5-flash-image`	✓	—	✓	3–4 ₽
`google/gemini-nano-banana-2.1`	✓	1K, 2K, 4K	✓	4–14 ₽
`openai/gpt-5-image-mini`	—	—	—	4–5 ₽
`google/gemini-3.1-flash-image`	✓	1K, 2K	✓	6–11 ₽
`openai/gpt-5.4-image-2`	✓	—	—	12–23 ₽
`google/gemini-3-pro-image`	✓	—	✓	15–18 ₽

Passing a parameter a model does not support returns a 400 listing the valid values — you are not charged.

Accepted values

Recommended Model	`aspect_ratio`	`image_size`
`google/gemini-3.1-flash-lite-image`	`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`	`1K`
`google/gemini-2.5-flash-image`	`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`	not supported
`google/gemini-nano-banana-2.1`	`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`	`1K`, `2K`, `4K`
`openai/gpt-5-image-mini`	not supported	not supported
`google/gemini-3.1-flash-image`	`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`	`1K`, `2K`
`openai/gpt-5.4-image-2`	`1:1`, `2:3`, `3:2`, `9:16`, `16:9`	not supported
`google/gemini-3-pro-image`	`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`	not supported

Simple generation

The minimal request: a model and a text prompt.

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://rus-gpt.com/api/v1",
    api_key="rusgpt-YOUR_API_KEY",
)

img = client.images.generate(
    model="google/gemini-3.1-flash-lite-image",
    prompt="A cosy cabin in a winter forest at sunrise",
)

entry = img.data[0]
# output_format tells you what you actually got — models differ (PNG vs JPEG).
with open(f"out.{entry.output_format}", "wb") as f:
    f.write(base64.b64decode(entry.b64_json))

curl https://rus-gpt.com/api/v1/images/generations \
  -H "Authorization: Bearer rusgpt-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-lite-image",
    "prompt": "A cosy cabin in a winter forest at sunrise"
  }' | jq -r '.data[0].b64_json' | base64 -d > out.jpg
# the lite model returns JPEG; the actual format is in the response mime_type / output_format fields.

import base64, requests

resp = requests.post(
    "https://rus-gpt.com/api/v1/images/generations",
    headers={"Authorization": "Bearer rusgpt-YOUR_API_KEY"},
    json={
        "model": "google/gemini-3.1-flash-lite-image",
        "prompt": "A cosy cabin in a winter forest at sunrise",
    },
    timeout=300,
)
resp.raise_for_status()
entry = resp.json()["data"][0]

# mime_type / output_format tell you what you actually got: models differ
# (lite-image returns JPEG, 3.1-flash-image returns PNG).
ext = entry["output_format"]
open(f"out.{ext}", "wb").write(base64.b64decode(entry["b64_json"]))

Google models (Gemini / Nano Banana)

They support aspect ratio and the seed parameter; some of them also let you pick the resolution.

import base64
from openai import OpenAI

client = OpenAI(base_url="https://rus-gpt.com/api/v1", api_key="rusgpt-YOUR_API_KEY")

img = client.images.generate(
    model="google/gemini-3.1-flash-image",
    prompt="A cosy cabin in a winter forest at sunrise",
    # Non-OpenAI params go through extra_body with the OpenAI SDK.
    extra_body={
        "aspect_ratio": "16:9",   # 1376x768
        "image_size": "2K",       # 2048px on the long side
        "seed": 42,               # forwarded upstream; reproducibility NOT guaranteed
    },
)

open("wide.png", "wb").write(base64.b64decode(img.data[0].b64_json))

curl https://rus-gpt.com/api/v1/images/generations \
  -H "Authorization: Bearer rusgpt-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A cosy cabin in a winter forest at sunrise",
    "aspect_ratio": "16:9",
    "image_size": "2K",
    "seed": 42
  }'

The seed parameter is forwarded to the provider, but reproducibility is not guaranteed: the same prompt and seed can produce different images (verified 11-08-2026).

OpenAI models (GPT Image)

They accept a prompt and reference images for editing; their parameter set is narrower than Gemini's.

import base64
from openai import OpenAI

client = OpenAI(base_url="https://rus-gpt.com/api/v1", api_key="rusgpt-YOUR_API_KEY")

img = client.images.generate(
    model="openai/gpt-5.4-image-2",
    prompt="A cosy cabin in a winter forest at sunrise",
    extra_body={"aspect_ratio": "16:9"},   # image_size / seed are NOT supported here
)

open("out.png", "wb").write(base64.b64decode(img.data[0].b64_json))

curl https://rus-gpt.com/api/v1/images/generations \
  -H "Authorization: Bearer rusgpt-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-image-2",
    "prompt": "A cosy cabin in a winter forest at sunrise",
    "aspect_ratio": "16:9"
  }'

Note: OpenAI models support neither image_size nor seed, and gpt-5-image-mini does not support aspect_ratio either. A request with an unsupported parameter returns a 400 unsupported_parameter error naming the parameter — nothing is charged. These models are also noticeably slower — generation can take up to two minutes.

Editing images

Pass one or more source images in the image parameter — either as a base64 data URI or as a public https URL. The prompt describes what to change.

import base64, requests

ref = base64.b64encode(open("photo.jpg", "rb").read()).decode()

resp = requests.post(
    "https://rus-gpt.com/api/v1/images/generations",
    headers={"Authorization": "Bearer rusgpt-YOUR_API_KEY"},
    json={
        "model": "google/gemini-3.1-flash-image",
        "prompt": "Replace the background with a sunset sky",
        "image": [f"data:image/jpeg;base64,{ref}"],   # up to 14 references
    },
    timeout=300,
)

entry = resp.json()["data"][0]
open("edited." + entry["output_format"], "wb").write(base64.b64decode(entry["b64_json"]))

# A reference image is passed as a data URI (or a public http(s) URL).
REF=$(base64 -w0 photo.jpg)

curl https://rus-gpt.com/api/v1/images/generations \
  -H "Authorization: Bearer rusgpt-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"google/gemini-3.1-flash-image\",
    \"prompt\": \"Replace the background with a sunset sky\",
    \"image\": [\"data:image/jpeg;base64,$REF\"]
  }"

Request parameters

Parameter	Description
`model`	Model ID — list: `GET /api/v1/images/models`
`prompt`	Text description of the image (required)
`aspect_ratio`	Aspect ratio: `1:1`, `16:9`, `9:16`, `21:9`, `4:3` etc. Support varies by model
`image_size`	Resolution: `1K` or `2K` (supported models only — see `capabilities` in the models list)
`size`	OpenAI-compatible alternative to aspect_ratio: `1024x1024`, `1536x1024`, `1024x1536`
`image`	Source images for editing (base64 data URIs or https URLs)
`seed`	For reproducible results (Gemini models)
`n`	Number of images. Every model currently supports `1` only.

The OpenAI parameters quality, style, background, output_format, output_compression, moderation and partial_images are not supported and return a 400. We reject them deliberately rather than ignore them silently — otherwise you would pay for an image that ignored what you asked for.

Response format

The response follows the OpenAI Images shape, plus fields for the real file format and the exact amount charged:

{
  "created": 1786000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg...",
      "mime_type": "image/png",
      "output_format": "png",
      "revised_prompt": "..."
    }
  ],
  "usage": {
    "input_tokens": 7,
    "output_tokens": 1120,
    "total_tokens": 1127,
    "cost": 6.72
  }
}

The file format depends on the model: some return PNG, others JPEG. Rely on mime_type and output_format rather than assuming an extension. usage.cost is exactly the amount in roubles deducted from your balance.

Listing models and their capabilities

The current list, with a capabilities field per model, needs no authentication:

curl https://rus-gpt.com/api/v1/images/models

Errors

Code	Description
`400 unsupported_parameter`	The parameter is not supported by this model. The error message lists what is available.
`400 invalid_value`	Invalid parameter value (for example, an aspect ratio outside the supported list).
`402`	Insufficient funds
`429`	Rate limit exceeded: 20 requests per minute and up to 5 concurrent generations.
`502 no_image_generated`	The model returned no image. You are not charged — retry the request.

Pricing

Billing is token-based at the model's rates; the Price column in the table above is the measured cost of one image (a range when it depends on size or aspect ratio). On Google models a 1K image is 1120 output tokens and 2K is 1680; OpenAI models spend noticeably more tokens per image, including input tokens. Reference images bill extra input tokens on top. Rejected requests (400 and 429) are never billed.

Full model list with current prices: Models page