API ReferenceChat

Create a chat completion

Sends a request for a model response for the given chat conversation. Supports both streaming and non-streaming modes.

Request

This endpoint expects an object.
messageslist of objectsRequired
List of messages for the conversation
providerobject or nullOptional
When multiple model providers are available, optionally indicate your routing preference.
pluginslist of objectsOptional
Plugins you want to enable for this request, including their settings.
userstringOptional
Unique user identifier
session_idstringOptional<=128 characters

A unique identifier for grouping related requests (e.g., a conversation or agent workflow) for observability. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 128 characters.

traceobjectOptional

Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.

modelstringOptional
Model to use for completion
modelslist of objectsOptional
Models to use for completion
frequency_penaltydouble or nullOptional-2-2

Frequency penalty (-2.0 to 2.0)

logit_biasmap from strings to doubles or nullOptional
Token logit bias adjustments
logprobsboolean or nullOptional
Return log probabilities
top_logprobsdouble or nullOptional0-20

Number of top log probabilities to return (0-20)

max_completion_tokensdouble or nullOptional>=1
Maximum tokens in completion
max_tokensdouble or nullOptional>=1

Maximum tokens (deprecated, use max_completion_tokens)

metadatamap from strings to stringsOptional

Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values)

presence_penaltydouble or nullOptional-2-2

Presence penalty (-2.0 to 2.0)

reasoningobjectOptional
Configuration options for reasoning models
response_formatobjectOptional
Response format configuration
seedinteger or nullOptional
Random seed for deterministic outputs
stopstring or list of strings or anyOptional

Stop sequences (up to 4)

streambooleanOptionalDefaults to false
Enable streaming response
stream_optionsobjectOptional
Streaming configuration options
temperaturedouble or nullOptional0-2Defaults to 1

Sampling temperature (0-2)

parallel_tool_callsboolean or nullOptional
tool_choiceenum or objectOptional
Tool choice configuration
toolslist of objectsOptional
Available tools for function calling
top_pdouble or nullOptional0-1Defaults to 1

Nucleus sampling parameter (0-1)

debugobjectOptional

Debug options for inspecting request transformations (streaming only)

image_configmap from strings to strings or doubles or lists of anyOptional

Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details.

modalitieslist of enumsOptional
Output modalities for the response. Supported values are "text" and "image".
Allowed values:

Response

Successful chat completion response
idstring
Unique completion identifier
choiceslist of objects
List of completion choices
createddouble
Unix timestamp of creation
modelstring
Model used for completion
objectenum
Allowed values:
system_fingerprintstring or null
System fingerprint
usageobject or null
Token usage statistics

Errors