Docs — request parameters

Set your key

Create an API key, save its recovery link, and add credits. Replace the placeholder below and run it in your terminal before running the examples on this page.

Set your key

export MINIROUTER_KEY='paste-your-api-key-here'

Examples use paid models. For free requests, follow the Auto Free guide.

Send a request with parameters

Run this in the same terminal. Change the prompt, temperature or output limit to suit your request.

Send a request with parameters

curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-4.1-mini",
  "messages": [
    {
      "role": "system",
      "content": "Give short, practical answers."
    },
    {
      "role": "user",
      "content": "Give three names for a gardening app."
    }
  ],
  "max_tokens": 256,
  "temperature": 0.7
}'

Read the answer in choices[0].message.content. A finish_reason of length means the output limit was reached; increase it for a longer answer.

Common Chat Completions fields

Field	How to use it
`model`	Required. Copy an exact model ID or listed alias from the catalog.
`messages`	Required, non-empty conversation array. Use `system` for instructions, `user` for prompts and `assistant` for earlier answers. Send the history needed for each request.
`max_tokens`	Positive integer limiting generated output. Keep it within the model limit.
`max_completion_tokens`	Alternative output-limit field used by some models. Send this or `max_tokens`, never both.
`temperature`	Controls sampling randomness. Lower values generally make answers more focused. Accepted ranges depend on the model.
`top_p`	Nucleus sampling. Tune this or temperature first, rather than changing both together.
`stop`	A string or list of stop sequences. Output ends when a supported model reaches one.
`frequency_penalty`, `presence_penalty`	Adjust repetition on models that support these controls.
`stream`	Set to `true` for server-sent events. See streaming.
`stream_options`	Chat Completions accepts `{"include_usage":true}` for streaming usage.
`reasoning`, `reasoning_effort`	Thinking controls. Choose one form; see reasoning.
`tools`, `tool_choice`	Describe functions your application can run and control when the model calls them. Example below.
`parallel_tool_calls`	Boolean controlling parallel calls on models that support them.
`seed`	Integer sampling seed where supported. It does not guarantee identical answers.
`n`	Only `1` is supported.
`logprobs`, `top_logprobs`	Request token probabilities where supported. `top_logprobs` accepts an integer from 0 to 20.
`models`	Ordered text-model fallback list. See fallback models.

Optional parameters vary by model and provider. Check supported_parameters on the public catalog, plus reasoning_options for thinking controls. If a field is rejected, read the field path in the error and remove or adjust it. For schema-constrained JSON, use the structured-output guide.

Field names by endpoint

Setting	Chat Completions	Responses	Messages
Endpoint	`/v1/chat/completions`	`/v1/responses`	`/v1/messages`
Input	`messages`	`input`	`messages`
System instructions	A system message	`instructions`	`system`
Output limit	`max_tokens` or `max_completion_tokens`	`max_output_tokens`	`max_tokens` (required)
Thinking	`reasoning` or `reasoning_effort`	`reasoning`	`thinking` and `output_config.effort`
Schema output	Not supported	Not supported	`output_config.format` on the models listed in the structured-output guide

Use the request shape for your endpoint. Moving the same JSON body between endpoints without changing its fields will return an error.

Call a tool

Send a function definition with a model that supports tools. MiniRouter returns the model's requested call; your application runs the function.

Call a tool

curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-4.1-mini",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in London?"
    }
  ],
  "max_tokens": 256,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": [
            "city"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}'

Read choices[0].message.tool_calls. With tool_choice: "auto", the model may answer directly instead.
Parse each function's arguments JSON and validate it before running your function.
Append the complete assistant message, including tool_calls, to the conversation.
Append a role: "tool" message for each result, using the matching tool_call_id and a string content.
Send the updated conversation to get the final answer.

For example, a tool result message looks like {"role":"tool","tool_call_id":"call_id_from_response","content":"18 C, cloudy"}. Use the ID from the actual response. To force a call, use tool_choice: "required"; to disable calls, use "none". These fields require a model that supports tool choice.

Handle an error

A 400 invalid_request names the field to change. Reduce oversized schemas, remove unsupported controls, and check that you used the right endpoint. A 402 insufficient_credits means the available balance cannot cover the request; reduce the output limit or add credits. See the error reference.