Image Generation

Generate images from a text prompt with Qubax's image generation endpoint. It mirrors the OpenAI Images API, so any client built for /v1/images/generations works unchanged when pointed at the Qubax base URL.

Endpoint

Text
POST https://api.qubax.ai/v1/images/generations

All requests require an API key passed as a Bearer token in the Authorization header:

Text
Authorization: Bearer qbx_live_...
Content-Type: application/json

Request Body

The request body is a JSON object with the parameters below.

ParameterTypeRequiredDescription
modelstringYesID of the model to use (e.g. flux-1.1-pro — see /v1/models for all image models).
promptstringYesA text description of the desired image. Max 4,000 chars.
nintegerNoNumber of images to generate. Default 1.
sizestringNoDimensions of the image, e.g. 1024x1024. Defaults vary by model.
response_formatstringNoAlways b64_json — images are returned inline as base64-encoded PNG. There is no URL mode.

Available Image Models

Qubax routes image generation through several state-of-the-art model families. The table below lists the most commonly used models (all available via /v1/models).

Model IDProvider / Notes
flux-1.1-proBlack Forest Labs Flux 1.1 — fast, high quality. Recommended default.
flux-2-maxBlack Forest Labs Flux 2 Max — highest fidelity.
nano-banana-2Google Nano Banana 2 — strong prompt adherence.
gpt-image-2OpenAI GPT Image 2 — integrated captions, edits.
seedream-4.5ByteDance Seedream V4.5 — photorealistic.
Note: Not every model supports every size or n value. When a combination is unsupported the API returns a 400 describing the constraint.

Python SDK Example

Using the OpenAI Python SDK pointed at the Qubax base URL:

Python
from openai import OpenAI

client = OpenAI(
    api_key="qbx_live_...",
    base_url="https://api.qubax.ai/v1",
)

response = client.images.generate(
    model="flux-1.1-pro",
    prompt="a cat in space, photorealistic",
    n=1,
    size="1024x1024",
)

# Images are returned inline as base64 — decode and save
import base64
from pathlib import Path
Path("cat.png").write_bytes(base64.b64decode(response.data[0].b64_json))
print("Wrote cat.png")

cURL Example

Shell
curl https://api.qubax.ai/v1/images/generations \
  -H "Authorization: Bearer qbx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "prompt": "a cat in space, photorealistic",
    "n": 1,
    "size": "1024x1024"
  }'

Response Format

A successful request returns a JSON object with a data array. Each entry contains a b64_json field holding the base64-encoded PNG image (there is no URL mode — images always come back inline).

JSON
{
  "created": 1719792000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

Saving the Image

Decode the base64 string and write the bytes to disk — in Python use base64.b64decode(response.data[0].b64_json), in shell pipe the JSON through jq -r '.data[0].b64_json' | base64 -d > image.png.

Image Editing (image-to-image)

Send an existing photo plus a prompt to get a new image, for example a product photo placed in a new advertising scene. Use an edit model (most end in -edit, e.g.nano-banana-2-edit, nano-banana-pro-edit,flux-2-max-edit, gpt-image-2-edit,seedream-v5-lite-edit). The price per edited image is listed on each model in/v1/models.

Text
POST https://api.qubax.ai/v1/images/edits
  • Source image: image as an https:// URL, a data:image/...;base64, URI, or plain base64. JPEG, PNG, WebP or GIF, up to 10 MB each.
  • Several images: up to 8 in images (OpenAI shape) or input_images. The first one is the base photo; the rest are references (style, background, a second product).
  • multipart/form-data works too: one or more image / image[] file fields plus model, prompt, size. This is what the OpenAI SDKs send.
  • Edited images come back at standard 1K resolution (about 1024 px), at a fixed price per image. size, resolution and quality are ignored on edits.
  • One edited image per request. It is synchronous and usually returns in 10–40 seconds. Masks (inpainting) are not supported yet, so describe the change in the prompt.
  • A failed request is never charged.
Shell
curl https://api.qubax.ai/v1/images/edits \
  -H "Authorization: Bearer qbx_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-shot-1" \
  -d '{
    "model": "nano-banana-2-edit",
    "prompt": "Place this exact perfume bottle on a white marble pedestal, soft golden studio light. Keep the bottle, label, logo, text, shape and colors unchanged.",
    "image": "https://example.com/product.jpg"
  }'

Multiple images (base photo + style reference):

JSON
{
  "model": "nano-banana-pro-edit",
  "prompt": "Put the product from the first image into the scene and lighting of the second image",
  "input_images": [
    { "url": "https://example.com/product.jpg", "role": "start" },
    { "url": "data:image/png;base64,iVBORw0KGgo...", "role": "reference" }
  ]
}

Python (OpenAI SDK, file upload):

Python
from openai import OpenAI
import base64

client = OpenAI(api_key="qbx_live_...", base_url="https://api.qubax.ai/v1")

result = client.images.edit(
    model="nano-banana-2-edit",
    image=open("product.jpg", "rb"),
    prompt="Luxury ad scene on marble, golden light. Keep the product unchanged.",
)
open("ad.png", "wb").write(base64.b64decode(result.data[0].b64_json))

C# / .NET (HttpClient, no SDK needed):

csharp
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var http = new HttpClient { Timeout = TimeSpan.FromSeconds(120) };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "qbx_live_...");

var photo = Convert.ToBase64String(File.ReadAllBytes("product.jpg"));
var body = JsonSerializer.Serialize(new {
    model = "nano-banana-2-edit",
    prompt = "Luxury ad scene on marble, golden light. Keep the product unchanged.",
    image = "data:image/jpeg;base64," + photo
});

var req = new HttpRequestMessage(HttpMethod.Post, "https://api.qubax.ai/v1/images/edits") {
    Content = new StringContent(body, Encoding.UTF8, "application/json")
};
req.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString()); // reuse the same value when retrying

var res = await http.SendAsync(req);
res.EnsureSuccessStatusCode();
using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
var b64 = doc.RootElement.GetProperty("data")[0].GetProperty("b64_json").GetString();
File.WriteAllBytes("ad.png", Convert.FromBase64String(b64!));

Safe retries (Idempotency-Key)

Image requests can take a while. If your client times out and retries, send the sameIdempotency-Key header (any unique string, up to 200 characters) on both attempts. A retry within 5 minutes of a successful request returns the first result again (header Idempotent-Replayed: true) and is not charged a second time. If the first attempt is still running, you get 409; wait a few seconds and retry. Failed requests are refunded and free the key.

Ready to build?

380+ models through one OpenAI & Anthropic-compatible API, up to 99% below OpenRouter.

Get your API key →