# OpenResponsesRequest

Request schema for Responses endpoint


## Fields

| Field                                                                                                                                                                                                                                                                                                | Type                                                                                                                                                                                                                                                                                                 | Required                                                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                          | Example                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input`                                                                                                                                                                                                                                                                                              | [Optional[components.OpenResponsesInput]](../components/openresponsesinput.md)                                                                                                                                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | Input for a response request - can be a string or array of items                                                                                                                                                                                                                                     | [<br/>{<br/>"role": "user",<br/>"content": "What is the weather today?"<br/>}<br/>]                                                                                                                                                                                                                  |
| `instructions`                                                                                                                                                                                                                                                                                       | *OptionalNullable[str]*                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `metadata`                                                                                                                                                                                                                                                                                           | Dict[str, *str*]                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.                                                                                                                                         | {<br/>"user_id": "123",<br/>"session_id": "abc-def-ghi"<br/>}                                                                                                                                                                                                                                        |
| `tools`                                                                                                                                                                                                                                                                                              | List[[components.OpenResponsesRequestToolUnion](../components/openresponsesrequesttoolunion.md)]                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `tool_choice`                                                                                                                                                                                                                                                                                        | [Optional[components.OpenAIResponsesToolChoiceUnion]](../components/openairesponsestoolchoiceunion.md)                                                                                                                                                                                               | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `parallel_tool_calls`                                                                                                                                                                                                                                                                                | *OptionalNullable[bool]*                                                                                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `model`                                                                                                                                                                                                                                                                                              | *Optional[str]*                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `models`                                                                                                                                                                                                                                                                                             | List[*str*]                                                                                                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `text`                                                                                                                                                                                                                                                                                               | [Optional[components.OpenResponsesResponseText]](../components/openresponsesresponsetext.md)                                                                                                                                                                                                         | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | Text output configuration including format and verbosity                                                                                                                                                                                                                                             | {<br/>"format": {<br/>"type": "text"<br/>},<br/>"verbosity": "medium"<br/>}                                                                                                                                                                                                                          |
| `reasoning`                                                                                                                                                                                                                                                                                          | [OptionalNullable[components.OpenResponsesReasoningConfig]](../components/openresponsesreasoningconfig.md)                                                                                                                                                                                           | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | Configuration for reasoning mode in the response                                                                                                                                                                                                                                                     | {<br/>"summary": "auto",<br/>"enabled": true<br/>}                                                                                                                                                                                                                                                   |
| `max_output_tokens`                                                                                                                                                                                                                                                                                  | *OptionalNullable[float]*                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `temperature`                                                                                                                                                                                                                                                                                        | *OptionalNullable[float]*                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `top_p`                                                                                                                                                                                                                                                                                              | *OptionalNullable[float]*                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `top_logprobs`                                                                                                                                                                                                                                                                                       | *OptionalNullable[int]*                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `max_tool_calls`                                                                                                                                                                                                                                                                                     | *OptionalNullable[int]*                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `presence_penalty`                                                                                                                                                                                                                                                                                   | *OptionalNullable[float]*                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `frequency_penalty`                                                                                                                                                                                                                                                                                  | *OptionalNullable[float]*                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `top_k`                                                                                                                                                                                                                                                                                              | *Optional[float]*                                                                                                                                                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `image_config`                                                                                                                                                                                                                                                                                       | Dict[str, [components.OpenResponsesRequestImageConfig](../components/openresponsesrequestimageconfig.md)]                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/features/multimodal/image-generation for more details.                                                                                                                         | {<br/>"aspect_ratio": "16:9"<br/>}                                                                                                                                                                                                                                                                   |
| `modalities`                                                                                                                                                                                                                                                                                         | List[[components.ResponsesOutputModality](../components/responsesoutputmodality.md)]                                                                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | Output modalities for the response. Supported values are "text" and "image".                                                                                                                                                                                                                         | [<br/>"text",<br/>"image"<br/>]                                                                                                                                                                                                                                                                      |
| `prompt_cache_key`                                                                                                                                                                                                                                                                                   | *OptionalNullable[str]*                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `previous_response_id`                                                                                                                                                                                                                                                                               | *OptionalNullable[str]*                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `prompt`                                                                                                                                                                                                                                                                                             | [OptionalNullable[components.OpenAIResponsesPrompt]](../components/openairesponsesprompt.md)                                                                                                                                                                                                         | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `include`                                                                                                                                                                                                                                                                                            | List[[components.OpenAIResponsesIncludable](../components/openairesponsesincludable.md)]                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `background`                                                                                                                                                                                                                                                                                         | *OptionalNullable[bool]*                                                                                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `safety_identifier`                                                                                                                                                                                                                                                                                  | *OptionalNullable[str]*                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `store`                                                                                                                                                                                                                                                                                              | *Optional[Literal[False]]*                                                                                                                                                                                                                                                                           | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `service_tier`                                                                                                                                                                                                                                                                                       | [Optional[components.ServiceTier]](../components/servicetier.md)                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `truncation`                                                                                                                                                                                                                                                                                         | [OptionalNullable[components.Truncation]](../components/truncation.md)                                                                                                                                                                                                                               | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  | auto                                                                                                                                                                                                                                                                                                 |
| `stream`                                                                                                                                                                                                                                                                                             | *Optional[bool]*                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                      |
| `provider`                                                                                                                                                                                                                                                                                           | [OptionalNullable[components.Provider]](../components/provider.md)                                                                                                                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | When multiple model providers are available, optionally indicate your routing preference.                                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                      |
| `plugins`                                                                                                                                                                                                                                                                                            | List[[components.Plugin](../components/plugin.md)]                                                                                                                                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | Plugins you want to enable for this request, including their settings.                                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                      |
| `user`                                                                                                                                                                                                                                                                                               | *Optional[str]*                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                   | A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual users. Maximum of 128 characters. |                                                                                                                                                                                                                                                                                                      |
| `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 128 characters.                                                          |                                                                                                                                                                                                                                                                                                      |