# 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

<!-- UsageSnippet language="python" operationID="sendChatCompletionRequest" method="post" path="/chat/completions" -->
```python
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](../../components/chatmessages.md)]                                                                                                                                                                           | :heavy_check_mark:                                                                                                                                                                                                                          | List of messages for the conversation                                                                                                                                                                                                       | [<br/>{<br/>"content": "Hello!",<br/>"role": "user"<br/>}<br/>]                                                                                                                                                                             |
| `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.<br/>This is used to track API usage per application.<br/>                                                                                   |                                                                                                                                                                                                                                             |
| `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.<br/>                                                                                                                                           |                                                                                                                                                                                                                                             |
| `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.<br/>                                                                                                                                  |                                                                                                                                                                                                                                             |
| `cache_control`                                                                                                                                                                                                                             | [Optional[components.AnthropicCacheControlDirective]](../../components/anthropiccachecontroldirective.md)                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                                          | N/A                                                                                                                                                                                                                                         | {<br/>"type": "ephemeral"<br/>}                                                                                                                                                                                                             |
| `debug`                                                                                                                                                                                                                                     | [Optional[components.ChatDebugOptions]](../../components/chatdebugoptions.md)                                                                                                                                                               | :heavy_minus_sign:                                                                                                                                                                                                                          | Debug options for inspecting request transformations (streaming only)                                                                                                                                                                       | {<br/>"echo_upstream_body": true<br/>}                                                                                                                                                                                                      |
| `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.                                                         | {<br/>"aspect_ratio": "16:9",<br/>"quality": "high"<br/>}                                                                                                                                                                                   |
| `logit_bias`                                                                                                                                                                                                                                | Dict[str, *float*]                                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                                          | Token logit bias adjustments                                                                                                                                                                                                                | {<br/>"50256": -100<br/>}                                                                                                                                                                                                                   |
| `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)                                                                                                                                             | {<br/>"session_id": "session-456",<br/>"user_id": "user-123"<br/>}                                                                                                                                                                          |
| `modalities`                                                                                                                                                                                                                                | List[[components.Modality](../../components/modality.md)]                                                                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                                          | Output modalities for the response. Supported values are "text", "image", and "audio".                                                                                                                                                      | [<br/>"text",<br/>"image"<br/>]                                                                                                                                                                                                             |
| `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                                                                                                                                                                                                                | [<br/>"openai/gpt-4",<br/>"openai/gpt-4o"<br/>]                                                                                                                                                                                             |
| `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.                                                                                                                                                   | {<br/>"allow_fallbacks": true<br/>}                                                                                                                                                                                                         |
| `reasoning`                                                                                                                                                                                                                                 | [Optional[components.Reasoning]](../../components/reasoning.md)                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                          | Configuration options for reasoning models                                                                                                                                                                                                  | {<br/>"effort": "medium",<br/>"summary": "concise"<br/>}                                                                                                                                                                                    |
| `response_format`                                                                                                                                                                                                                           | [Optional[components.ResponseFormat]](../../components/responseformat.md)                                                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                                          | Response format configuration                                                                                                                                                                                                               | {<br/>"type": "json_object"<br/>}                                                                                                                                                                                                           |
| `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)                                                                                                                                                                                                                    | [<br/>""<br/>]                                                                                                                                                                                                                              |
| `stream`                                                                                                                                                                                                                                    | *Optional[bool]*                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                          | Enable streaming response                                                                                                                                                                                                                   | false                                                                                                                                                                                                                                       |
| `stream_options`                                                                                                                                                                                                                            | [OptionalNullable[components.ChatStreamOptions]](../../components/chatstreamoptions.md)                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                          | Streaming configuration options                                                                                                                                                                                                             | {<br/>"include_usage": true<br/>}                                                                                                                                                                                                           |
| `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                                                                                                                                                                                                        | [<br/>{<br/>"function": {<br/>"description": "Get weather",<br/>"name": "get_weather"<br/>},<br/>"type": "function"<br/>}<br/>]                                                                                                             |
| `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.    | {<br/>"trace_id": "trace-abc123",<br/>"trace_name": "my-app-trace"<br/>}                                                                                                                                                                    |
| `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                                | \*/\*                                   |