# Parameters

> Every field of a chat completion request, with its type, range, default and effect on routing.

Source: https://0.0.0.0:3000/docs/api-reference/parameters
Documentation index: https://0.0.0.0:3000/docs/llms.txt

This page lists the common fields for `POST /chat/completions`. Unknown ordinary generation settings are forwarded to the upstream provider. Reserved routing, cache, privacy, connection, execution and billing controls remain validated.

Put all prompt text in `messages`. Native alternate input fields such as `systemInstruction` and cache-retention overrides such as `prompt_cache_retention` return `400`. `service_tier` accepts only `default`; any other tier returns `400`, because endpoints are priced at their standard tier.

## How parameters are applied

Ordinary generation settings are forwarded by default. The upstream decides whether it supports their values. If an endpoint refuses a setting it doesn't declare, the request falls back to the next endpoint and the refusal isn't counted against the provider's health; if every endpoint refuses, the request returns `400`.

| Group | Default behavior |
| --- | --- |
| Generation hints: sampling, client functions, structured output and reasoning | Forward to the upstream; `provider.require_parameters: true` opts into declared capability matching |
| Media, hosted tools, access, privacy, explicit cache controls and resource limits | Enforce the admitted capability and authorization boundaries |
| Routing and metadata | Handled by Numes |

