openrouter-python-sdk-retry-errors/docs/sdks/chat

Chat

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

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.chat.send(messages=[
        {
            "content": "You are a helpful assistant.",
            "role": "system",
        },
        {
            "content": "What is the capital of France?",
            "role": "user",
        },
    ], max_tokens=150, model="openai/gpt-4", stream=False, temperature=0.7)

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)

Parameters

Parameter	Type	Required	Description	Example
messages	List[components.ChatMessages]	✔️	List of messages for the conversation	[ { "content": "Hello!", "role": "user" } ]
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.
cache_control	Optional[components.AnthropicCacheControlDirective]	➖	N/A	{ "type": "ephemeral" }
debug	Optional[components.ChatDebugOptions]	➖	Debug options for inspecting request transformations (streaming only)	{ "echo_upstream_body": true }
frequency_penalty	OptionalNullable[float]	➖	Frequency penalty (-2.0 to 2.0)	0
image_config	Dict[str, components.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" }
logit_bias	Dict[str, float]	➖	Token logit bias adjustments	{ "50256": -100 }
logprobs	OptionalNullable[bool]	➖	Return log probabilities	false
max_completion_tokens	OptionalNullable[int]	➖	Maximum tokens in completion	100
max_tokens	OptionalNullable[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)	{ "session_id": "session-456", "user_id": "user-123" }
modalities	List[components.Modality]	➖	Output modalities for the response. Supported values are "text", "image", and "audio".	[ "text", "image" ]
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" ]
parallel_tool_calls	OptionalNullable[bool]	➖	Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response.	true
plugins	List[components.ChatRequestPlugin]	➖	Plugins you want to enable for this request, including their settings.
presence_penalty	OptionalNullable[float]	➖	Presence penalty (-2.0 to 2.0)	0
provider	OptionalNullable[components.ProviderPreferences]	➖	When multiple model providers are available, optionally indicate your routing preference.	{ "allow_fallbacks": true }
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	OptionalNullable[int]	➖	Random seed for deterministic outputs	42
service_tier	OptionalNullable[components.ChatRequestServiceTier]	➖	The service tier to use for processing this request.	auto
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.
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	OptionalNullable[float]	➖	Sampling temperature (0-2)	0.7
tool_choice	Optional[components.ChatToolChoice]	➖	Tool choice configuration	auto
tools	List[components.ChatFunctionTool]	➖	Available tools for function calling	[ { "function": { "description": "Get weather", "name": "get_weather" }, "type": "function" } ]
top_logprobs	OptionalNullable[int]	➖	Number of top log probabilities to return (0-20)	5
top_p	OptionalNullable[float]	➖	Nucleus sampling parameter (0-1)	1
trace	Optional[components.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	Optional[str]	➖	Unique user identifier	user-123
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	*/*