Models & routing
Models
322 models are listed in the current catalog. Copy the exact ID and use the endpoints supported by that model.
Choose an exact model.
Compare prices and capabilities, then copy its ID into your request.
Browse the catalog →Let Auto choose.
Use an intent such as smart, cheap, or code. Auto selects a model for you.
Explore Auto routing →1. Set your API key
Create a key and save the key and recovery link. Replace paste-your-api-key-here with your key, then run this in your terminal.
export MINIROUTER_KEY='paste-your-api-key-here'The example below uses a paid model. Add credits first, or follow the Auto Free guide to send a request without a deposit.
2. Choose a model
Run this command to list models. Copy an id in author/name format from the response.
curl https://api.minirouter.sh/v1/models \
-H "Authorization: Bearer $MINIROUTER_KEY"You can also browse models for prices and supported features. Choose a text model for the Chat Completions request below.
For text models with published measurements, compare quality and monthly cost in Model Finder before choosing an exact ID.
3. Send a request
Run this in the same terminal. To use another text model, replace the model value with its exact ID.
curl https://api.minirouter.sh/v1/chat/completions \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "abliteration/abliterated-model",
"messages": [
{
"role": "user",
"content": "Explain an API gateway in one sentence."
}
],
"max_tokens": 256
}'Read the answer in choices[0].message.content and the request cost in usage.cost.
For typed boolean, choice and score questions, see the evaluation API preview. For text to speech, transcription and audio input, see the Audio API. For video, see the Video API.
Next, set request parameters, enable thinking, or request structured output. To receive the answer as it arrives, see streaming.
Let Auto choose a model
Use minirouter/auto as the model value to let MiniRouter choose. The x-minirouter-model header names the model that answered. Paid intents include :smart (the default), :cheap, :code, and :roleplay. See the current choices and how Auto chooses.
For no-deposit requests, use minirouter/auto:free. Check availability and follow the Auto Free guide for its account limits.
Model aliases
Follow a family's newest model, keep IDs from other gateways, or pin an exact ID.
Aliases are alternate names listed in a model’s aliases array. Copy a listed alias into the model field, just as you would a model ID.
Aliases ending in -latest follow the newest model in a family, such as anthropic/claude-opus-latest. Model IDs used by other gateways, such as x-ai/grok-4.6, also work.
curl https://api.minirouter.sh/v1/chat/completions \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-fable-latest",
"messages": [
{
"role": "user",
"content": "Explain an API gateway in one sentence."
}
],
"max_tokens": 256
}'An alias can point to a different model over time, changing its capabilities and price. Use the concrete model ID to keep your requests on the same model. Your key must allow that model.
The response model and x-minirouter-model header identify the model that answered. Request logs also record the alias you requested.
Client-compatible catalog
Public model metadata, capabilities, modalities, and pricing.
GET /api/v1/modelsis public. It returns each model’s input and output modalities, capabilities and prices. Models that accept images can answer in text. Models that generate images list their own prices and supported settings.
{
"data": [
{
"type": "language",
"id": "abliteration/abliterated-model",
"name": "Abliterated Model",
"context_length": 262144,
"released": 1781308800,
"description": "abliteration.ai general-purpose reasoning model with its refusal behaviour removed. Zero data retention. Text and up to four base64 images per request on MiniRouter.",
"supported_parameters": [
"max_tokens",
"temperature",
"top_p",
"frequency_penalty",
"presence_penalty",
"stop",
"seed",
"tools",
"tool_choice",
"reasoning"
],
"architecture": {
"modality": "text+image->text",
"input_modalities": [
"text",
"image"
],
"output_modalities": [
"text"
]
},
"pricing": {
"prompt": "0.00000105",
"completion": "0.00000315",
"request": "0",
"image": "0"
},
"top_provider": {
"context_length": 262144,
"max_completion_tokens": 32768
},
"per_request_limits": null
}
]
}Fallback models
Try an ordered list of models you explicitly allow.
For text requests, send models with an ordered list of acceptable fallback IDs. minirouter never chooses a model outside that list.
Every model must share a provider qualified for your request. Incompatible lists are rejected before dispatch. Do not combine a fallback list with minirouter/auto. See model fallbacks for request examples, limits and billing.
Send images to a model
Image inputs, supported formats, and request examples.
Image input (vision)
Models that accept images can describe photos, read screenshots, and extract information from charts. Examples include GPT 5.6 Sol, Claude Opus 5, Gemini 2.5 Flash, and GPT 4.1 Mini.
Check architecture. in the
public catalog for image, and
architecture. for the response type. Check the exact
model ID: variants can have different capabilities. An image input capability
does not mean the model generates images.
Send images alongside your prompt using Chat Completions, Responses, or Messages. Use a publicly accessible HTTPS image URL or base64-encoded JPEG, PNG, GIF or WebP. You can include up to 20 images per request, within the request body size limit. Set your API key and add credits as shown above before running these examples.
Image requests can require a larger temporary hold: MiniRouter reserves enough for the model's full input capacity, since an image URL does not reveal its token count. Final billing uses the provider's actual usage and cost.
Chat Completions with images
Run this example, replacing image_ with your own image URL.
The prompt and image go in the same user message's content array.
detail accepts auto, low, or high where supported by the model.
curl --fail-with-body https://api.minirouter.sh/v1/chat/completions \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "openai/gpt-5.6-sol",
"max_tokens": 512,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe what you see in this image."
},
{
"type": "image_url",
"image_url": {
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/1024px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
"detail": "auto"
}
}
]
}
]
}'Read the answer in choices[0].. For a local image, use a
base64 data URL such as data: in
image_. Set stream: to stream the text response.
Responses with images
Use input_ content parts on the Responses endpoint. Replace
image_ with your HTTPS image URL or base64 data URL.
curl --fail-with-body https://api.minirouter.sh/v1/responses \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "openai/gpt-5.6-sol",
"store": false,
"max_output_tokens": 512,
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Describe what you see in this image."
},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/1024px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
"detail": "auto"
}
]
}
]
}'Read text from output message items' content blocks with
type:. Keep store: and supply conversation history
on each turn. Set stream: to stream the answer. Tool results can also
include input_ parts when their matching tool call is in the supplied history.
Messages with images
Use a type: block alongside your prompt. Replace source.
with your publicly accessible HTTPS image URL.
curl --fail-with-body https://api.minirouter.sh/v1/messages \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-H "anthropic-version: 2023-06-01" \
--data '{
"model": "openai/gpt-5.6-sol",
"max_tokens": 512,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe what you see in this image."
},
{
"type": "image",
"source": {
"type": "url",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/1024px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
}
]
}
]
}'Read the answer in response content blocks with type:.
For a local file, replace the image's source object with
{"type":.
Use raw base64 without a data-URL prefix on this endpoint.
To generate an image or edit an existing image, use the Images API below.
Generate images
Image models, supported settings, and response formats.
Images API
Generate images with any model listed under Images on the models page. Each model page lists its price, the settings it accepts, and examples for the operations it supports.
GPT Image models:
Set your API key as shown above and add credits, then run this request to
POST /. It saves the response to response. and
its headers to response..
curl --fail-with-body --retry 0 --max-time 120 \
https://api.minirouter.sh/v1/images/generations \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-D response.headers --output response.json \
--data '{
"model": "openai/gpt-image-2.5-flare",
"prompt": "A blue circle on a white background.",
"quality": "low",
"size": "1024x1024",
"output_format": "png",
"n": 1
}'After a successful response, decode data[0]. to save the PNG:
python3 -c 'import base64,json; r=json.load(open("response.json")); open("image.png","wb").write(base64.b64decode(r["data"][0]["b64_json"]))'Check the model's image. and image. in the
public catalog.
Model-specific settings must be listed in image.; other provider settings are rejected.
Where image. is present, choose a quality from that list and
a size from image.. Omitted values use image..
The matching entry in image. gives the output-image estimate
for that size and quality; add prompt and reference-image costs when estimating
the total. Higher quality and larger images can cost more. Auto settings let the
provider choose and reserve credit for the largest or highest-quality output it
may choose. Image Studio shows the estimate for your selected settings.
A generation capability does not imply editing. Where operations. is
present, use POST / with multipart form data and one image.
GPT Image 2.5 Flare and Sunburst require a 1024 × 1024 PNG; other editors accept
PNG, JPEG or WebP up to 1,048,576 pixels. Where the catalog lists a non-zero
pricing., the longer side can be at most 4,096 pixels. A file can
be at most 8 MiB. Use a mask only when the exact model's edit capability allows it.
Each request returns one image. Copy the required settings from the model page; GPT Image controls and sizes do not apply to every image model. Catalog prices show their unit: per-image reservation estimates and token reservation rates are different quantities. Final billing uses the provider's actual cost plus the MiniRouter fee. Use a concrete image model ID or one of its listed aliases. Image requests do not use Auto or text-model fallback lists.
A temporary hold reserves twice the estimated cost, including the MiniRouter
fee. The final charge cannot exceed that hold. The image response can arrive
before billing finishes. Keep x-minirouter-request-id from the response
headers and check GET / with the
same account before resubmitting an uncertain request. Disable automatic retries.
If you cache image catalog records, refresh them after catalog_.
The image endpoints do not serve video, embedding, reranking or realtime requests:
embeddings and reranking have their own endpoints, speech and transcription use the
Audio API, video uses the
Video API, and realtime is not offered.
When an ID is wrong
An unavailable ID returns 404 unknown_model with a did-you-mean suggestion and a link to the current list. A real ID this key’s policy excludes returns 403 model_not_allowed.