Chat - Python SDK
Chat method reference
The Python SDK and docs are currently in beta. Report issues on GitHub.
Overview
Available Operations
- send - Create a chat completion
send
Sends a request for a model response for the given chat conversation. Supports both streaming and non-streaming modes.
Example Usage
1 from openrouter import OpenRouter 2 import os 3 4 with OpenRouter( 5 http_referer="<value>", 6 x_open_router_title="<value>", 7 x_open_router_categories="<value>", 8 api_key=os.getenv("OPENROUTER_API_KEY", ""), 9 ) as open_router: 10 11 res = open_router.chat.send(messages=[ 12 { 13 "role": "system", 14 "content": "You are a helpful assistant.", 15 }, 16 { 17 "role": "user", 18 "content": "What is the capital of France?", 19 }, 20 ], stream=False) 21 22 with res as event_stream: 23 for event in event_stream: 24 # handle event 25 print(event, flush=True)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
messages | List[components.ChatMessages] | ✔️ | List of messages for the conversation | [{"role": "user","content": "Hello!"}] |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
provider | OptionalNullable[components.ChatRequestProvider] | ➖ | When multiple model providers are available, optionally indicate your routing preference. | |
plugins | List[components.ChatRequestPluginUnion] | ➖ | Plugins you want to enable for this request, including their settings. | |
user | Optional[str] | ➖ | Unique user identifier | user-123 |
session_id | Optional[str] | ➖ | 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. | |
trace | Optional[components.ChatRequestTrace] | ➖ | 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. | |
model | Optional[str] | ➖ | Model to use for completion | openai/gpt-4 |
models | List[str] | ➖ | Models to use for completion | [ “openai/gpt-4”, “openai/gpt-4o” ] |
frequency_penalty | Optional[float] | ➖ | Frequency penalty (-2.0 to 2.0) | 0 |
logit_bias | Dict[str, float] | ➖ | Token logit bias adjustments | {"50256": -100} |
logprobs | OptionalNullable[bool] | ➖ | Return log probabilities | false |
top_logprobs | Optional[int] | ➖ | Number of top log probabilities to return (0-20) | 5 |
max_completion_tokens | Optional[int] | ➖ | Maximum tokens in completion | 100 |
max_tokens | Optional[int] | ➖ | Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16. | 100 |
metadata | Dict[str, str] | ➖ | Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values) | {"user_id": "user-123","session_id": "session-456"} |
presence_penalty | Optional[float] | ➖ | Presence penalty (-2.0 to 2.0) | 0 |
reasoning | Optional[components.Reasoning] | ➖ | Configuration options for reasoning models | {"effort": "medium","summary": "concise"} |
response_format | Optional[components.ResponseFormat] | ➖ | Response format configuration | {"type": "json_object"} |
seed | Optional[int] | ➖ | Random seed for deterministic outputs | 42 |
stop | OptionalNullable[components.Stop] | ➖ | Stop sequences (up to 4) | [ "" ] |
stream | Optional[bool] | ➖ | Enable streaming response | false |
stream_options | OptionalNullable[components.ChatStreamOptions] | ➖ | Streaming configuration options | {"include_usage": true} |
temperature | Optional[float] | ➖ | Sampling temperature (0-2) | 0.7 |
parallel_tool_calls | OptionalNullable[bool] | ➖ | N/A | |
tool_choice | Optional[components.ChatToolChoice] | ➖ | Tool choice configuration | auto |
tools | List[components.ChatFunctionTool] | ➖ | Available tools for function calling | [{"type": "function","function": {"name": "get_weather","description": "Get weather"}} ] |
top_p | Optional[float] | ➖ | Nucleus sampling parameter (0-1) | 1 |
debug | Optional[components.ChatDebugOptions] | ➖ | Debug options for inspecting request transformations (streaming only) | {"echo_upstream_body": true} |
image_config | Dict[str, components.ChatRequestImageConfig] | ➖ | 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"} |
modalities | List[components.Modality] | ➖ | Output modalities for the response. Supported values are “text”, “image”, and “audio”. | [ “text”, “image” ] |
cache_control | Optional[components.CacheControl] | ➖ | Enable automatic prompt caching. When set, the system automatically applies cache breakpoints to the last cacheable block in the request. Currently supported for Anthropic Claude models. | |
service_tier | OptionalNullable[components.ChatRequestServiceTier] | ➖ | The service tier to use for processing this request. | auto |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
operations.SendChatCompletionRequestResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.PaymentRequiredResponseError | 402 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.RequestTimeoutResponseError | 408 | application/json |
| errors.PayloadTooLargeResponseError | 413 | application/json |
| errors.UnprocessableEntityResponseError | 422 | application/json |
| errors.TooManyRequestsResponseError | 429 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.BadGatewayResponseError | 502 | application/json |
| errors.ServiceUnavailableResponseError | 503 | application/json |
| errors.EdgeNetworkTimeoutResponseError | 524 | application/json |
| errors.ProviderOverloadedResponseError | 529 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |