Models & routing

Models

322 models are listed in the current catalog. Copy the exact ID and use the endpoints supported by that model.

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.

Set your key
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.

List models
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.

Send a text request
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.

Use a listed alias
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.

Catalog shape
{
  "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.input_modalities in the public catalog for image, and architecture.output_modalities 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_url.url 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.

Chat Completions with images
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].message.content. For a local image, use a base64 data URL such as data:image/png;base64,YOUR_BASE64_IMAGE in image_url.url. Set stream: true to stream the text response.

Responses with images

Use input_image content parts on the Responses endpoint. Replace image_url with your HTTPS image URL or base64 data URL.

Responses with images
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: "output_text". Keep store: false and supply conversation history on each turn. Set stream: true to stream the answer. Tool results can also include input_image parts when their matching tool call is in the supplied history.

Messages with images

Use a type: "image" block alongside your prompt. Replace source.url with your publicly accessible HTTPS image URL.

Messages with images
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: "text". For a local file, replace the image's source object with {"type":"base64","media_type":"image/png","data":"YOUR_BASE64_IMAGE"}. 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 /v1/images/generations. It saves the response to response.json and its headers to response.headers.

Images API
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].b64_json to save the PNG:

Images API
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.operations and image.controls in the public catalog. Model-specific settings must be listed in image.controls; other provider settings are rejected. Where image.controls.quality is present, choose a quality from that list and a size from image.controls.size. Omitted values use image.controls.defaults. The matching entry in image.pricing.variants 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.edit is present, use POST /v1/images/edits 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.image_input, 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 /v1/images/status?request_id=YOUR_REQUEST_ID with the same account before resubmitting an uncertain request. Disable automatic retries.

If you cache image catalog records, refresh them after catalog_expires_at. 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.