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
POST https://api.qubax.ai/v1/images/generationsAll requests require an API key passed as a Bearer token in the Authorization header:
Authorization: Bearer qbx_live_...
Content-Type: application/jsonRequest Body
The request body is a JSON object with the parameters below.
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | ID of the model to use (e.g. flux-1.1-pro — see /v1/models for all image models). |
| prompt | string | Yes | A text description of the desired image. Max 4,000 chars. |
| n | integer | No | Number of images to generate. Default 1. |
| size | string | No | Dimensions of the image, e.g. 1024x1024. Defaults vary by model. |
| response_format | string | No | Always 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 ID | Provider / Notes |
|---|---|
| flux-1.1-pro | Black Forest Labs Flux 1.1 — fast, high quality. Recommended default. |
| flux-2-max | Black Forest Labs Flux 2 Max — highest fidelity. |
| nano-banana-2 | Google Nano Banana 2 — strong prompt adherence. |
| gpt-image-2 | OpenAI GPT Image 2 — integrated captions, edits. |
| seedream-4.5 | ByteDance Seedream V4.5 — photorealistic. |
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:
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
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).
{
"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.
POST https://api.qubax.ai/v1/images/edits- Source image:
imageas anhttps://URL, adata: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) orinput_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 plusmodel,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,resolutionandqualityare 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.
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):
{
"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):
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):
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.