A `null` sampling setting is treated as omitted. Message and text-part `cache_control` remains a hint unless strict matching is requested; endpoints without the capability receive the request without those markers. See [Prompt caching](/docs/features/prompt-caching#directives-narrow-routing).

Each endpoint's declared parameters are in `supported_parameters` from [`GET /models`](/docs/api-reference/models/list-models) and [`GET /models/{author}/{slug}/endpoints`](/docs/api-reference/models/list-model-endpoints). Both output-length spellings map to `max_tokens` there.

## Model and messages

:::fields
- `model` `string` — The canonical model ID, such as `openai/gpt-6-luna`. Required unless you send `models`. There are no variant suffixes such as `:free` or `:nitro`, and no `~` aliases.
- `models` `string[]` — An array with exactly one model ID, for OpenRouter clients. More than one entry, or sending both `model` and `models`, returns `400`.
- `messages` `Message[]` required — The conversation, within the aggregate request limit.
  - `role` `string` required — Common values are `system`, `developer`, `user`, `assistant` and `tool`. Unfamiliar roles are forwarded by matching compatible adapters.
  - `content` `string | ContentPart[] | null` — Text or structured provider content. Empty and unfamiliar shapes are accepted within aggregate request limits; native adapters may reject shapes they cannot translate.
  - `tool_calls` `ToolCall[]` — Historical calls, usually `{id, type: "function", function: {name, arguments}}`. Identifiers and argument strings are replayed without local semantic validation.
  - `tool_call_id` `string` — The provider call identifier for a tool result.
  - `name` `string` — Provider message name; preserved on compatible requests.
  - `reasoning` `string` — Reasoning from an earlier turn. `reasoning_content` is accepted as an alias. Preserve all continuation metadata.
  - `reasoning_details` `ReasoningDetail[]` — Structured reasoning blocks from an earlier response, including signatures and encrypted state. Send them back unchanged in tool loops.
  - `cache_control` `object` — Cache directive for the whole message. See [Caching and sessions](#caching-and-sessions).
- `stream` `boolean` default `false` — Return Server-Sent Events instead of one JSON object. See [Streaming](/docs/features/streaming).
- `store` `boolean` default `false` — Only `false` is accepted, equivalent to omission. Stored completions aren't supported; `true`, `null` and other types return `400`. This field isn't forwarded or matched against provider capabilities. It doesn't change metadata retention or provider data policies; use `provider.zdr` and `provider.data_collection` for [provider privacy requirements](/docs/privacy/provider-data-policies).
:::

### Content parts

:::fields Content part types
- `text` `object` — `{type: "text", text}`. Empty text is accepted. Optional `cache_control` or `prompt_cache_breakpoint`, not both.
- `image_url` `object` — `{type: "image_url", image_url: {url, detail?}}`. `url` is an HTTPS URL or a `data:` URL. Common `detail` values are `auto`, `low` and `high`; the upstream validates the hint. PNG, JPEG, GIF and WebP are accepted.
- `file` `object` — `{type: "file", file: {file_data, filename?}}`. `file_data` is an HTTPS URL or a PDF `data:` URL; `filename` is forwarded as provider metadata. `file_id` isn't supported.
- `input_audio` `object` — `{type: "input_audio", input_audio: {data, format}}`. `data` is base64, not a URL. `format` is `wav`, `mp3`, `flac`, `m4a`, `ogg`, `webm`, `aac`, `aiff`, `pcm16` or `pcm24` (PCM is read as 24 kHz).
:::

Remote media must be a publicly reachable HTTPS URL. A URL that can't be fetched promptly, points to a non-public destination, is too large, or holds an unsupported type returns `400`. Size and duration limits are in [Limits](/docs/api-reference/limits#media-inputs); [Multimodal inputs](/docs/multimodal/overview) covers usage.

## Sampling

:::fields
- `frequency_penalty`, `presence_penalty`, `repetition_penalty`, `min_p`, `top_a` `number | null` — Numeric sampling hints. Support and value ranges depend on the endpoint.
- `temperature` `number | null` — Sampling temperature; the upstream validates its range.
- `top_p` `number | null` — Nucleus sampling hint.
- `top_k` `integer | null` — Candidate sampling hint.
- `seed` `integer | null` — Deterministic sampling hint.
- `stop` `string | string[] | null` — Stop sequences, subject to upstream limits.
:::

All are samplers. When one is omitted, the endpoint's own default applies. Values are forwarded without local range checks.

## Output length

:::fields
- `max_completion_tokens` `integer | null` — Maximum output tokens, 1 to 131072. If you send both spellings, this one wins.
- `max_tokens` `integer | null` — Legacy spelling of the same limit.
- `n` `integer | null` — One response choice is supported. Omit it, send `null` or send `1`. Other values return `400` before dispatch. This doesn't narrow routing or require a declared model feature.
:::

Native output-limit spellings such as `n_predict`, `num_predict`, `max_new_tokens`, `max_tokens_to_sample`, `maxOutputTokens` and `maxTokens` return `400`. Use `max_completion_tokens` or `max_tokens` so the limit Numes authorizes is the one the endpoint applies.

- **Omitted:** no limit is sent, and the endpoint applies its own default within the model's maximum output.
- **Set:** endpoints whose maximum output is smaller than your limit are excluded. The endpoint stops at the limit and reports `finish_reason: "length"`. The authorized limit is forwarded, subject to source dialect translation, and enforced by Numes.
- **Funds:** a smaller limit doesn't reduce the amount held before the request runs; see [Credits and reservations](/docs/api-reference/limits#credits-and-reservations).

A model's maximum output is in `top_provider.max_completion_tokens` from [`GET /models`](/docs/api-reference/models/list-models), and per endpoint in `max_completion_tokens` from the endpoints list.

## Tools

:::fields
- `tools` `Tool[]` — Function declarations are provider-owned data within the aggregate body limit. Hosted tools retain capability and execution checks.
  - `type: "function"` `object` — A tool your code runs: `{type: "function", cache_control?, function: {name, description?, parameters, strict?}}`. Names and schemas are validated by the upstream provider. `strict` asks the endpoint to follow the schema exactly. `cache_control` is accepted for compatibility with clients that mark tools, but it isn't sent to the endpoint and never affects routing; see [Prompt caching](/docs/features/prompt-caching#on-messages-or-text-parts).
  - `type: <hosted tool>` `object` — A tool the provider runs: `{type, configuration?, resource_aliases?}` where `type` is `web_search`, `web_fetch`, `datetime`, `image_generation`, `code_execution`, `file_search`, `shell`, `mcp`, `tool_search`, `skills`, `maps`, `url_context`, `advisor`, `apply_patch`, `fusion` or `subagent`.
  - `type: "hosted"` `object` — A versioned hosted tool by ID: `{type: "hosted", id, configuration?, resource_aliases?}`, for example `openrouter.web_search@1`. See [Hosted tools](/docs/features/hosted-tools) for the accepted IDs.
  - `configuration` `object` — Hosted tools only. Up to 16 settings from the tool's allowed set, at most 32 KiB. Unknown settings return `400`.
  - `resource_aliases` `string[]` — Hosted tools only. Up to 32 unique aliases, each at most 128 characters.
- `tool_choice` `string | object` default `"auto"` — `none`, `auto`, `required`, or `{type: "function", function: {name}}` naming a declared function. `none` removes the tools from the request. A named choice sends only that tool and fails a response without the call. `required` is passed to the endpoint but not guaranteed, and needs at least one tool.
- `parallel_tool_calls` `boolean` — When `false`, a response with a second tool call fails. When omitted, multiple calls are allowed.
- `max_tool_calls` `integer` default `128` — Maximum tool calls in one response, 1 to 128.
:::

With `tool_choice: "none"`, tools aren't a routing requirement. See [Tool calling](/docs/features/tool-calling) and [Hosted tools](/docs/features/hosted-tools).

## Structured output

:::fields
- `response_format` `object` — The output format.
  - `type: "text"` `object` — Plain text. Same as omitting the field.
  - `type: "json_object"` `object` — Any JSON object. The upstream decides whether it supports the format; strict matching requires declared `response_format` support.
  - `type: "json_schema"` `object` — `{type: "json_schema", json_schema: {name, description?, schema, strict?}}`. The upstream validates names, schemas and additional format attributes. `provider.require_parameters: true` requires declared `structured_outputs` support.
:::

Schema adherence depends on the model and endpoint, so validate the parsed result. See [Structured outputs](/docs/features/structured-outputs).

## Reasoning

:::fields
- `reasoning` `object` — Reasoning hints, forwarded by default.
  - `effort` `string` — Common values include `none`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`. New values are forwarded.
  - `max_tokens` `integer` — Provider reasoning token budget.
  - `exclude` `boolean` — Omit reasoning from the response, both `reasoning` and `reasoning_details`.
  - `enabled` `boolean` — Turn reasoning on or off; the upstream resolves contradictory hints.
- `reasoning_effort` `string | null` — Shorthand for `reasoning.effort`; this alias takes precedence when supplied.
- `include_reasoning` `boolean` — Inverse shorthand for `reasoning.exclude`; this alias takes precedence when supplied.
:::

With `provider.require_parameters: true`, the following declared capabilities are required:

| You send | Endpoint must support |
| --- | --- |
| `effort` other than `none` | Reasoning at that effort level, or reasoning with unpublished effort levels (the effort is sent as a hint) |
| `effort: "none"` or `enabled: false` | Turning reasoning off |
| `max_tokens` | A reasoning token budget |
| Any other reasoning control, including `exclude` alone | Reasoning |

A model's `reasoning` object in `/models` lists its `supported_efforts`, whether it `supports_max_tokens`, and whether reasoning is `mandatory`. See [Reasoning](/docs/features/reasoning).

## Output modalities

:::fields
- `modalities` `string[]` default `["text"]` — Unique values from `text`, `image` and `audio`. Non-text values are features.
- `audio` `object` — `{voice, format}`, with `format` `wav` or `mp3`. Required when `modalities` contains `audio`, and not allowed otherwise. Audio output also requires `stream: true` and `text` in `modalities`.
:::

Few chat endpoints offer image or audio output, so these requests often return `503`. Use [`POST /images`](/docs/api-reference/media/create-image) and [`POST /audio/speech`](/docs/api-reference/media/create-speech) for generated media.

## Caching and sessions

:::fields
- `session_id` `string` — Sticky-routing key, at most 256 characters. Requests with the same session and model prefer the endpoint that served the previous one. The `X-Session-Id` header does the same; the body value wins.
- `prompt_cache_key` `string` — Cache-affinity key, at most 256 characters. Takes precedence over `session_id` for stickiness. The provider receives only an opaque hint with no content or account identifiers. Never limits routing: endpoints that don't accept it still serve the request without the hint.
- `prompt_cache_options` `object` — `{mode?, ttl?}` with `mode` `implicit` or `explicit` and `ttl` `30m`. At least one key. Feature.
- `cache_control` `object` — `{type: "ephemeral", ttl?}` with `ttl` `5m` or `1h`. Allowed at the top level, on a message, or on a `text` part. Feature at the top level. On a message or text part it's a hint, and a feature only with `provider.require_parameters: true`.
- `prompt_cache_breakpoint` `object` — On a `text` part only: `{mode: "explicit"}` marks an explicit cache breakpoint. Feature.
:::

These placements return `400`:

- Top-level `cache_control` combined with message- or part-level directives.
- `cache_control` on both a message and one of its parts.
- `cache_control` and `prompt_cache_breakpoint` on the same text part.

Stickiness applies only when you set neither `provider.order` nor `provider.sort`. A supported cache directive doesn't guarantee a cache hit. See [Prompt caching](/docs/features/prompt-caching) and [Sessions](/docs/features/sessions).

## Routing

The `provider` object is closed like the rest of the request. [Provider routing](/docs/routing/provider-routing) explains the default strategy with complete examples.

:::fields
- `provider` `object` — Routing preferences for this request.
  - `order` `string[]` — Endpoints to try first, in order. Unlisted endpoints follow, unless `allow_fallbacks` is `false`. Up to 100 entries.
  - `only` `string[]` — Allow only these providers or endpoints. Up to 100 entries.
  - `ignore` `string[]` — Never use these providers or endpoints. Up to 100 entries.
  - `allow_fallbacks` `boolean` default `true` — When `true`, a failed request can move to another endpoint, within a limited number of tries, before any output reaches you. When `false`, only one endpoint is tried.
  - `require_parameters` `boolean` default `false` — Make every sampler you send, a `"required"` or named `tool_choice`, and message- or part-level `cache_control` a requirement. See [How parameters are applied](#how-parameters-are-applied).
  - `data_collection` `string` — `allow` or `deny`. `deny` excludes endpoints that declare they collect request data.
  - `zdr` `boolean` — `true` allows only endpoints that declare zero data retention.
  - `quantizations` `string[]` — Allow only endpoints that declare one of these weight formats, matched exactly. Endpoints declare `int4`, `int8`, `fp4`, `mxfp4`, `nvfp4`, `fp6`, `fp8`, `mxfp8`, `fp16`, `bf16` or `fp32`; endpoints that declare none are excluded. Up to 100 entries.
  - `regions` `string[]` — Allow only endpoints that declare one of these country codes or region names, matched case-insensitively. Up to 64 unique values of 1 to 64 letters, digits, `.`, `_`, `:` or `-`.
  - `sort` `string` — `price` (lowest estimated price first), `throughput` (fastest observed output first), `latency` (fastest observed time to first token first) or `quality` (highest measured quality first; see [Quality sort](/docs/routing/provider-routing#quality-sort)).
  - `max_price` `object` — `{prompt?, completion?}` price ceilings as non-negative numbers, per token, in the key's currency. `completion` also caps a separate reasoning rate, and `prompt` a separate cache-write rate.
:::

Selectors in `order`, `only` and `ignore` are a provider slug or a `<provider>/<endpoint>` tag from the `tag` field of the endpoints list, matched case-insensitively, each at most 256 characters. Setting `order` or `sort` replaces the default routing strategy and turns off sticky routing.

:::warning max_price is per token
OpenRouter expresses `max_price` in dollars per million tokens. Here it's per unit in the key's currency: per token for text, and in satoshis for BTC keys. Divide an OpenRouter value by 1,000,000.
:::

## Accepted but ignored

These fields are accepted so existing clients keep working. They have no effect.

:::fields
- `stream_options` `object | null` — `{include_usage}` is accepted and ignored; usage is always returned. Other keys return `400`.
- `usage` `object` — `{include}` is accepted and ignored. Other keys return `400`.
- `user` `string` — End-user identifier, at most 256 characters with no control characters. Validated, then discarded.
:::

Ordinary hints such as `logit_bias`, `logprobs`, `top_logprobs`, `prediction` and `verbosity` can be forwarded to compatible endpoints. The public response does not include token log probabilities.

## Not supported

These OpenAI and OpenRouter fields return `400 invalid_request`:

| Field | Notes |
| --- | --- |
| `n` other than `1` or `null` | One choice per request. Send parallel requests for more. |
| `plugins` | Plugins, including response caching, aren't available. |
| `web_search_options` | Use a hosted `web_search` tool instead of `web_search_options`. |

Remove these fields in your client before sending. [OpenRouter compatibility](/docs/api-reference/compatibility) lists every difference.

## Next steps

:::cards
- {network} [Provider routing](/docs/routing/provider-routing) Order, sort, filter and cap prices per request.
- {wrench} [Tool calling](/docs/features/tool-calling) Define tools and run the tool loop.
- {brain} [Reasoning](/docs/features/reasoning) Effort levels, budgets and reasoning in streams.
- {waves} [Streaming](/docs/features/streaming) How each field shows up in stream chunks.
:::