Skip to main content

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/generations and POST /v1/images/edits. The OpenAI SDKs' images.generate() and images.edit() work unchanged once base_url points at MindsHub.
  • OpenRouter's images API: POST /v1/images, which names a size as a resolution and an aspect_ratio and takes reference images as input_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​

AliasUse it for
gpt-image-2.6-flareFast, everyday generation and editing. The default image model.
gpt-image-2.6-sunburstDetailed 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​

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)

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.

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",
)

/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:

QualityImage output tokensAbout, per image
low824$0.025
medium1,449$0.043
high1,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 413 with code: request_too_large.
  • Streaming (stream, partial_images) is not supported yet; either is a 400.
  • A request gets 110 seconds. Past that it is answered with 503 carrying upstream_status: 504 and code: 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​

StatuscodeWhen
400invalid_param (param: "model")The model is not an image model.
400moderation_blockedThe provider's safety system refused the prompt or a reference image. The message says why.
400invalid_param / param_not_supportedA parameter is out of range or not served here; param names it.
402wallet_emptyNo balance to cover the request. Nothing was generated.
413request_too_largeThe request body is larger than 50 MiB. Send fewer or smaller images.
429rate_limitedYour rate limit, or the provider's. Honor Retry-After.
503image_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​

ParameterHandlingNotes
modeladaptedAn 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.
promptforwardedRelayed as sent. The provider enforces its length limit.
nforwarded1-10. Billed per image the provider returns, and reserved against your rate limit before the call.
sizeforwardedRelayed 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.
qualityforwardedlow, medium, high or auto. Higher quality uses more image output tokens, and costs more.
backgroundforwardedRelayed as sent.
output_formatforwardedpng (the default), jpeg or webp.
output_compressionforwarded0-100, for jpeg and webp.
moderationforwardedRelayed as sent.
userforwardedRelayed to the provider. Requests are attributed by API key.
response_formatrejected (400)Images always come back as b64_json; url is a 400, because MindsHub does not host generated images. b64_json is accepted.
styleignoredA DALL-E 3 parameter that GPT Image models do not read.
partial_imagesrejected (400)Streaming partial images is not served yet; a value is a 400. Omit it.
streamrejected (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​

ParameterHandlingNotes
modeladaptedAn 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.
promptforwardedRelayed as sent. The provider enforces its length limit.
nforwarded1-10. Billed per image the provider returns, and reserved against your rate limit before the call.
sizeforwardedRelayed 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.
qualityforwardedlow, medium, high or auto. Higher quality uses more image output tokens, and costs more.
backgroundforwardedRelayed as sent.
output_formatforwardedpng (the default), jpeg or webp.
output_compressionforwarded0-100, for jpeg and webp.
userforwardedRelayed to the provider. Requests are attributed by API key.
response_formatrejected (400)Images always come back as b64_json; url is a 400, because MindsHub does not host generated images. b64_json is accepted.
partial_imagesrejected (400)Streaming partial images is not served yet; a value is a 400. Omit it.
streamrejected (400)Streaming is not served yet; true is a 400.
imageforwarded1-16 files, sent as repeated image or image[] multipart fields, each up to 20 MiB. Each reference image bills as image input tokens.
maskforwardedA PNG the size of the first image; relayed as sent.
input_fidelityforwardedRelayed 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​

ParameterHandlingNotes
modeladaptedAn 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.
promptforwardedRelayed as sent.
nforwarded1-10.
resolutionadaptedTurned 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_ratioadaptedW: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.
sizeadaptedA resolution tier (same as resolution) or WIDTHxHEIGHT, relayed as sent.
input_referencesadaptedUp 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).
qualityforwardedRelayed as sent.
output_formatforwardedpng, jpeg or webp.
output_compressionforwarded0-100, for jpeg and webp.
backgroundforwardedRelayed as sent.
seedignoredGPT Image models take no seed.
userforwardedRelayed to the provider.
session_idignoredUse the Langfuse-Session-Id header to group requests.
streamrejected (400)Streaming is not served yet; true is a 400.
providerignoredMindsHub routes by the model alias.
traceignoredUse 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.