# Chat ## Overview ### Available Operations * [send](#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 ```python from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", 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](../../components/chatmessages.md)] | :heavy_check_mark: | List of messages for the conversation | [
{
"content": "Hello!",
"role": "user"
}
] | | `http_referer` | *Optional[str]* | :heavy_minus_sign: | 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]* | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional[str]* | :heavy_minus_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `cache_control` | [Optional[components.AnthropicCacheControlDirective]](../../components/anthropiccachecontroldirective.md) | :heavy_minus_sign: | N/A | {
"type": "ephemeral"
} | | `debug` | [Optional[components.ChatDebugOptions]](../../components/chatdebugoptions.md) | :heavy_minus_sign: | Debug options for inspecting request transformations (streaming only) | {
"echo_upstream_body": true
} | | `frequency_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | Frequency penalty (-2.0 to 2.0) | 0 | | `image_config` | Dict[str, [components.ImageConfig](../../components/imageconfig.md)] | :heavy_minus_sign: | 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*] | :heavy_minus_sign: | Token logit bias adjustments | {
"50256": -100
} | | `logprobs` | *OptionalNullable[bool]* | :heavy_minus_sign: | Return log probabilities | false | | `max_completion_tokens` | *OptionalNullable[int]* | :heavy_minus_sign: | Maximum tokens in completion | 100 | | `max_tokens` | *OptionalNullable[int]* | :heavy_minus_sign: | Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16. | 100 | | `metadata` | Dict[str, *str*] | :heavy_minus_sign: | 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](../../components/modality.md)] | :heavy_minus_sign: | Output modalities for the response. Supported values are "text", "image", and "audio". | [
"text",
"image"
] | | `model` | *Optional[str]* | :heavy_minus_sign: | Model to use for completion | openai/gpt-4 | | `models` | List[*str*] | :heavy_minus_sign: | Models to use for completion | [
"openai/gpt-4",
"openai/gpt-4o"
] | | `parallel_tool_calls` | *OptionalNullable[bool]* | :heavy_minus_sign: | 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](../../components/chatrequestplugin.md)] | :heavy_minus_sign: | Plugins you want to enable for this request, including their settings. | | | `presence_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | Presence penalty (-2.0 to 2.0) | 0 | | `provider` | [OptionalNullable[components.ProviderPreferences]](../../components/providerpreferences.md) | :heavy_minus_sign: | When multiple model providers are available, optionally indicate your routing preference. | {
"allow_fallbacks": true
} | | `reasoning` | [Optional[components.Reasoning]](../../components/reasoning.md) | :heavy_minus_sign: | Configuration options for reasoning models | {
"effort": "medium",
"summary": "concise"
} | | `response_format` | [Optional[components.ResponseFormat]](../../components/responseformat.md) | :heavy_minus_sign: | Response format configuration | {
"type": "json_object"
} | | `seed` | *OptionalNullable[int]* | :heavy_minus_sign: | Random seed for deterministic outputs | 42 | | `service_tier` | [OptionalNullable[components.ChatRequestServiceTier]](../../components/chatrequestservicetier.md) | :heavy_minus_sign: | The service tier to use for processing this request. | auto | | `session_id` | *Optional[str]* | :heavy_minus_sign: | 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]](../../components/stop.md) | :heavy_minus_sign: | Stop sequences (up to 4) | [
""
] | | `stream` | *Optional[bool]* | :heavy_minus_sign: | Enable streaming response | false | | `stream_options` | [OptionalNullable[components.ChatStreamOptions]](../../components/chatstreamoptions.md) | :heavy_minus_sign: | Streaming configuration options | {
"include_usage": true
} | | `temperature` | *OptionalNullable[float]* | :heavy_minus_sign: | Sampling temperature (0-2) | 0.7 | | `tool_choice` | [Optional[components.ChatToolChoice]](../../components/chattoolchoice.md) | :heavy_minus_sign: | Tool choice configuration | auto | | `tools` | List[[components.ChatFunctionTool](../../components/chatfunctiontool.md)] | :heavy_minus_sign: | Available tools for function calling | [
{
"function": {
"description": "Get weather",
"name": "get_weather"
},
"type": "function"
}
] | | `top_logprobs` | *OptionalNullable[int]* | :heavy_minus_sign: | Number of top log probabilities to return (0-20) | 5 | | `top_p` | *OptionalNullable[float]* | :heavy_minus_sign: | Nucleus sampling parameter (0-1) | 1 | | `trace` | [Optional[components.TraceConfig]](../../components/traceconfig.md) | :heavy_minus_sign: | 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]* | :heavy_minus_sign: | Unique user identifier | user-123 | | `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[operations.SendChatCompletionRequestResponse](../../operations/sendchatcompletionrequestresponse.md)** ### 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 | \*/\* |