Image generation
Generate images from a prompt, or edit images you already have, through your MindsHub API key. Two request shapes are served:
- OpenAI's images API:
POST /v1/images/generationsandPOST /v1/images/edits. The OpenAI SDKs'images.generate()andimages.edit()work unchanged oncebase_urlpoints at MindsHub. - OpenRouter's images API:
POST /v1/images, which names a size as aresolutionand anaspect_ratioand takes reference images asinput_references.
Image models are their own part of the catalog: list them with GET /v1/models?kind=image. The plain listing leaves them out. They can't chat, and chat models can't make images. Sending one to the other's endpoint is a 400 naming model.
Models
| Alias | Use it for |
|---|---|
gpt-image-2.6-flare | Fast, everyday generation and editing. The default image model. |
gpt-image-2.6-sunburst | Detailed compositions, and edits where precision matters most. |
Both are OpenAI's GPT Image 2.6 models, at OpenAI's list prices. Prices are on Billing. Image models bill to the wallet only and never draw the included allowance.
Generate an image
- Python
- TypeScript
- curl
import base64
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.mindshub.ai/v1", api_key=os.environ["MINDSHUB_API_KEY"])
result = client.images.generate(
model="gpt-image-2.6-flare",
prompt="A watercolor fox in a snowy birch forest, morning light",
size="1536x1024",
quality="medium",
)
with open("fox.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
print(result.usage)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.mindshub.ai/v1", apiKey: process.env.MINDSHUB_API_KEY });
const result = await client.images.generate({
model: "gpt-image-2.6-flare",
prompt: "A watercolor fox in a snowy birch forest, morning light",
size: "1536x1024",
quality: "medium",
});
fs.writeFileSync("fox.png", Buffer.from(result.data[0].b64_json!, "base64"));
curl https://api.mindshub.ai/v1/images/generations \
-H "Authorization: Bearer $MINDSHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.6-flare", "prompt": "A watercolor fox in a snowy birch forest", "size": "1024x1024"}' \
| jq -r '.data[0].b64_json' | base64 --decode > fox.png
Images always come back inline as base64 in data[].b64_json; MindsHub does not host them, so response_format: "url" is a 400. Ask for up to 10 at once with n.
Edit an image
Send one or more images and say what to change. Add a mask (a PNG whose transparent areas mark where to edit) to limit the change to part of the first image.
- Python
- TypeScript
- curl
import base64
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.mindshub.ai/v1", api_key=os.environ["MINDSHUB_API_KEY"])
result = client.images.edit(
model="gpt-image-2.6-flare",
image=open("fox.png", "rb"),
prompt="Make the background a deep blue night sky",
)
with open("fox-night.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
# Several reference images in one request:
combined = client.images.edit(
model="gpt-image-2.6-sunburst",
image=[open("product.png", "rb"), open("logo.png", "rb")],
prompt="A studio photo of the product with the logo printed on it",
)
import fs from "node:fs";
import OpenAI, { toFile } from "openai";
const client = new OpenAI({ baseURL: "https://api.mindshub.ai/v1", apiKey: process.env.MINDSHUB_API_KEY });
const result = await client.images.edit({
model: "gpt-image-2.6-flare",
image: await toFile(fs.createReadStream("fox.png"), null, { type: "image/png" }),
prompt: "Make the background a deep blue night sky",
});
fs.writeFileSync("fox-night.png", Buffer.from(result.data[0].b64_json!, "base64"));
curl https://api.mindshub.ai/v1/images/edits \
-H "Authorization: Bearer $MINDSHUB_API_KEY" \
-F model=gpt-image-2.6-flare \
-F "image[]=@fox.png" \
-F prompt="Make the background a deep blue night sky" \
| jq -r '.data[0].b64_json' | base64 --decode > fox-night.png
/v1/images/edits takes multipart/form-data, like OpenAI's: up to 16 images as repeated image or image[] fields, each up to 20 MiB and 50 MiB in all.
OpenRouter format
POST /v1/images takes OpenRouter's request shape. A resolution tier (1K, 1.5K, 2K, 4K) and an aspect_ratio (16:9, 3:2, …) become the nearest pixel size the model accepts; leave both out and the model picks. input_references makes the request an edit.
curl https://api.mindshub.ai/v1/images \
-H "Authorization: Bearer $MINDSHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare",
"prompt": "The same fox, now wearing a red scarf",
"resolution": "1K",
"aspect_ratio": "16:9",
"input_references": [{"type": "image_url", "image_url": {"url": "https://example.com/fox.png"}}]
}'
{
"created": 1793877149,
"data": [{"b64_json": "iVBORw0KGgo…", "media_type": "image/png"}],
"usage": {
"prompt_tokens": 1060,
"completion_tokens": 1132,
"total_tokens": 2192,
"completion_tokens_details": {"image_tokens": 1132},
"cost": null
}
}
A reference URL must be a public https URL or a data: URL; MindsHub downloads remote ones itself (public hosts only, 20 MiB each). A reference that is not PNG, JPEG or WebP, such as a GIF, is converted to PNG, whether inline or downloaded, if it is at most 16,777,216 pixels (4096x4096) and 16,384 pixels on its longest side; a larger one, or an icon file (ICO, CUR, ICNS), is a 400. usage.cost is null: a request is priced after it is served, so its cost appears on your usage dashboard and on GET /v1/usage/sessions/{id} rather than in the response. Errors use the OpenAI error envelope, as on every other MindsHub endpoint.
Quality, size and cost
quality is low, medium, high or auto (the default). Higher quality and larger sizes use more image output tokens. Measured on gpt-image-2.6-flare at 1024x1024:
| Quality | Image output tokens | About, per image |
|---|---|---|
low | 824 | $0.025 |
medium | 1,449 | $0.043 |
high | 1,758 | $0.053 |
size is auto, one of 1024x1024, 1536x1024 and 1024x1536, or another WIDTHxHEIGHT within the model's limits: both edges multiples of 16, no edge over 3840 px, and no wider than 3:1 either way.
Billing
Each request bills three things at the model's own rates, all reported in usage:
- text input tokens: the prompt (
usage.input_tokens_details.text_tokens); - image input tokens: any reference images on an edit, about 1,000 for a 1024x1024 image (
usage.input_tokens_details.image_tokens); - image output tokens: the images returned (
usage.output_tokens_details.image_tokens).
Your organization's balance and budgets are checked before anything is generated, as on every model: with an empty wallet the request is refused with 402 wallet_empty (or 429), and with a spent budget for your organization, a workspace, a key, a team or a member, with 402 budget_exceeded, whose error.budget_scope names which. Either way it costs nothing. MindsHub also reserves an estimate of the request's tokens against your rate limit, settled to the real usage afterwards.
You pay for what the provider charges for. A request that fails before the provider answers bills nothing. If it times out or loses its connection after the provider received it, it also bills nothing, but the tokens reserved for it stay counted against your rate limit until it refills. A refusal by the provider's safety system bills only the usage the provider reports for it.
Limits
n: 1 to 10 images per request.- Edits: up to 16 reference images, 20 MiB each.
- A request body may be up to 50 MiB, reference images included; a larger one is a
413withcode: request_too_large. - Streaming (
stream,partial_images) is not supported yet; either is a400. - A request gets 110 seconds. Past that it is answered with
503carryingupstream_status: 504andcode: image_generation_timeout: ask for fewer images, a lower quality or a smaller size. The response tells SDKs not to retry it, because a resend generates the images again. Rate limits apply as on every model.
Errors
| Status | code | When |
|---|---|---|
400 | invalid_param (param: "model") | The model is not an image model. |
400 | moderation_blocked | The provider's safety system refused the prompt or a reference image. The message says why. |
400 | invalid_param / param_not_supported | A parameter is out of range or not served here; param names it. |
402 | wallet_empty | No balance to cover the request. Nothing was generated. |
413 | request_too_large | The request body is larger than 50 MiB. Send fewer or smaller images. |
429 | rate_limited | Your rate limit, or the provider's. Honor Retry-After. |
503 | image_generation_timeout (upstream_status: 504) | The request ran past its 110-second budget. Not retried automatically. |
503 | (upstream_status: 502) | The provider could not be reached, or refused MindsHub's own credentials. Not retried automatically. |
Parameters
POST /v1/images/generations
| Parameter | Handling | Notes |
|---|---|---|
model | adapted | An image alias from GET /v1/models?kind=image resolves to a concrete provider model. A chat or embedding alias is a 400, as is an image alias on a chat endpoint. |
prompt | forwarded | Relayed as sent. The provider enforces its length limit. |
n | forwarded | 1-10. Billed per image the provider returns, and reserved against your rate limit before the call. |
size | forwarded | Relayed as sent; the provider validates it. GPT Image 2.6 takes auto, the three standard sizes (1024x1024, 1536x1024, 1024x1536) and other WIDTHxHEIGHT values within its limits. |
quality | forwarded | low, medium, high or auto. Higher quality uses more image output tokens, and costs more. |
background | forwarded | Relayed as sent. |
output_format | forwarded | png (the default), jpeg or webp. |
output_compression | forwarded | 0-100, for jpeg and webp. |
moderation | forwarded | Relayed as sent. |
user | forwarded | Relayed to the provider. Requests are attributed by API key. |
response_format | rejected (400) | Images always come back as b64_json; url is a 400, because MindsHub does not host generated images. b64_json is accepted. |
style | ignored | A DALL-E 3 parameter that GPT Image models do not read. |
partial_images | rejected (400) | Streaming partial images is not served yet; a value is a 400. Omit it. |
stream | rejected (400) | Streaming is not served yet; true is a 400. |
This table is generated from GENERATION_PARAM_SUPPORT in minds/requests/images_request.py, which a unit test holds to the OpenAI SDK's own parameter list.
POST /v1/images/edits
| Parameter | Handling | Notes |
|---|---|---|
model | adapted | An image alias from GET /v1/models?kind=image resolves to a concrete provider model. A chat or embedding alias is a 400, as is an image alias on a chat endpoint. |
prompt | forwarded | Relayed as sent. The provider enforces its length limit. |
n | forwarded | 1-10. Billed per image the provider returns, and reserved against your rate limit before the call. |
size | forwarded | Relayed as sent; the provider validates it. GPT Image 2.6 takes auto, the three standard sizes (1024x1024, 1536x1024, 1024x1536) and other WIDTHxHEIGHT values within its limits. |
quality | forwarded | low, medium, high or auto. Higher quality uses more image output tokens, and costs more. |
background | forwarded | Relayed as sent. |
output_format | forwarded | png (the default), jpeg or webp. |
output_compression | forwarded | 0-100, for jpeg and webp. |
user | forwarded | Relayed to the provider. Requests are attributed by API key. |
response_format | rejected (400) | Images always come back as b64_json; url is a 400, because MindsHub does not host generated images. b64_json is accepted. |
partial_images | rejected (400) | Streaming partial images is not served yet; a value is a 400. Omit it. |
stream | rejected (400) | Streaming is not served yet; true is a 400. |
image | forwarded | 1-16 files, sent as repeated image or image[] multipart fields, each up to 20 MiB. Each reference image bills as image input tokens. |
mask | forwarded | A PNG the size of the first image; relayed as sent. |
input_fidelity | forwarded | Relayed as sent. |
This table is generated from EDIT_PARAM_SUPPORT in minds/requests/images_request.py, which a unit test holds to the OpenAI SDK's own parameter list.
POST /v1/images
| Parameter | Handling | Notes |
|---|---|---|
model | adapted | An image alias from GET /v1/models?kind=image resolves to a concrete provider model. A chat or embedding alias is a 400, as is an image alias on a chat endpoint. |
prompt | forwarded | Relayed as sent. |
n | forwarded | 1-10. |
resolution | adapted | Turned into a pixel size with aspect_ratio: 1K is about 1024x1024 pixels in area, 1.5K 1536x1536, 2K 2048x2048 and 4K the model's largest. 512 and 768 round up to the model's smallest size. |
aspect_ratio | adapted | W:H. Ratios past the model's limit (3:1 either way on GPT Image 2.6) are clamped to it. auto, or neither resolution nor aspect_ratio, lets the model choose. |
size | adapted | A resolution tier (same as resolution) or WIDTHxHEIGHT, relayed as sent. |
input_references | adapted | Up to 16 https or data: URLs; present, the request is an edit. Remote images are downloaded by MindsHub (public hosts only, up to 20 MiB each). |
quality | forwarded | Relayed as sent. |
output_format | forwarded | png, jpeg or webp. |
output_compression | forwarded | 0-100, for jpeg and webp. |
background | forwarded | Relayed as sent. |
seed | ignored | GPT Image models take no seed. |
user | forwarded | Relayed to the provider. |
session_id | ignored | Use the Langfuse-Session-Id header to group requests. |
stream | rejected (400) | Streaming is not served yet; true is a 400. |
provider | ignored | MindsHub routes by the model alias. |
trace | ignored | Use the Langfuse-Trace-Id header to join a trace. |
This table is generated from OPENROUTER_PARAM_SUPPORT in minds/requests/images_request.py, which a unit test holds to the request model's parameter list.