Parameters

modelstring

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.

modelsstring[]

An array with exactly one model ID, for OpenRouter clients. More than one entry, or sending both model and models, returns 400.

messagesMessage[]Required

The conversation, within the aggregate request limit.

›Show child attributesHide child attributes

rolestringRequired

Common values are system, developer, user, assistant and tool. Unfamiliar roles are forwarded by matching compatible adapters.

contentstring | 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_callsToolCall[]

Historical calls, usually {id, type: "function", function: {name, arguments}}. Identifiers and argument strings are replayed without local semantic validation.

tool_call_idstring

The provider call identifier for a tool result.

namestring

Provider message name; preserved on compatible requests.

reasoningstring

Reasoning from an earlier turn. reasoning_content is accepted as an alias. Preserve all continuation metadata.

reasoning_detailsReasoningDetail[]

Structured reasoning blocks from an earlier response, including signatures and encrypted state. Send them back unchanged in tool loops.

cache_controlobject

Cache directive for the whole message. See Caching and sessions.

streambooleanDefault false

Return Server-Sent Events instead of one JSON object. See Streaming.

storebooleanDefault 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.

Content part types

textobject

{type: "text", text}. Empty text is accepted. Optional cache_control or prompt_cache_breakpoint, not both.

image_urlobject

{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.

fileobject

{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_audioobject

{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).

frequency_penalty

, presence_penalty, repetition_penalty, min_p, top_a number | null — Numeric sampling hints. Support and value ranges depend on the endpoint.

temperaturenumber | null

Sampling temperature; the upstream validates its range.

top_pnumber | null

Nucleus sampling hint.

top_kinteger | null

Candidate sampling hint.

seedinteger | null

Deterministic sampling hint.

stopstring | string[] | null

Stop sequences, subject to upstream limits.

max_completion_tokensinteger | null

Maximum output tokens, 1 to 131072. If you send both spellings, this one wins.

max_tokensinteger | null

Legacy spelling of the same limit.

ninteger | 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.

toolsTool[]

Function declarations are provider-owned data within the aggregate body limit. Hosted tools retain capability and execution checks.

›Show child attributesHide child attributes

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.

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 for the accepted IDs.

configurationobject

Hosted tools only. Up to 16 settings from the tool's allowed set, at most 32 KiB. Unknown settings return 400.

resource_aliasesstring[]

Hosted tools only. Up to 32 unique aliases, each at most 128 characters.

tool_choicestring | objectDefault "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_callsboolean

When false, a response with a second tool call fails. When omitted, multiple calls are allowed.

max_tool_callsintegerDefault 128

Maximum tool calls in one response, 1 to 128.

response_formatobject

The output format.

›Show child attributesHide child attributes

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.

reasoningobject

Reasoning hints, forwarded by default.

›Show child attributesHide child attributes

effortstring

Common values include none, minimal, low, medium, high, xhigh and max. New values are forwarded.

max_tokensinteger

Provider reasoning token budget.

excludeboolean

Omit reasoning from the response, both reasoning and reasoning_details.

enabledboolean

Turn reasoning on or off; the upstream resolves contradictory hints.

reasoning_effortstring | null

Shorthand for reasoning.effort; this alias takes precedence when supplied.

include_reasoningboolean

Inverse shorthand for reasoning.exclude; this alias takes precedence when supplied.

modalitiesstring[]Default ["text"]

Unique values from text, image and audio. Non-text values are features.

audioobject

{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.

session_idstring

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_keystring

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_optionsobject

{mode?, ttl?} with mode implicit or explicit and ttl 30m. At least one key. Feature.

cache_controlobject

{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_breakpointobject

On a text part only: {mode: "explicit"} marks an explicit cache breakpoint. Feature.

providerobject

Routing preferences for this request.

›Show child attributesHide child attributes

orderstring[]

Endpoints to try first, in order. Unlisted endpoints follow, unless allow_fallbacks is false. Up to 100 entries.

onlystring[]

Allow only these providers or endpoints. Up to 100 entries.

ignorestring[]

Never use these providers or endpoints. Up to 100 entries.

allow_fallbacksbooleanDefault 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_parametersbooleanDefault 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.

data_collectionstring

allow or deny. deny excludes endpoints that declare they collect request data.

zdrboolean

true allows only endpoints that declare zero data retention.

quantizationsstring[]

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.

regionsstring[]

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

sortstring

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).

max_priceobject

{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.

stream_optionsobject | null

{include_usage} is accepted and ignored; usage is always returned. Other keys return 400.

usageobject

{include} is accepted and ignored. Other keys return 400.

userstring

End-user identifier, at most 256 characters with no control characters. Validated, then discarded.