ChatRequest - TypeScript SDK

ChatRequest type definition

Example Usage

1 import { ChatRequest } from "@openrouter/sdk/models";
2 
3 let value: ChatRequest = {
4   messages: [
5     {
6       content: "You are a helpful assistant.",
7       role: "system",
8     },
9     {
10       content: "What is the capital of France?",
11       role: "user",
12     },
13   ],
14 };

Fields

Field	Type	Required	Description	Example
`cacheControl`	models.AnthropicCacheControlDirective	➖	Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. Currently supported for Anthropic Claude models.	`{"type": "ephemeral"}`
`debug`	models.ChatDebugOptions	➖	Debug options for inspecting request transformations (streaming only)	`{"echo_upstream_body": true}`
`frequencyPenalty`	number	➖	Frequency penalty (-2.0 to 2.0)	0
`imageConfig`	`Record<string, models.ImageConfig>`	➖	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.	`{"aspect_ratio": "16:9","quality": "high"}`
`logitBias`	`Record<string, number>`	➖	Token logit bias adjustments	`{"50256": -100}`
`logprobs`	boolean	➖	Return log probabilities	false
`maxCompletionTokens`	number	➖	Maximum tokens in completion	100
`maxTokens`	number	➖	Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16.	100
`messages`	models.ChatMessages[]	✔️	List of messages for the conversation	[ `{"content": "Hello!","role": "user"}` ]
`metadata`	`Record<string, string>`	➖	Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values)	`{"session_id": "session-456","user_id": "user-123"}`
`modalities`	models.Modality[]	➖	Output modalities for the response. Supported values are “text”, “image”, and “audio”.	[ “text”, “image” ]
`model`	string	➖	Model to use for completion	openai/gpt-4
`models`	string[]	➖	Models to use for completion	[ “openai/gpt-4”, “openai/gpt-4o” ]
`parallelToolCalls`	boolean	➖	Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response.	true
`plugins`	models.ChatRequestPlugin[]	➖	Plugins you want to enable for this request, including their settings.
`presencePenalty`	number	➖	Presence penalty (-2.0 to 2.0)	0
`provider`	models.ProviderPreferences	➖	When multiple model providers are available, optionally indicate your routing preference.	`{"allow_fallbacks": true}`
`reasoning`	models.ChatRequestReasoning	➖	Configuration options for reasoning models	`{"effort": "medium","summary": "concise"}`
`responseFormat`	models.ResponseFormat	➖	Response format configuration	`{"type": "json_object"}`
`seed`	number	➖	Random seed for deterministic outputs	42
`serviceTier`	models.ChatRequestServiceTier	➖	The service tier to use for processing this request.	auto
`sessionId`	string	➖	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 256 characters.
`stop`	models.Stop	➖	Stop sequences (up to 4)	[ "" ]
`stopServerToolsWhen`	models.StopServerToolsWhenCondition[]	➖	Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`.	[ `{"step_count": 5,"type": "step_count_is"}`, `{"max_cost_in_dollars": 0.5,"type": "max_cost"}` ]
`stream`	boolean	➖	Enable streaming response	false
`streamOptions`	models.ChatStreamOptions	➖	Streaming configuration options	`{"include_usage": true}`
`temperature`	number	➖	Sampling temperature (0-2)	0.7
`toolChoice`	models.ChatToolChoice	➖	Tool choice configuration	auto
`tools`	models.ChatFunctionTool[]	➖	Available tools for function calling	[ `{"function": {"description": "Get weather","name": "get_weather"}`, “type”: “function” } ]
`topLogprobs`	number	➖	Number of top log probabilities to return (0-20)	5
`topP`	number	➖	Nucleus sampling parameter (0-1)	1
`trace`	models.TraceConfig	➖	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.	`{"trace_id": "trace-abc123","trace_name": "my-app-trace"}`
`user`	string	➖	Unique user identifier	user-123

Example Usage

1 import { ChatRequest } from "@openrouter/sdk/models";
2 
3 let value: ChatRequest = {
4   messages: [
5     {
6       content: "You are a helpful assistant.",
7       role: "system",
8     },
9     {
10       content: "What is the capital of France?",
11       role: "user",
12     },
13   ],
14 };

Fields

Field	Type	Required	Description	Example
`cacheControl`	models.AnthropicCacheControlDirective	➖	Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. Currently supported for Anthropic Claude models.	`{"type": "ephemeral"}`
`debug`	models.ChatDebugOptions	➖	Debug options for inspecting request transformations (streaming only)	`{"echo_upstream_body": true}`
`frequencyPenalty`	number	➖	Frequency penalty (-2.0 to 2.0)	0
`imageConfig`	`Record<string, models.ImageConfig>`	➖	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.	`{"aspect_ratio": "16:9","quality": "high"}`
`logitBias`	`Record<string, number>`	➖	Token logit bias adjustments	`{"50256": -100}`
`logprobs`	boolean	➖	Return log probabilities	false
`maxCompletionTokens`	number	➖	Maximum tokens in completion	100
`maxTokens`	number	➖	Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16.	100
`messages`	models.ChatMessages[]	✔️	List of messages for the conversation	[ `{"content": "Hello!","role": "user"}` ]
`metadata`	`Record<string, string>`	➖	Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values)	`{"session_id": "session-456","user_id": "user-123"}`
`modalities`	models.Modality[]	➖	Output modalities for the response. Supported values are “text”, “image”, and “audio”.	[ “text”, “image” ]
`model`	string	➖	Model to use for completion	openai/gpt-4
`models`	string[]	➖	Models to use for completion	[ “openai/gpt-4”, “openai/gpt-4o” ]
`parallelToolCalls`	boolean	➖	Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response.	true
`plugins`	models.ChatRequestPlugin[]	➖	Plugins you want to enable for this request, including their settings.
`presencePenalty`	number	➖	Presence penalty (-2.0 to 2.0)	0
`provider`	models.ProviderPreferences	➖	When multiple model providers are available, optionally indicate your routing preference.	`{"allow_fallbacks": true}`
`reasoning`	models.ChatRequestReasoning	➖	Configuration options for reasoning models	`{"effort": "medium","summary": "concise"}`
`responseFormat`	models.ResponseFormat	➖	Response format configuration	`{"type": "json_object"}`
`seed`	number	➖	Random seed for deterministic outputs	42
`serviceTier`	models.ChatRequestServiceTier	➖	The service tier to use for processing this request.	auto
`sessionId`	string	➖	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 256 characters.
`stop`	models.Stop	➖	Stop sequences (up to 4)	[ "" ]
`stopServerToolsWhen`	models.StopServerToolsWhenCondition[]	➖	Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`.	[ `{"step_count": 5,"type": "step_count_is"}`, `{"max_cost_in_dollars": 0.5,"type": "max_cost"}` ]
`stream`	boolean	➖	Enable streaming response	false
`streamOptions`	models.ChatStreamOptions	➖	Streaming configuration options	`{"include_usage": true}`
`temperature`	number	➖	Sampling temperature (0-2)	0.7
`toolChoice`	models.ChatToolChoice	➖	Tool choice configuration	auto
`tools`	models.ChatFunctionTool[]	➖	Available tools for function calling	[ `{"function": {"description": "Get weather","name": "get_weather"}`, “type”: “function” } ]
`topLogprobs`	number	➖	Number of top log probabilities to return (0-20)	5
`topP`	number	➖	Nucleus sampling parameter (0-1)	1
`trace`	models.TraceConfig	➖	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.	`{"trace_id": "trace-abc123","trace_name": "my-app-trace"}`
`user`	string	➖	Unique user identifier	user-123

1	import { ChatRequest } from "@openrouter/sdk/models";
2
3	let value: ChatRequest = {
4	messages: [
5	{
6	content: "You are a helpful assistant.",
7	role: "system",
8	},
9	{
10	content: "What is the capital of France?",
11	role: "user",
12	},
13	],
14	};