diff --git a/.speakeasy/gen.lock b/.speakeasy/gen.lock index 6fd77524..5b6fbc94 100644 --- a/.speakeasy/gen.lock +++ b/.speakeasy/gen.lock @@ -1,19 +1,19 @@ lockVersion: 2.0.0 id: c48cf606-fb42-4a45-9c23-8f0555307828 management: - docChecksum: ed950d049ab66589aac666ef97de5ade + docChecksum: 7ed2699e9084e60aa3120a61ca62a940 docVersion: 1.0.0 speakeasyVersion: 1.787.0 generationVersion: 2.914.0 - releaseVersion: 1.0.22 - configChecksum: eea86bd0d0182c493782d4e779a36642 + releaseVersion: 1.1.0 + configChecksum: 8af580dc2b9a7792adcab07e2841a335 repoURL: https://github.com/OpenRouterTeam/python-sdk.git installationURL: https://github.com/OpenRouterTeam/python-sdk.git published: true persistentEdits: - generation_id: 6c3cde2e-c79c-4fb2-a368-09c397fc2171 - pristine_commit_hash: 07bd316b05d346a37d1a557fa35656e99bd60dc5 - pristine_tree_hash: b951060366946f0af191e522aade310a354d8dd2 + generation_id: aa06fa63-f5c2-41fd-bcb7-4d5b1b17f00b + pristine_commit_hash: f795042663596dd63565022d60444e61c63b7e79 + pristine_tree_hash: cc2b70d5e12908a70971a47d0509eaf807954e03 features: python: acceptHeaders: 3.0.0 @@ -6692,6 +6692,10 @@ trackedFiles: id: 239279ebf01b last_write_checksum: sha1:5a76d28d77f68efe34ebbcb72850e6a87c74d3b1 pristine_git_object: 6e4b06ff97f02da5d31d78f478094db32dfdaa6f + docs/sdks/betaresponses/README.mdx: + id: 8a1e987c9840 + last_write_checksum: sha1:80eea97f1d2861c40c6cb5bf7ed7675b9b49a666 + pristine_git_object: 3b452fc5a627e83c4d3ac6282add1193ea1f2bc0 docs/sdks/byok/README.mdx: id: 17792f3b180d last_write_checksum: sha1:e2871404d5619b9a2adbdf02be1dd26e7e2bcd5e @@ -6766,8 +6770,8 @@ trackedFiles: pristine_git_object: cd1b341b1b7c0284b9ba9b102bd8020e0d7ce707 docs/sdks/responses/README.mdx: id: abab319e080e - last_write_checksum: sha1:190b20fd69931812090ddbdf5ab92eb2d35a7972 - pristine_git_object: e6ccd0eff2a0b11617c78cdd6ce9f5ad20b91198 + last_write_checksum: sha1:253c128cd03cd6322da4ca03ac45b3b91ba10900 + pristine_git_object: ac0c66814803c4e5d4c67bb000f7524c49d56d91 docs/sdks/stt/README.mdx: id: 190b0dc9a5d1 last_write_checksum: sha1:a8e68ac2b0bb8640e01d962177b42ab47b24898b @@ -6790,8 +6794,8 @@ trackedFiles: pristine_git_object: 3e38f1a929f7d6b1d6de74604aa87e3d8f010544 pyproject.toml: id: 5d07e7d72637 - last_write_checksum: sha1:18e56f63c9d74f7372f61bb11033e3109c442d43 - pristine_git_object: 05a245e6c0f584fd6e364b931d8bd4079e5158ac + last_write_checksum: sha1:c2f251318e7c22ba9e060b689abb2632bec575c4 + pristine_git_object: 11c174040ab36e581f2c0fbd0a4598c5abf2037f scripts/prepare_readme.py: id: e0c5957a6035 last_write_checksum: sha1:77f44b60b98bc126557ec27391f91dfba764bb54 @@ -6818,8 +6822,8 @@ trackedFiles: pristine_git_object: 86713cfea633e09d33b3d4e65281071fe20e6137 src/openrouter/_version.py: id: d8d15ad6c586 - last_write_checksum: sha1:7cf0cf327dddee692402b00a69d3de77b6b04639 - pristine_git_object: 6edf59c879482baa7693c4d0ddd870e86e1b054a + last_write_checksum: sha1:5e3fe20250cb4285925fead79225f508329b687a + pristine_git_object: 47e4174dee2882cc6f667caf28fb7b7a13ce1472 src/openrouter/analytics.py: id: cb406b5aaabb last_write_checksum: sha1:9e709b71dd0611056dc0cec6150b578defe32841 @@ -6838,12 +6842,16 @@ trackedFiles: pristine_git_object: 1b503c89b32b0381c93ee627e74428ae37286e33 src/openrouter/beta.py: id: fffdf54fd8f5 - last_write_checksum: sha1:7999d9294e23e166c6b27236262f1fb40139a4d1 - pristine_git_object: 9c02cc64163adf027507af763e7b612d3b704adb + last_write_checksum: sha1:4e34fb96ffe38673ca72e0f8576a8eddd4134d4b + pristine_git_object: 6def81a950b22cb1245b0b6b76c05a8d81fedaf8 src/openrouter/beta_analytics.py: id: 81988b170188 last_write_checksum: sha1:517ca1b0d4b94343e7728f156230e653f43c4641 pristine_git_object: 1b01f0c081ffc8a42fa56d335f95ec3121e4b5e6 + src/openrouter/beta_responses.py: + id: 001eaf848bf1 + last_write_checksum: sha1:98d6a6d987521a6dd178131aa68cbe8ad8f4e880 + pristine_git_object: 96d73084f18d2366b7dc1efda8ed0d4915620f24 src/openrouter/byok.py: id: bec352462ae1 last_write_checksum: sha1:b6e23eeb00a67208ad47b0ea77d56e92933af2b7 @@ -9642,12 +9650,12 @@ trackedFiles: pristine_git_object: 76378ffba1806e0ca66fc873db1a568be0becebb src/openrouter/responses.py: id: f2108fb635e1 - last_write_checksum: sha1:d0c570fe0a8e130efc4dbeccec4154aa33383932 - pristine_git_object: cc793c727d9b36406fa2d9ec9045274035f639b5 + last_write_checksum: sha1:94f1a10ee60b10f2203f4f13b19f87371ca56f44 + pristine_git_object: db9f7f737df555d67747b876b6f785af51f8933c src/openrouter/sdk.py: id: ee9846c4c9c5 - last_write_checksum: sha1:2247537eca7f88a8f36e53fe011904b98569ad52 - pristine_git_object: a6a9afda84aa6a6c36bf3ea4ca6a04761ab86e26 + last_write_checksum: sha1:d0a58277d1af4efc41a39ad4eff2196603e9c0ac + pristine_git_object: ced544d338aedc126fc976c30d3f949b83741a85 src/openrouter/sdkconfiguration.py: id: 55773bb98d7c last_write_checksum: sha1:c01826125c31a8b8bc99d9d679782c8758fae001 @@ -11321,4 +11329,3 @@ examples: "500": application/json: {"error": {"code": 500, "message": "Internal Server Error"}} examplesVersion: 1.0.2 -releaseNotes: "## Python SDK Changes:\n* `open_router.presets.create_presets_messages()`: \n * `request.messages[].content.union(Array<>)[]` **Changed** (Breaking ⚠️)\n" diff --git a/.speakeasy/gen.yaml b/.speakeasy/gen.yaml index 238dbe21..7008a425 100644 --- a/.speakeasy/gen.yaml +++ b/.speakeasy/gen.yaml @@ -36,7 +36,7 @@ generation: documentation: mintlify preApplyUnionDiscriminators: true python: - version: 1.0.22 + version: 1.1.0 additionalDependencies: dev: {} main: {} diff --git a/.speakeasy/in.openapi.yaml b/.speakeasy/in.openapi.yaml index 1b29b842..8a07ce9e 100644 --- a/.speakeasy/in.openapi.yaml +++ b/.speakeasy/in.openapi.yaml @@ -34665,7 +34665,7 @@ paths: description: 'Provider Overloaded - Provider is temporarily overloaded' summary: 'Create a response' tags: - - 'beta.responses' + - 'responses' x-speakeasy-name-override: 'send' x-speakeasy-stream-request-field: 'stream' /videos: @@ -35952,8 +35952,8 @@ tags: name: 'Workspaces' - description: 'beta.Analytics endpoints' name: 'beta.Analytics' - - description: 'beta.responses endpoints' - name: 'beta.responses' + - description: 'responses endpoints' + name: 'responses' x-retry-strategy: initialDelay: 500 maxAttempts: 3 diff --git a/.speakeasy/out.openapi.yaml b/.speakeasy/out.openapi.yaml index 37fb80b0..1a277f7f 100644 --- a/.speakeasy/out.openapi.yaml +++ b/.speakeasy/out.openapi.yaml @@ -35091,7 +35091,8 @@ paths: description: 'Provider Overloaded - Provider is temporarily overloaded' summary: 'Create a response' tags: - - 'beta.responses' + - 'responses' + - beta.responses x-speakeasy-name-override: 'send' x-speakeasy-stream-request-field: 'stream' parameters: @@ -36428,8 +36429,11 @@ tags: name: 'Workspaces' - description: 'beta.Analytics endpoints' name: 'beta.Analytics' - - description: 'beta.responses endpoints' - name: 'beta.responses' + - description: 'responses endpoints' + name: 'responses' + - name: beta.responses + deprecated: true + description: Deprecated alias for responses endpoints. Use responses instead. Scheduled for removal (sunset date TBD). x-retry-strategy: initialDelay: 500 maxAttempts: 3 diff --git a/.speakeasy/overlays/deprecated-beta-responses-alias.overlay.yaml b/.speakeasy/overlays/deprecated-beta-responses-alias.overlay.yaml new file mode 100644 index 00000000..89063e7f --- /dev/null +++ b/.speakeasy/overlays/deprecated-beta-responses-alias.overlay.yaml @@ -0,0 +1,23 @@ +overlay: 1.0.0 +x-speakeasy-jsonpath: rfc9535 +info: + title: Keep beta.responses as a deprecated SDK alias + version: 0.0.0 +actions: + # `update` appends to the existing tags list, so only the alias is listed here; + # re-listing `responses` would duplicate the canonical tag. + - target: $.paths["/responses"].post + description: Add beta.responses as a second (deprecated) SDK namespace for the responses operation + update: + tags: + - beta.responses + # Define the tag here rather than editing one in the input spec: the monorepo + # sdk-bot overwrites in.openapi.yaml with the GA-only spec, which carries no + # beta.responses tag, so a filter-based edit would silently match nothing and + # drop the deprecation notice. + - target: $.tags + description: Define the deprecated beta.responses tag + update: + - name: beta.responses + deprecated: true + description: Deprecated alias for responses endpoints. Use responses instead. Scheduled for removal (sunset date TBD). diff --git a/.speakeasy/workflow.lock b/.speakeasy/workflow.lock index 8c9a334c..19c9e24d 100644 --- a/.speakeasy/workflow.lock +++ b/.speakeasy/workflow.lock @@ -2,8 +2,8 @@ speakeasyVersion: 1.787.0 sources: OpenRouter API: sourceNamespace: open-router-chat-completions-api - sourceRevisionDigest: sha256:bb9814e3281a9e0c3024eaa6567726ce1522ce6ccf1a05f1206563bccba3bcec - sourceBlobDigest: sha256:040172eadbe8a42c5cc61b80aa158f3211bac5e469aca169ad8d0555056d3bea + sourceRevisionDigest: sha256:357663a2d3a9676da4b760aa05c45ca0114b2051d6eb3b5d420965915c7e587e + sourceBlobDigest: sha256:8bc72d29f0b30052d8fdf6fe99ce3d2b1c575428671c9350a6da7aedfaf615b5 tags: - latest - 1.0.0 @@ -11,10 +11,10 @@ targets: open-router: source: OpenRouter API sourceNamespace: open-router-chat-completions-api - sourceRevisionDigest: sha256:bb9814e3281a9e0c3024eaa6567726ce1522ce6ccf1a05f1206563bccba3bcec - sourceBlobDigest: sha256:040172eadbe8a42c5cc61b80aa158f3211bac5e469aca169ad8d0555056d3bea + sourceRevisionDigest: sha256:357663a2d3a9676da4b760aa05c45ca0114b2051d6eb3b5d420965915c7e587e + sourceBlobDigest: sha256:8bc72d29f0b30052d8fdf6fe99ce3d2b1c575428671c9350a6da7aedfaf615b5 codeSamplesNamespace: open-router-python-code-samples - codeSamplesRevisionDigest: sha256:1821552e46e96ec3536132a65e72ad74f213f58fc59900072da10b8c2428fedc + codeSamplesRevisionDigest: sha256:cdacb4b0a23b51908530ed8eb261c9a2e0202cb35ac88ae7d7941fc938def943 workflow: workflowVersion: 1.0.0 speakeasyVersion: 1.787.0 @@ -29,6 +29,7 @@ workflow: - location: .speakeasy/overlays/allof-simplify.overlay.yaml - location: .speakeasy/overlays/boolean-query-params.overlay.yaml - location: .speakeasy/overlays/fix-nullable-pagination.overlay.yaml + - location: .speakeasy/overlays/deprecated-beta-responses-alias.overlay.yaml output: .speakeasy/out.openapi.yaml registry: location: registry.speakeasyapi.dev/openrouter/sdk/open-router-chat-completions-api diff --git a/.speakeasy/workflow.yaml b/.speakeasy/workflow.yaml index 36493c14..8e51a85a 100644 --- a/.speakeasy/workflow.yaml +++ b/.speakeasy/workflow.yaml @@ -11,6 +11,7 @@ sources: - location: .speakeasy/overlays/allof-simplify.overlay.yaml - location: .speakeasy/overlays/boolean-query-params.overlay.yaml - location: .speakeasy/overlays/fix-nullable-pagination.overlay.yaml + - location: .speakeasy/overlays/deprecated-beta-responses-alias.overlay.yaml output: .speakeasy/out.openapi.yaml registry: location: registry.speakeasyapi.dev/openrouter/sdk/open-router-chat-completions-api diff --git a/docs/docs.json b/docs/docs.json index 0b81ee5f..a9ef22cd 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -14,6 +14,7 @@ "sdks/apikeys/README", "sdks/benchmarks/README", "sdks/betaanalytics/README", + "sdks/betaresponses/README", "sdks/byok/README", "sdks/chat/README", "sdks/classifications/README", diff --git a/docs/sdks/betaresponses/README.mdx b/docs/sdks/betaresponses/README.mdx new file mode 100644 index 00000000..3b452fc5 --- /dev/null +++ b/docs/sdks/betaresponses/README.mdx @@ -0,0 +1,133 @@ +--- +title: "Beta.Responses" +description: "Deprecated alias for responses endpoints. Use responses instead. Scheduled for removal (sunset date TBD)." +--- + +## Overview + +Deprecated alias for responses endpoints. Use responses instead. Scheduled for removal (sunset date TBD). + +### Available Operations + +* [send](#send) - Create a response + +## send + +Creates a streaming or non-streaming response using OpenResponses API format + +### Example Usage: guardrail-blocked + +```python +from openrouter import OpenRouter +import os + + +with OpenRouter( + http_referer="", + x_open_router_title="", + x_open_router_categories="", + api_key=os.getenv("OPENROUTER_API_KEY", ""), +) as open_router: + + res = open_router.beta.responses.send(service_tier="auto", stream=False) + + with res as event_stream: + for event in event_stream: + # handle event + print(event, flush=True) + +``` +### Example Usage: insufficient-permissions + +```python +from openrouter import OpenRouter +import os + + +with OpenRouter( + http_referer="", + x_open_router_title="", + x_open_router_categories="", + api_key=os.getenv("OPENROUTER_API_KEY", ""), +) as open_router: + + res = open_router.beta.responses.send(service_tier="auto", stream=False) + + with res as event_stream: + for event in event_stream: + # handle event + print(event, flush=True) + +``` + +### Parameters + +| Parameter | Type | Required | Description | Example | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `http_referer` | *Optional[str]* | :heavy_minus_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | +| `x_open_router_title` | *Optional[str]* | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | +| `x_open_router_categories` | *Optional[str]* | :heavy_minus_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | +| `x_open_router_metadata` | [Optional[components.MetadataLevel]](../../components/metadatalevel.mdx) | :heavy_minus_sign: | Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. | enabled | +| `background` | *OptionalNullable[bool]* | :heavy_minus_sign: | N/A | | +| `cache_control` | [Optional[components.AnthropicCacheControlDirective]](../../components/anthropiccachecontroldirective.mdx) | :heavy_minus_sign: | Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. | \{
"type": "ephemeral"
} | +| `debug` | [Optional[components.ChatDebugOptions]](../../components/chatdebugoptions.mdx) | :heavy_minus_sign: | Debug options for inspecting request transformations (streaming only) | \{
"echo_upstream_body": true
} | +| `frequency_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | N/A | | +| `image_config` | Dict[str, [components.ImageConfig](../../components/imageconfig.mdx)] | :heavy_minus_sign: | Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details. | \{
"aspect_ratio": "16:9",
"quality": "high"
} | +| `include` | List[[components.ResponseIncludesEnum](../../components/responseincludesenum.mdx)] | :heavy_minus_sign: | N/A | | +| `input` | [Optional[components.InputsUnion]](../../components/inputsunion.mdx) | :heavy_minus_sign: | Input for a response request - can be a string or array of items | [
\{
"content": "What is the weather today?",
"role": "user"
}
] | +| `instructions` | *OptionalNullable[str]* | :heavy_minus_sign: | N/A | | +| `max_output_tokens` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | +| `max_tool_calls` | *OptionalNullable[int]* | :heavy_minus_sign: | Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. | 30 | +| `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. | \{
"session_id": "abc-def-ghi",
"user_id": "123"
} | +| `modalities` | List[[components.OutputModalityEnum](../../components/outputmodalityenum.mdx)] | :heavy_minus_sign: | Output modalities for the response. Supported values are "text" and "image". | [
"text",
"image"
] | +| `model` | *Optional[str]* | :heavy_minus_sign: | N/A | | +| `models` | List[*str*] | :heavy_minus_sign: | N/A | | +| `parallel_tool_calls` | *OptionalNullable[bool]* | :heavy_minus_sign: | N/A | | +| `plugins` | List[[components.ResponsesRequestPlugin](../../components/responsesrequestplugin.mdx)] | :heavy_minus_sign: | Plugins you want to enable for this request, including their settings. | | +| `presence_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | N/A | | +| `previous_response_id` | *Optional[Any]* | :heavy_minus_sign: | Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. | | +| `prompt` | [OptionalNullable[components.StoredPromptTemplate]](../../components/storedprompttemplate.mdx) | :heavy_minus_sign: | N/A | \{
"id": "prompt-abc123",
"variables": \{
"name": "John"
}
} | +| `prompt_cache_key` | *OptionalNullable[str]* | :heavy_minus_sign: | N/A | | +| `prompt_cache_options` | [OptionalNullable[components.PromptCacheOptions]](../../components/promptcacheoptions.mdx) | :heavy_minus_sign: | Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. | \{
"mode": "explicit",
"ttl": "30m"
} | +| `provider` | [OptionalNullable[components.ProviderPreferences]](../../components/providerpreferences.mdx) | :heavy_minus_sign: | When multiple model providers are available, optionally indicate your routing preference. | \{
"allow_fallbacks": true
} | +| `reasoning` | [OptionalNullable[components.ReasoningConfig]](../../components/reasoningconfig.mdx) | :heavy_minus_sign: | Configuration for reasoning mode in the response | \{
"enabled": true,
"summary": "auto"
} | +| `safety_identifier` | *OptionalNullable[str]* | :heavy_minus_sign: | Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. | user-123 | +| `service_tier` | [OptionalNullable[components.ResponsesRequestServiceTier]](../../components/responsesrequestservicetier.mdx) | :heavy_minus_sign: | N/A | | +| `session_id` | *Optional[str]* | :heavy_minus_sign: | A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. | | +| `stop_server_tools_when` | List[[components.StopServerToolsWhenCondition](../../components/stopservertoolswhencondition.mdx)] | :heavy_minus_sign: | Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. | [
\{
"step_count": 5,
"type": "step_count_is"
},
\{
"max_cost_in_dollars": 0.5,
"type": "max_cost"
}
] | +| `stream` | *Optional[bool]* | :heavy_minus_sign: | N/A | | +| `temperature` | *OptionalNullable[float]* | :heavy_minus_sign: | N/A | | +| `text` | [Optional[components.TextExtendedConfig]](../../components/textextendedconfig.mdx) | :heavy_minus_sign: | Text output configuration including format and verbosity | \{
"format": \{
"type": "text"
}
} | +| `tool_choice` | [Optional[components.OpenAIResponsesToolChoiceUnion]](../../components/openairesponsestoolchoiceunion.mdx) | :heavy_minus_sign: | N/A | auto | +| `tools` | List[[components.ResponsesRequestToolUnion](../../components/responsesrequesttoolunion.mdx)] | :heavy_minus_sign: | N/A | | +| `top_k` | *Optional[int]* | :heavy_minus_sign: | N/A | | +| `top_logprobs` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | +| `top_p` | *OptionalNullable[float]* | :heavy_minus_sign: | N/A | | +| `trace` | [Optional[components.TraceConfig]](../../components/traceconfig.mdx) | :heavy_minus_sign: | Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations. | \{
"trace_id": "trace-abc123",
"trace_name": "my-app-trace"
} | +| `truncation` | [OptionalNullable[components.OpenAIResponsesTruncation]](../../components/openairesponsestruncation.mdx) | :heavy_minus_sign: | N/A | auto | +| `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 256 characters. | | +| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | + +### Response + +**[operations.CreateResponsesResponse](../../operations/createresponsesresponse.mdx)** + +### Errors + +| Error Type | Status Code | Content Type | +| --------------------------------------- | --------------------------------------- | --------------------------------------- | +| errors.BadRequestResponseError | 400 | application/json | +| errors.UnauthorizedResponseError | 401 | application/json | +| errors.PaymentRequiredResponseError | 402 | application/json | +| errors.ForbiddenResponseError | 403 | 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 | \*/\* | \ No newline at end of file diff --git a/docs/sdks/responses/README.mdx b/docs/sdks/responses/README.mdx index e6ccd0ef..ac0c6681 100644 --- a/docs/sdks/responses/README.mdx +++ b/docs/sdks/responses/README.mdx @@ -1,11 +1,11 @@ --- -title: "Beta.Responses" -description: "beta.responses endpoints" +title: "Responses" +description: "responses endpoints" --- ## Overview -beta.responses endpoints +responses endpoints ### Available Operations @@ -29,7 +29,7 @@ with OpenRouter( api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: - res = open_router.beta.responses.send(service_tier="auto", stream=False) + res = open_router.responses.send(service_tier="auto", stream=False) with res as event_stream: for event in event_stream: @@ -51,7 +51,7 @@ with OpenRouter( api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: - res = open_router.beta.responses.send(service_tier="auto", stream=False) + res = open_router.responses.send(service_tier="auto", stream=False) with res as event_stream: for event in event_stream: diff --git a/pyproject.toml b/pyproject.toml index 05a245e6..11c17404 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "openrouter" -version = "1.0.22" +version = "1.1.0" description = "Official Python Client SDK for OpenRouter." authors = [{ name = "OpenRouter" },] readme = "README-PYPI.md" diff --git a/src/openrouter/_version.py b/src/openrouter/_version.py index 6edf59c8..47e4174d 100644 --- a/src/openrouter/_version.py +++ b/src/openrouter/_version.py @@ -3,10 +3,10 @@ import importlib.metadata __title__: str = "openrouter" -__version__: str = "1.0.22" +__version__: str = "1.1.0" __openapi_doc_version__: str = "1.0.0" __gen_version__: str = "2.914.0" -__user_agent__: str = "speakeasy-sdk/python 1.0.22 2.914.0 1.0.0 openrouter" +__user_agent__: str = "speakeasy-sdk/python 1.1.0 2.914.0 1.0.0 openrouter" try: if __package__ is not None: diff --git a/src/openrouter/beta.py b/src/openrouter/beta.py index 9c02cc64..6def81a9 100644 --- a/src/openrouter/beta.py +++ b/src/openrouter/beta.py @@ -3,15 +3,15 @@ from .basesdk import BaseSDK from .sdkconfiguration import SDKConfiguration from openrouter.beta_analytics import BetaAnalytics -from openrouter.responses import Responses +from openrouter.beta_responses import BetaResponses from typing import Optional class Beta(BaseSDK): analytics: BetaAnalytics r"""beta.Analytics endpoints""" - responses: Responses - r"""beta.responses endpoints""" + responses: BetaResponses + r"""Deprecated alias for responses endpoints. Use responses instead. Scheduled for removal (sunset date TBD).""" def __init__( self, sdk_config: SDKConfiguration, parent_ref: Optional[object] = None @@ -24,4 +24,6 @@ def _init_sdks(self): self.analytics = BetaAnalytics( self.sdk_configuration, parent_ref=self.parent_ref ) - self.responses = Responses(self.sdk_configuration, parent_ref=self.parent_ref) + self.responses = BetaResponses( + self.sdk_configuration, parent_ref=self.parent_ref + ) diff --git a/src/openrouter/beta_responses.py b/src/openrouter/beta_responses.py new file mode 100644 index 00000000..96d73084 --- /dev/null +++ b/src/openrouter/beta_responses.py @@ -0,0 +1,1861 @@ +"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.""" + +from .basesdk import BaseSDK +from openrouter import components, errors, operations, utils +from openrouter._hooks import HookContext +from openrouter.types import OptionalNullable, UNSET +from openrouter.utils import eventstreaming, get_security_from_env +from openrouter.utils.unmarshal_json_response import unmarshal_json_response +from typing import ( + Any, + Dict, + Iterable, + List, + Literal, + Mapping, + Optional, + Union, + overload, +) + + +class BetaResponses(BaseSDK): + r"""Deprecated alias for responses endpoints. Use responses instead. Scheduled for removal (sunset date TBD).""" + + @overload + def send( + self, + *, + http_referer: Optional[str] = None, + x_open_router_title: Optional[str] = None, + x_open_router_categories: Optional[str] = None, + x_open_router_metadata: Optional[components.MetadataLevel] = None, + background: OptionalNullable[bool] = UNSET, + cache_control: Optional[ + Union[ + components.AnthropicCacheControlDirective, + components.AnthropicCacheControlDirectiveTypedDict, + ] + ] = None, + debug: Optional[ + Union[components.ChatDebugOptions, components.ChatDebugOptionsTypedDict] + ] = None, + frequency_penalty: OptionalNullable[float] = UNSET, + image_config: Optional[ + Union[ + Mapping[str, components.ImageConfig], + Mapping[str, components.ImageConfigTypedDict], + ] + ] = None, + include: OptionalNullable[Iterable[components.ResponseIncludesEnum]] = UNSET, + input: Optional[ + Union[components.InputsUnion, components.InputsUnionTypedDict] + ] = None, + instructions: OptionalNullable[str] = UNSET, + max_output_tokens: OptionalNullable[int] = UNSET, + max_tool_calls: OptionalNullable[int] = UNSET, + metadata: OptionalNullable[Mapping[str, str]] = UNSET, + modalities: Optional[Iterable[components.OutputModalityEnum]] = None, + model: Optional[str] = None, + models: Optional[Iterable[str]] = None, + parallel_tool_calls: OptionalNullable[bool] = UNSET, + plugins: Optional[ + Union[ + Iterable[components.ResponsesRequestPlugin], + Iterable[components.ResponsesRequestPluginTypedDict], + ] + ] = None, + presence_penalty: OptionalNullable[float] = UNSET, + previous_response_id: Optional[Any] = None, + prompt: OptionalNullable[ + Union[ + components.StoredPromptTemplate, + components.StoredPromptTemplateTypedDict, + ] + ] = UNSET, + prompt_cache_key: OptionalNullable[str] = UNSET, + prompt_cache_options: OptionalNullable[ + Union[components.PromptCacheOptions, components.PromptCacheOptionsTypedDict] + ] = UNSET, + provider: OptionalNullable[ + Union[ + components.ProviderPreferences, components.ProviderPreferencesTypedDict + ] + ] = UNSET, + reasoning: OptionalNullable[ + Union[components.ReasoningConfig, components.ReasoningConfigTypedDict] + ] = UNSET, + safety_identifier: OptionalNullable[str] = UNSET, + service_tier: OptionalNullable[components.ResponsesRequestServiceTier] = "auto", + session_id: Optional[str] = None, + stop_server_tools_when: Optional[ + Union[ + Iterable[components.StopServerToolsWhenCondition], + Iterable[components.StopServerToolsWhenConditionTypedDict], + ] + ] = None, + stream: Union[Literal[False], None] = None, + temperature: OptionalNullable[float] = UNSET, + text: Optional[ + Union[components.TextExtendedConfig, components.TextExtendedConfigTypedDict] + ] = None, + tool_choice: Optional[ + Union[ + components.OpenAIResponsesToolChoiceUnion, + components.OpenAIResponsesToolChoiceUnionTypedDict, + ] + ] = None, + tools: Optional[ + Union[ + Iterable[components.ResponsesRequestToolUnion], + Iterable[components.ResponsesRequestToolUnionTypedDict], + ] + ] = None, + top_k: Optional[int] = None, + top_logprobs: OptionalNullable[int] = UNSET, + top_p: OptionalNullable[float] = UNSET, + trace: Optional[ + Union[components.TraceConfig, components.TraceConfigTypedDict] + ] = None, + truncation: OptionalNullable[components.OpenAIResponsesTruncation] = UNSET, + user: Optional[str] = None, + retries: OptionalNullable[utils.RetryConfig] = UNSET, + server_url: Optional[str] = None, + timeout_ms: Optional[int] = None, + http_headers: Optional[Mapping[str, str]] = None, + ) -> components.OpenResponsesResult: + r"""Create a response + + Creates a streaming or non-streaming response using OpenResponses API format + + :param http_referer: The app identifier should be your app's URL and is used as the primary identifier for rankings. + This is used to track API usage per application. + + :param x_open_router_title: The app display name allows you to customize how your app appears in OpenRouter's dashboard. + + :param x_open_router_categories: Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings. + + :param x_open_router_metadata: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. + :param background: + :param cache_control: Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. + :param debug: Debug options for inspecting request transformations (streaming only) + :param frequency_penalty: + :param image_config: 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. + :param include: + :param input: Input for a response request - can be a string or array of items + :param instructions: + :param max_output_tokens: + :param max_tool_calls: Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. + :param metadata: 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. + :param modalities: Output modalities for the response. Supported values are \"text\" and \"image\". + :param model: + :param models: + :param parallel_tool_calls: + :param plugins: Plugins you want to enable for this request, including their settings. + :param presence_penalty: + :param previous_response_id: Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. + :param prompt: + :param prompt_cache_key: + :param prompt_cache_options: Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. + :param provider: When multiple model providers are available, optionally indicate your routing preference. + :param reasoning: Configuration for reasoning mode in the response + :param safety_identifier: Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. + :param service_tier: + :param session_id: A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. + :param stop_server_tools_when: Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. + :param stream: + :param temperature: + :param text: Text output configuration including format and verbosity + :param tool_choice: + :param tools: + :param top_k: + :param top_logprobs: + :param top_p: + :param trace: 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. + :param truncation: + :param user: 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 256 characters. + :param retries: Override the default retry configuration for this method + :param server_url: Override the default server URL for this method + :param timeout_ms: Override the default request timeout configuration for this method in milliseconds + :param http_headers: Additional headers to set or replace on requests. + """ + + @overload + def send( + self, + *, + http_referer: Optional[str] = None, + x_open_router_title: Optional[str] = None, + x_open_router_categories: Optional[str] = None, + x_open_router_metadata: Optional[components.MetadataLevel] = None, + background: OptionalNullable[bool] = UNSET, + cache_control: Optional[ + Union[ + components.AnthropicCacheControlDirective, + components.AnthropicCacheControlDirectiveTypedDict, + ] + ] = None, + debug: Optional[ + Union[components.ChatDebugOptions, components.ChatDebugOptionsTypedDict] + ] = None, + frequency_penalty: OptionalNullable[float] = UNSET, + image_config: Optional[ + Union[ + Mapping[str, components.ImageConfig], + Mapping[str, components.ImageConfigTypedDict], + ] + ] = None, + include: OptionalNullable[Iterable[components.ResponseIncludesEnum]] = UNSET, + input: Optional[ + Union[components.InputsUnion, components.InputsUnionTypedDict] + ] = None, + instructions: OptionalNullable[str] = UNSET, + max_output_tokens: OptionalNullable[int] = UNSET, + max_tool_calls: OptionalNullable[int] = UNSET, + metadata: OptionalNullable[Mapping[str, str]] = UNSET, + modalities: Optional[Iterable[components.OutputModalityEnum]] = None, + model: Optional[str] = None, + models: Optional[Iterable[str]] = None, + parallel_tool_calls: OptionalNullable[bool] = UNSET, + plugins: Optional[ + Union[ + Iterable[components.ResponsesRequestPlugin], + Iterable[components.ResponsesRequestPluginTypedDict], + ] + ] = None, + presence_penalty: OptionalNullable[float] = UNSET, + previous_response_id: Optional[Any] = None, + prompt: OptionalNullable[ + Union[ + components.StoredPromptTemplate, + components.StoredPromptTemplateTypedDict, + ] + ] = UNSET, + prompt_cache_key: OptionalNullable[str] = UNSET, + prompt_cache_options: OptionalNullable[ + Union[components.PromptCacheOptions, components.PromptCacheOptionsTypedDict] + ] = UNSET, + provider: OptionalNullable[ + Union[ + components.ProviderPreferences, components.ProviderPreferencesTypedDict + ] + ] = UNSET, + reasoning: OptionalNullable[ + Union[components.ReasoningConfig, components.ReasoningConfigTypedDict] + ] = UNSET, + safety_identifier: OptionalNullable[str] = UNSET, + service_tier: OptionalNullable[components.ResponsesRequestServiceTier] = "auto", + session_id: Optional[str] = None, + stop_server_tools_when: Optional[ + Union[ + Iterable[components.StopServerToolsWhenCondition], + Iterable[components.StopServerToolsWhenConditionTypedDict], + ] + ] = None, + stream: Literal[True], + temperature: OptionalNullable[float] = UNSET, + text: Optional[ + Union[components.TextExtendedConfig, components.TextExtendedConfigTypedDict] + ] = None, + tool_choice: Optional[ + Union[ + components.OpenAIResponsesToolChoiceUnion, + components.OpenAIResponsesToolChoiceUnionTypedDict, + ] + ] = None, + tools: Optional[ + Union[ + Iterable[components.ResponsesRequestToolUnion], + Iterable[components.ResponsesRequestToolUnionTypedDict], + ] + ] = None, + top_k: Optional[int] = None, + top_logprobs: OptionalNullable[int] = UNSET, + top_p: OptionalNullable[float] = UNSET, + trace: Optional[ + Union[components.TraceConfig, components.TraceConfigTypedDict] + ] = None, + truncation: OptionalNullable[components.OpenAIResponsesTruncation] = UNSET, + user: Optional[str] = None, + retries: OptionalNullable[utils.RetryConfig] = UNSET, + server_url: Optional[str] = None, + timeout_ms: Optional[int] = None, + http_headers: Optional[Mapping[str, str]] = None, + ) -> eventstreaming.EventStream[components.StreamEvents]: + r"""Create a response + + Creates a streaming or non-streaming response using OpenResponses API format + + :param http_referer: The app identifier should be your app's URL and is used as the primary identifier for rankings. + This is used to track API usage per application. + + :param x_open_router_title: The app display name allows you to customize how your app appears in OpenRouter's dashboard. + + :param x_open_router_categories: Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings. + + :param x_open_router_metadata: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. + :param background: + :param cache_control: Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. + :param debug: Debug options for inspecting request transformations (streaming only) + :param frequency_penalty: + :param image_config: 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. + :param include: + :param input: Input for a response request - can be a string or array of items + :param instructions: + :param max_output_tokens: + :param max_tool_calls: Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. + :param metadata: 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. + :param modalities: Output modalities for the response. Supported values are \"text\" and \"image\". + :param model: + :param models: + :param parallel_tool_calls: + :param plugins: Plugins you want to enable for this request, including their settings. + :param presence_penalty: + :param previous_response_id: Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. + :param prompt: + :param prompt_cache_key: + :param prompt_cache_options: Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. + :param provider: When multiple model providers are available, optionally indicate your routing preference. + :param reasoning: Configuration for reasoning mode in the response + :param safety_identifier: Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. + :param service_tier: + :param session_id: A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. + :param stop_server_tools_when: Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. + :param stream: + :param temperature: + :param text: Text output configuration including format and verbosity + :param tool_choice: + :param tools: + :param top_k: + :param top_logprobs: + :param top_p: + :param trace: 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. + :param truncation: + :param user: 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 256 characters. + :param retries: Override the default retry configuration for this method + :param server_url: Override the default server URL for this method + :param timeout_ms: Override the default request timeout configuration for this method in milliseconds + :param http_headers: Additional headers to set or replace on requests. + """ + + @overload + def send( + self, + *, + http_referer: Optional[str] = None, + x_open_router_title: Optional[str] = None, + x_open_router_categories: Optional[str] = None, + x_open_router_metadata: Optional[components.MetadataLevel] = None, + background: OptionalNullable[bool] = UNSET, + cache_control: Optional[ + Union[ + components.AnthropicCacheControlDirective, + components.AnthropicCacheControlDirectiveTypedDict, + ] + ] = None, + debug: Optional[ + Union[components.ChatDebugOptions, components.ChatDebugOptionsTypedDict] + ] = None, + frequency_penalty: OptionalNullable[float] = UNSET, + image_config: Optional[ + Union[ + Mapping[str, components.ImageConfig], + Mapping[str, components.ImageConfigTypedDict], + ] + ] = None, + include: OptionalNullable[Iterable[components.ResponseIncludesEnum]] = UNSET, + input: Optional[ + Union[components.InputsUnion, components.InputsUnionTypedDict] + ] = None, + instructions: OptionalNullable[str] = UNSET, + max_output_tokens: OptionalNullable[int] = UNSET, + max_tool_calls: OptionalNullable[int] = UNSET, + metadata: OptionalNullable[Mapping[str, str]] = UNSET, + modalities: Optional[Iterable[components.OutputModalityEnum]] = None, + model: Optional[str] = None, + models: Optional[Iterable[str]] = None, + parallel_tool_calls: OptionalNullable[bool] = UNSET, + plugins: Optional[ + Union[ + Iterable[components.ResponsesRequestPlugin], + Iterable[components.ResponsesRequestPluginTypedDict], + ] + ] = None, + presence_penalty: OptionalNullable[float] = UNSET, + previous_response_id: Optional[Any] = None, + prompt: OptionalNullable[ + Union[ + components.StoredPromptTemplate, + components.StoredPromptTemplateTypedDict, + ] + ] = UNSET, + prompt_cache_key: OptionalNullable[str] = UNSET, + prompt_cache_options: OptionalNullable[ + Union[components.PromptCacheOptions, components.PromptCacheOptionsTypedDict] + ] = UNSET, + provider: OptionalNullable[ + Union[ + components.ProviderPreferences, components.ProviderPreferencesTypedDict + ] + ] = UNSET, + reasoning: OptionalNullable[ + Union[components.ReasoningConfig, components.ReasoningConfigTypedDict] + ] = UNSET, + safety_identifier: OptionalNullable[str] = UNSET, + service_tier: OptionalNullable[components.ResponsesRequestServiceTier] = "auto", + session_id: Optional[str] = None, + stop_server_tools_when: Optional[ + Union[ + Iterable[components.StopServerToolsWhenCondition], + Iterable[components.StopServerToolsWhenConditionTypedDict], + ] + ] = None, + stream: bool, + temperature: OptionalNullable[float] = UNSET, + text: Optional[ + Union[components.TextExtendedConfig, components.TextExtendedConfigTypedDict] + ] = None, + tool_choice: Optional[ + Union[ + components.OpenAIResponsesToolChoiceUnion, + components.OpenAIResponsesToolChoiceUnionTypedDict, + ] + ] = None, + tools: Optional[ + Union[ + Iterable[components.ResponsesRequestToolUnion], + Iterable[components.ResponsesRequestToolUnionTypedDict], + ] + ] = None, + top_k: Optional[int] = None, + top_logprobs: OptionalNullable[int] = UNSET, + top_p: OptionalNullable[float] = UNSET, + trace: Optional[ + Union[components.TraceConfig, components.TraceConfigTypedDict] + ] = None, + truncation: OptionalNullable[components.OpenAIResponsesTruncation] = UNSET, + user: Optional[str] = None, + retries: OptionalNullable[utils.RetryConfig] = UNSET, + server_url: Optional[str] = None, + timeout_ms: Optional[int] = None, + http_headers: Optional[Mapping[str, str]] = None, + ) -> Union[ + components.OpenResponsesResult, + eventstreaming.EventStream[components.StreamEvents], + ]: + r"""Create a response + + Creates a streaming or non-streaming response using OpenResponses API format + + :param http_referer: The app identifier should be your app's URL and is used as the primary identifier for rankings. + This is used to track API usage per application. + + :param x_open_router_title: The app display name allows you to customize how your app appears in OpenRouter's dashboard. + + :param x_open_router_categories: Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings. + + :param x_open_router_metadata: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. + :param background: + :param cache_control: Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. + :param debug: Debug options for inspecting request transformations (streaming only) + :param frequency_penalty: + :param image_config: 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. + :param include: + :param input: Input for a response request - can be a string or array of items + :param instructions: + :param max_output_tokens: + :param max_tool_calls: Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. + :param metadata: 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. + :param modalities: Output modalities for the response. Supported values are \"text\" and \"image\". + :param model: + :param models: + :param parallel_tool_calls: + :param plugins: Plugins you want to enable for this request, including their settings. + :param presence_penalty: + :param previous_response_id: Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. + :param prompt: + :param prompt_cache_key: + :param prompt_cache_options: Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. + :param provider: When multiple model providers are available, optionally indicate your routing preference. + :param reasoning: Configuration for reasoning mode in the response + :param safety_identifier: Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. + :param service_tier: + :param session_id: A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. + :param stop_server_tools_when: Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. + :param stream: + :param temperature: + :param text: Text output configuration including format and verbosity + :param tool_choice: + :param tools: + :param top_k: + :param top_logprobs: + :param top_p: + :param trace: 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. + :param truncation: + :param user: 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 256 characters. + :param retries: Override the default retry configuration for this method + :param server_url: Override the default server URL for this method + :param timeout_ms: Override the default request timeout configuration for this method in milliseconds + :param http_headers: Additional headers to set or replace on requests. + """ + + def send( + self, + *, + http_referer: Optional[str] = None, + x_open_router_title: Optional[str] = None, + x_open_router_categories: Optional[str] = None, + x_open_router_metadata: Optional[components.MetadataLevel] = None, + background: OptionalNullable[bool] = UNSET, + cache_control: Optional[ + Union[ + components.AnthropicCacheControlDirective, + components.AnthropicCacheControlDirectiveTypedDict, + ] + ] = None, + debug: Optional[ + Union[components.ChatDebugOptions, components.ChatDebugOptionsTypedDict] + ] = None, + frequency_penalty: OptionalNullable[float] = UNSET, + image_config: Optional[ + Union[ + Mapping[str, components.ImageConfig], + Mapping[str, components.ImageConfigTypedDict], + ] + ] = None, + include: OptionalNullable[Iterable[components.ResponseIncludesEnum]] = UNSET, + input: Optional[ + Union[components.InputsUnion, components.InputsUnionTypedDict] + ] = None, + instructions: OptionalNullable[str] = UNSET, + max_output_tokens: OptionalNullable[int] = UNSET, + max_tool_calls: OptionalNullable[int] = UNSET, + metadata: OptionalNullable[Mapping[str, str]] = UNSET, + modalities: Optional[Iterable[components.OutputModalityEnum]] = None, + model: Optional[str] = None, + models: Optional[Iterable[str]] = None, + parallel_tool_calls: OptionalNullable[bool] = UNSET, + plugins: Optional[ + Union[ + Iterable[components.ResponsesRequestPlugin], + Iterable[components.ResponsesRequestPluginTypedDict], + ] + ] = None, + presence_penalty: OptionalNullable[float] = UNSET, + previous_response_id: Optional[Any] = None, + prompt: OptionalNullable[ + Union[ + components.StoredPromptTemplate, + components.StoredPromptTemplateTypedDict, + ] + ] = UNSET, + prompt_cache_key: OptionalNullable[str] = UNSET, + prompt_cache_options: OptionalNullable[ + Union[components.PromptCacheOptions, components.PromptCacheOptionsTypedDict] + ] = UNSET, + provider: OptionalNullable[ + Union[ + components.ProviderPreferences, components.ProviderPreferencesTypedDict + ] + ] = UNSET, + reasoning: OptionalNullable[ + Union[components.ReasoningConfig, components.ReasoningConfigTypedDict] + ] = UNSET, + safety_identifier: OptionalNullable[str] = UNSET, + service_tier: OptionalNullable[components.ResponsesRequestServiceTier] = "auto", + session_id: Optional[str] = None, + stop_server_tools_when: Optional[ + Union[ + Iterable[components.StopServerToolsWhenCondition], + Iterable[components.StopServerToolsWhenConditionTypedDict], + ] + ] = None, + stream: Optional[bool] = False, + temperature: OptionalNullable[float] = UNSET, + text: Optional[ + Union[components.TextExtendedConfig, components.TextExtendedConfigTypedDict] + ] = None, + tool_choice: Optional[ + Union[ + components.OpenAIResponsesToolChoiceUnion, + components.OpenAIResponsesToolChoiceUnionTypedDict, + ] + ] = None, + tools: Optional[ + Union[ + Iterable[components.ResponsesRequestToolUnion], + Iterable[components.ResponsesRequestToolUnionTypedDict], + ] + ] = None, + top_k: Optional[int] = None, + top_logprobs: OptionalNullable[int] = UNSET, + top_p: OptionalNullable[float] = UNSET, + trace: Optional[ + Union[components.TraceConfig, components.TraceConfigTypedDict] + ] = None, + truncation: OptionalNullable[components.OpenAIResponsesTruncation] = UNSET, + user: Optional[str] = None, + retries: OptionalNullable[utils.RetryConfig] = UNSET, + server_url: Optional[str] = None, + timeout_ms: Optional[int] = None, + http_headers: Optional[Mapping[str, str]] = None, + ) -> Union[ + components.OpenResponsesResult, + eventstreaming.EventStream[components.StreamEvents], + ]: + r"""Create a response + + Creates a streaming or non-streaming response using OpenResponses API format + + :param http_referer: The app identifier should be your app's URL and is used as the primary identifier for rankings. + This is used to track API usage per application. + + :param x_open_router_title: The app display name allows you to customize how your app appears in OpenRouter's dashboard. + + :param x_open_router_categories: Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings. + + :param x_open_router_metadata: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. + :param background: + :param cache_control: Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. + :param debug: Debug options for inspecting request transformations (streaming only) + :param frequency_penalty: + :param image_config: 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. + :param include: + :param input: Input for a response request - can be a string or array of items + :param instructions: + :param max_output_tokens: + :param max_tool_calls: Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. + :param metadata: 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. + :param modalities: Output modalities for the response. Supported values are \"text\" and \"image\". + :param model: + :param models: + :param parallel_tool_calls: + :param plugins: Plugins you want to enable for this request, including their settings. + :param presence_penalty: + :param previous_response_id: Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. + :param prompt: + :param prompt_cache_key: + :param prompt_cache_options: Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. + :param provider: When multiple model providers are available, optionally indicate your routing preference. + :param reasoning: Configuration for reasoning mode in the response + :param safety_identifier: Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. + :param service_tier: + :param session_id: A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. + :param stop_server_tools_when: Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. + :param stream: + :param temperature: + :param text: Text output configuration including format and verbosity + :param tool_choice: + :param tools: + :param top_k: + :param top_logprobs: + :param top_p: + :param trace: 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. + :param truncation: + :param user: 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 256 characters. + :param retries: Override the default retry configuration for this method + :param server_url: Override the default server URL for this method + :param timeout_ms: Override the default request timeout configuration for this method in milliseconds + :param http_headers: Additional headers to set or replace on requests. + """ + base_url = None + url_variables = None + if timeout_ms is None: + timeout_ms = self.sdk_configuration.timeout_ms + + if server_url is not None: + base_url = server_url + else: + base_url = self._get_url(base_url, url_variables) + + request = operations.CreateResponsesRequest( + http_referer=http_referer, + x_open_router_title=x_open_router_title, + x_open_router_categories=x_open_router_categories, + x_open_router_metadata=x_open_router_metadata, + responses_request=components.ResponsesRequest( + background=background, + cache_control=utils.get_pydantic_model( + cache_control, Optional[components.AnthropicCacheControlDirective] + ), + debug=utils.get_pydantic_model( + debug, Optional[components.ChatDebugOptions] + ), + frequency_penalty=frequency_penalty, + image_config=utils.unmarshal( + image_config, Optional[Dict[str, components.ImageConfig]] + ), + include=utils.unmarshal( + include, OptionalNullable[List[components.ResponseIncludesEnum]] + ), + input=utils.get_pydantic_model(input, Optional[components.InputsUnion]), + instructions=instructions, + max_output_tokens=max_output_tokens, + max_tool_calls=max_tool_calls, + metadata=utils.unmarshal(metadata, OptionalNullable[Dict[str, str]]), + modalities=utils.unmarshal( + modalities, Optional[List[components.OutputModalityEnum]] + ), + model=model, + models=utils.unmarshal(models, Optional[List[str]]), + parallel_tool_calls=parallel_tool_calls, + plugins=utils.get_pydantic_model( + plugins, Optional[List[components.ResponsesRequestPlugin]] + ), + presence_penalty=presence_penalty, + previous_response_id=previous_response_id, + prompt=utils.get_pydantic_model( + prompt, OptionalNullable[components.StoredPromptTemplate] + ), + prompt_cache_key=prompt_cache_key, + prompt_cache_options=utils.get_pydantic_model( + prompt_cache_options, + OptionalNullable[components.PromptCacheOptions], + ), + provider=utils.get_pydantic_model( + provider, OptionalNullable[components.ProviderPreferences] + ), + reasoning=utils.get_pydantic_model( + reasoning, OptionalNullable[components.ReasoningConfig] + ), + safety_identifier=safety_identifier, + service_tier=service_tier, + session_id=session_id, + stop_server_tools_when=utils.get_pydantic_model( + stop_server_tools_when, + Optional[List[components.StopServerToolsWhenCondition]], + ), + stream=stream, + temperature=temperature, + text=utils.get_pydantic_model( + text, Optional[components.TextExtendedConfig] + ), + tool_choice=utils.get_pydantic_model( + tool_choice, Optional[components.OpenAIResponsesToolChoiceUnion] + ), + tools=utils.get_pydantic_model( + tools, Optional[List[components.ResponsesRequestToolUnion]] + ), + top_k=top_k, + top_logprobs=top_logprobs, + top_p=top_p, + trace=utils.get_pydantic_model(trace, Optional[components.TraceConfig]), + truncation=truncation, + user=user, + ), + ) + + req = self._build_request( + method="POST", + path="/responses", + base_url=base_url, + url_variables=url_variables, + request=request, + request_body_required=True, + request_has_path_params=False, + request_has_query_params=True, + user_agent_header="user-agent", + accept_header_value="text/event-stream" + if stream is True + else "application/json", + http_headers=http_headers, + _globals=operations.CreateResponsesGlobals( + http_referer=self.sdk_configuration.globals.http_referer, + x_open_router_title=self.sdk_configuration.globals.x_open_router_title, + x_open_router_categories=self.sdk_configuration.globals.x_open_router_categories, + ), + security=self.sdk_configuration.security, + get_serialized_body=lambda: utils.serialize_request_body( + request.responses_request, + False, + False, + "json", + components.ResponsesRequest, + ), + allow_empty_value=None, + timeout_ms=timeout_ms, + ) + + if retries == UNSET: + if self.sdk_configuration.retry_config is not UNSET: + retries = self.sdk_configuration.retry_config + else: + retries = utils.RetryConfig( + "backoff", utils.BackoffStrategy(500, 60000, 1.5, 3600000), True + ) + + retry_config = None + if isinstance(retries, utils.RetryConfig): + retry_config = (retries, ["5XX"]) + + http_res = self.do_request( + hook_ctx=HookContext( + config=self.sdk_configuration, + base_url=base_url or "", + operation_id="createResponses", + oauth2_scopes=None, + security_source=get_security_from_env( + self.sdk_configuration.security, components.Security + ), + tags=["responses", "beta.responses"], + extensions=None, + ), + request=req, + is_error_status_code=lambda c: utils.match_status_codes(["4XX", "5XX"], c), + stream=stream is True, + retry_config=retry_config, + ) + + response_data: Any = None + if utils.match_response(http_res, "200", "application/json"): + http_res_text = utils.stream_to_text(http_res) + return unmarshal_json_response( + components.OpenResponsesResult, http_res, http_res_text + ) + if utils.match_response(http_res, "200", "text/event-stream"): + return eventstreaming.EventStream( + http_res, + lambda raw: unmarshal_json_response( + components.ResponsesStreamingResponse, http_res, raw + ).data, + sentinel="[DONE]", + client_ref=self, + ) + if utils.match_response(http_res, "400", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.BadRequestResponseErrorData, http_res, http_res_text + ) + raise errors.BadRequestResponseError(response_data, http_res, http_res_text) + if utils.match_response(http_res, "401", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.UnauthorizedResponseErrorData, http_res, http_res_text + ) + raise errors.UnauthorizedResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "402", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.PaymentRequiredResponseErrorData, http_res, http_res_text + ) + raise errors.PaymentRequiredResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "403", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.ForbiddenResponseErrorData, http_res, http_res_text + ) + raise errors.ForbiddenResponseError(response_data, http_res, http_res_text) + if utils.match_response(http_res, "404", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.NotFoundResponseErrorData, http_res, http_res_text + ) + raise errors.NotFoundResponseError(response_data, http_res, http_res_text) + if utils.match_response(http_res, "408", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.RequestTimeoutResponseErrorData, http_res, http_res_text + ) + raise errors.RequestTimeoutResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "413", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.PayloadTooLargeResponseErrorData, http_res, http_res_text + ) + raise errors.PayloadTooLargeResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "422", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.UnprocessableEntityResponseErrorData, http_res, http_res_text + ) + raise errors.UnprocessableEntityResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "429", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.TooManyRequestsResponseErrorData, http_res, http_res_text + ) + raise errors.TooManyRequestsResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "500", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.InternalServerResponseErrorData, http_res, http_res_text + ) + raise errors.InternalServerResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "502", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.BadGatewayResponseErrorData, http_res, http_res_text + ) + raise errors.BadGatewayResponseError(response_data, http_res, http_res_text) + if utils.match_response(http_res, "503", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.ServiceUnavailableResponseErrorData, http_res, http_res_text + ) + raise errors.ServiceUnavailableResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "524", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.EdgeNetworkTimeoutResponseErrorData, http_res, http_res_text + ) + raise errors.EdgeNetworkTimeoutResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "529", "application/json"): + http_res_text = utils.stream_to_text(http_res) + response_data = unmarshal_json_response( + errors.ProviderOverloadedResponseErrorData, http_res, http_res_text + ) + raise errors.ProviderOverloadedResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "4XX", "*"): + http_res_text = utils.stream_to_text(http_res) + raise errors.OpenRouterDefaultError( + "API error occurred", http_res, http_res_text + ) + if utils.match_response(http_res, "5XX", "*"): + http_res_text = utils.stream_to_text(http_res) + raise errors.OpenRouterDefaultError( + "API error occurred", http_res, http_res_text + ) + + http_res_text = utils.stream_to_text(http_res) + raise errors.OpenRouterDefaultError( + "Unexpected response received", http_res, http_res_text + ) + + @overload + async def send_async( + self, + *, + http_referer: Optional[str] = None, + x_open_router_title: Optional[str] = None, + x_open_router_categories: Optional[str] = None, + x_open_router_metadata: Optional[components.MetadataLevel] = None, + background: OptionalNullable[bool] = UNSET, + cache_control: Optional[ + Union[ + components.AnthropicCacheControlDirective, + components.AnthropicCacheControlDirectiveTypedDict, + ] + ] = None, + debug: Optional[ + Union[components.ChatDebugOptions, components.ChatDebugOptionsTypedDict] + ] = None, + frequency_penalty: OptionalNullable[float] = UNSET, + image_config: Optional[ + Union[ + Mapping[str, components.ImageConfig], + Mapping[str, components.ImageConfigTypedDict], + ] + ] = None, + include: OptionalNullable[Iterable[components.ResponseIncludesEnum]] = UNSET, + input: Optional[ + Union[components.InputsUnion, components.InputsUnionTypedDict] + ] = None, + instructions: OptionalNullable[str] = UNSET, + max_output_tokens: OptionalNullable[int] = UNSET, + max_tool_calls: OptionalNullable[int] = UNSET, + metadata: OptionalNullable[Mapping[str, str]] = UNSET, + modalities: Optional[Iterable[components.OutputModalityEnum]] = None, + model: Optional[str] = None, + models: Optional[Iterable[str]] = None, + parallel_tool_calls: OptionalNullable[bool] = UNSET, + plugins: Optional[ + Union[ + Iterable[components.ResponsesRequestPlugin], + Iterable[components.ResponsesRequestPluginTypedDict], + ] + ] = None, + presence_penalty: OptionalNullable[float] = UNSET, + previous_response_id: Optional[Any] = None, + prompt: OptionalNullable[ + Union[ + components.StoredPromptTemplate, + components.StoredPromptTemplateTypedDict, + ] + ] = UNSET, + prompt_cache_key: OptionalNullable[str] = UNSET, + prompt_cache_options: OptionalNullable[ + Union[components.PromptCacheOptions, components.PromptCacheOptionsTypedDict] + ] = UNSET, + provider: OptionalNullable[ + Union[ + components.ProviderPreferences, components.ProviderPreferencesTypedDict + ] + ] = UNSET, + reasoning: OptionalNullable[ + Union[components.ReasoningConfig, components.ReasoningConfigTypedDict] + ] = UNSET, + safety_identifier: OptionalNullable[str] = UNSET, + service_tier: OptionalNullable[components.ResponsesRequestServiceTier] = "auto", + session_id: Optional[str] = None, + stop_server_tools_when: Optional[ + Union[ + Iterable[components.StopServerToolsWhenCondition], + Iterable[components.StopServerToolsWhenConditionTypedDict], + ] + ] = None, + stream: Union[Literal[False], None] = None, + temperature: OptionalNullable[float] = UNSET, + text: Optional[ + Union[components.TextExtendedConfig, components.TextExtendedConfigTypedDict] + ] = None, + tool_choice: Optional[ + Union[ + components.OpenAIResponsesToolChoiceUnion, + components.OpenAIResponsesToolChoiceUnionTypedDict, + ] + ] = None, + tools: Optional[ + Union[ + Iterable[components.ResponsesRequestToolUnion], + Iterable[components.ResponsesRequestToolUnionTypedDict], + ] + ] = None, + top_k: Optional[int] = None, + top_logprobs: OptionalNullable[int] = UNSET, + top_p: OptionalNullable[float] = UNSET, + trace: Optional[ + Union[components.TraceConfig, components.TraceConfigTypedDict] + ] = None, + truncation: OptionalNullable[components.OpenAIResponsesTruncation] = UNSET, + user: Optional[str] = None, + retries: OptionalNullable[utils.RetryConfig] = UNSET, + server_url: Optional[str] = None, + timeout_ms: Optional[int] = None, + http_headers: Optional[Mapping[str, str]] = None, + ) -> components.OpenResponsesResult: + r"""Create a response + + Creates a streaming or non-streaming response using OpenResponses API format + + :param http_referer: The app identifier should be your app's URL and is used as the primary identifier for rankings. + This is used to track API usage per application. + + :param x_open_router_title: The app display name allows you to customize how your app appears in OpenRouter's dashboard. + + :param x_open_router_categories: Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings. + + :param x_open_router_metadata: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. + :param background: + :param cache_control: Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. + :param debug: Debug options for inspecting request transformations (streaming only) + :param frequency_penalty: + :param image_config: 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. + :param include: + :param input: Input for a response request - can be a string or array of items + :param instructions: + :param max_output_tokens: + :param max_tool_calls: Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. + :param metadata: 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. + :param modalities: Output modalities for the response. Supported values are \"text\" and \"image\". + :param model: + :param models: + :param parallel_tool_calls: + :param plugins: Plugins you want to enable for this request, including their settings. + :param presence_penalty: + :param previous_response_id: Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. + :param prompt: + :param prompt_cache_key: + :param prompt_cache_options: Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. + :param provider: When multiple model providers are available, optionally indicate your routing preference. + :param reasoning: Configuration for reasoning mode in the response + :param safety_identifier: Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. + :param service_tier: + :param session_id: A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. + :param stop_server_tools_when: Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. + :param stream: + :param temperature: + :param text: Text output configuration including format and verbosity + :param tool_choice: + :param tools: + :param top_k: + :param top_logprobs: + :param top_p: + :param trace: 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. + :param truncation: + :param user: 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 256 characters. + :param retries: Override the default retry configuration for this method + :param server_url: Override the default server URL for this method + :param timeout_ms: Override the default request timeout configuration for this method in milliseconds + :param http_headers: Additional headers to set or replace on requests. + """ + + @overload + async def send_async( + self, + *, + http_referer: Optional[str] = None, + x_open_router_title: Optional[str] = None, + x_open_router_categories: Optional[str] = None, + x_open_router_metadata: Optional[components.MetadataLevel] = None, + background: OptionalNullable[bool] = UNSET, + cache_control: Optional[ + Union[ + components.AnthropicCacheControlDirective, + components.AnthropicCacheControlDirectiveTypedDict, + ] + ] = None, + debug: Optional[ + Union[components.ChatDebugOptions, components.ChatDebugOptionsTypedDict] + ] = None, + frequency_penalty: OptionalNullable[float] = UNSET, + image_config: Optional[ + Union[ + Mapping[str, components.ImageConfig], + Mapping[str, components.ImageConfigTypedDict], + ] + ] = None, + include: OptionalNullable[Iterable[components.ResponseIncludesEnum]] = UNSET, + input: Optional[ + Union[components.InputsUnion, components.InputsUnionTypedDict] + ] = None, + instructions: OptionalNullable[str] = UNSET, + max_output_tokens: OptionalNullable[int] = UNSET, + max_tool_calls: OptionalNullable[int] = UNSET, + metadata: OptionalNullable[Mapping[str, str]] = UNSET, + modalities: Optional[Iterable[components.OutputModalityEnum]] = None, + model: Optional[str] = None, + models: Optional[Iterable[str]] = None, + parallel_tool_calls: OptionalNullable[bool] = UNSET, + plugins: Optional[ + Union[ + Iterable[components.ResponsesRequestPlugin], + Iterable[components.ResponsesRequestPluginTypedDict], + ] + ] = None, + presence_penalty: OptionalNullable[float] = UNSET, + previous_response_id: Optional[Any] = None, + prompt: OptionalNullable[ + Union[ + components.StoredPromptTemplate, + components.StoredPromptTemplateTypedDict, + ] + ] = UNSET, + prompt_cache_key: OptionalNullable[str] = UNSET, + prompt_cache_options: OptionalNullable[ + Union[components.PromptCacheOptions, components.PromptCacheOptionsTypedDict] + ] = UNSET, + provider: OptionalNullable[ + Union[ + components.ProviderPreferences, components.ProviderPreferencesTypedDict + ] + ] = UNSET, + reasoning: OptionalNullable[ + Union[components.ReasoningConfig, components.ReasoningConfigTypedDict] + ] = UNSET, + safety_identifier: OptionalNullable[str] = UNSET, + service_tier: OptionalNullable[components.ResponsesRequestServiceTier] = "auto", + session_id: Optional[str] = None, + stop_server_tools_when: Optional[ + Union[ + Iterable[components.StopServerToolsWhenCondition], + Iterable[components.StopServerToolsWhenConditionTypedDict], + ] + ] = None, + stream: Literal[True], + temperature: OptionalNullable[float] = UNSET, + text: Optional[ + Union[components.TextExtendedConfig, components.TextExtendedConfigTypedDict] + ] = None, + tool_choice: Optional[ + Union[ + components.OpenAIResponsesToolChoiceUnion, + components.OpenAIResponsesToolChoiceUnionTypedDict, + ] + ] = None, + tools: Optional[ + Union[ + Iterable[components.ResponsesRequestToolUnion], + Iterable[components.ResponsesRequestToolUnionTypedDict], + ] + ] = None, + top_k: Optional[int] = None, + top_logprobs: OptionalNullable[int] = UNSET, + top_p: OptionalNullable[float] = UNSET, + trace: Optional[ + Union[components.TraceConfig, components.TraceConfigTypedDict] + ] = None, + truncation: OptionalNullable[components.OpenAIResponsesTruncation] = UNSET, + user: Optional[str] = None, + retries: OptionalNullable[utils.RetryConfig] = UNSET, + server_url: Optional[str] = None, + timeout_ms: Optional[int] = None, + http_headers: Optional[Mapping[str, str]] = None, + ) -> eventstreaming.EventStreamAsync[components.StreamEvents]: + r"""Create a response + + Creates a streaming or non-streaming response using OpenResponses API format + + :param http_referer: The app identifier should be your app's URL and is used as the primary identifier for rankings. + This is used to track API usage per application. + + :param x_open_router_title: The app display name allows you to customize how your app appears in OpenRouter's dashboard. + + :param x_open_router_categories: Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings. + + :param x_open_router_metadata: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. + :param background: + :param cache_control: Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. + :param debug: Debug options for inspecting request transformations (streaming only) + :param frequency_penalty: + :param image_config: 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. + :param include: + :param input: Input for a response request - can be a string or array of items + :param instructions: + :param max_output_tokens: + :param max_tool_calls: Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. + :param metadata: 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. + :param modalities: Output modalities for the response. Supported values are \"text\" and \"image\". + :param model: + :param models: + :param parallel_tool_calls: + :param plugins: Plugins you want to enable for this request, including their settings. + :param presence_penalty: + :param previous_response_id: Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. + :param prompt: + :param prompt_cache_key: + :param prompt_cache_options: Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. + :param provider: When multiple model providers are available, optionally indicate your routing preference. + :param reasoning: Configuration for reasoning mode in the response + :param safety_identifier: Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. + :param service_tier: + :param session_id: A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. + :param stop_server_tools_when: Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. + :param stream: + :param temperature: + :param text: Text output configuration including format and verbosity + :param tool_choice: + :param tools: + :param top_k: + :param top_logprobs: + :param top_p: + :param trace: 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. + :param truncation: + :param user: 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 256 characters. + :param retries: Override the default retry configuration for this method + :param server_url: Override the default server URL for this method + :param timeout_ms: Override the default request timeout configuration for this method in milliseconds + :param http_headers: Additional headers to set or replace on requests. + """ + + @overload + async def send_async( + self, + *, + http_referer: Optional[str] = None, + x_open_router_title: Optional[str] = None, + x_open_router_categories: Optional[str] = None, + x_open_router_metadata: Optional[components.MetadataLevel] = None, + background: OptionalNullable[bool] = UNSET, + cache_control: Optional[ + Union[ + components.AnthropicCacheControlDirective, + components.AnthropicCacheControlDirectiveTypedDict, + ] + ] = None, + debug: Optional[ + Union[components.ChatDebugOptions, components.ChatDebugOptionsTypedDict] + ] = None, + frequency_penalty: OptionalNullable[float] = UNSET, + image_config: Optional[ + Union[ + Mapping[str, components.ImageConfig], + Mapping[str, components.ImageConfigTypedDict], + ] + ] = None, + include: OptionalNullable[Iterable[components.ResponseIncludesEnum]] = UNSET, + input: Optional[ + Union[components.InputsUnion, components.InputsUnionTypedDict] + ] = None, + instructions: OptionalNullable[str] = UNSET, + max_output_tokens: OptionalNullable[int] = UNSET, + max_tool_calls: OptionalNullable[int] = UNSET, + metadata: OptionalNullable[Mapping[str, str]] = UNSET, + modalities: Optional[Iterable[components.OutputModalityEnum]] = None, + model: Optional[str] = None, + models: Optional[Iterable[str]] = None, + parallel_tool_calls: OptionalNullable[bool] = UNSET, + plugins: Optional[ + Union[ + Iterable[components.ResponsesRequestPlugin], + Iterable[components.ResponsesRequestPluginTypedDict], + ] + ] = None, + presence_penalty: OptionalNullable[float] = UNSET, + previous_response_id: Optional[Any] = None, + prompt: OptionalNullable[ + Union[ + components.StoredPromptTemplate, + components.StoredPromptTemplateTypedDict, + ] + ] = UNSET, + prompt_cache_key: OptionalNullable[str] = UNSET, + prompt_cache_options: OptionalNullable[ + Union[components.PromptCacheOptions, components.PromptCacheOptionsTypedDict] + ] = UNSET, + provider: OptionalNullable[ + Union[ + components.ProviderPreferences, components.ProviderPreferencesTypedDict + ] + ] = UNSET, + reasoning: OptionalNullable[ + Union[components.ReasoningConfig, components.ReasoningConfigTypedDict] + ] = UNSET, + safety_identifier: OptionalNullable[str] = UNSET, + service_tier: OptionalNullable[components.ResponsesRequestServiceTier] = "auto", + session_id: Optional[str] = None, + stop_server_tools_when: Optional[ + Union[ + Iterable[components.StopServerToolsWhenCondition], + Iterable[components.StopServerToolsWhenConditionTypedDict], + ] + ] = None, + stream: bool, + temperature: OptionalNullable[float] = UNSET, + text: Optional[ + Union[components.TextExtendedConfig, components.TextExtendedConfigTypedDict] + ] = None, + tool_choice: Optional[ + Union[ + components.OpenAIResponsesToolChoiceUnion, + components.OpenAIResponsesToolChoiceUnionTypedDict, + ] + ] = None, + tools: Optional[ + Union[ + Iterable[components.ResponsesRequestToolUnion], + Iterable[components.ResponsesRequestToolUnionTypedDict], + ] + ] = None, + top_k: Optional[int] = None, + top_logprobs: OptionalNullable[int] = UNSET, + top_p: OptionalNullable[float] = UNSET, + trace: Optional[ + Union[components.TraceConfig, components.TraceConfigTypedDict] + ] = None, + truncation: OptionalNullable[components.OpenAIResponsesTruncation] = UNSET, + user: Optional[str] = None, + retries: OptionalNullable[utils.RetryConfig] = UNSET, + server_url: Optional[str] = None, + timeout_ms: Optional[int] = None, + http_headers: Optional[Mapping[str, str]] = None, + ) -> Union[ + components.OpenResponsesResult, + eventstreaming.EventStreamAsync[components.StreamEvents], + ]: + r"""Create a response + + Creates a streaming or non-streaming response using OpenResponses API format + + :param http_referer: The app identifier should be your app's URL and is used as the primary identifier for rankings. + This is used to track API usage per application. + + :param x_open_router_title: The app display name allows you to customize how your app appears in OpenRouter's dashboard. + + :param x_open_router_categories: Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings. + + :param x_open_router_metadata: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. + :param background: + :param cache_control: Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. + :param debug: Debug options for inspecting request transformations (streaming only) + :param frequency_penalty: + :param image_config: 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. + :param include: + :param input: Input for a response request - can be a string or array of items + :param instructions: + :param max_output_tokens: + :param max_tool_calls: Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. + :param metadata: 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. + :param modalities: Output modalities for the response. Supported values are \"text\" and \"image\". + :param model: + :param models: + :param parallel_tool_calls: + :param plugins: Plugins you want to enable for this request, including their settings. + :param presence_penalty: + :param previous_response_id: Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. + :param prompt: + :param prompt_cache_key: + :param prompt_cache_options: Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. + :param provider: When multiple model providers are available, optionally indicate your routing preference. + :param reasoning: Configuration for reasoning mode in the response + :param safety_identifier: Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. + :param service_tier: + :param session_id: A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. + :param stop_server_tools_when: Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. + :param stream: + :param temperature: + :param text: Text output configuration including format and verbosity + :param tool_choice: + :param tools: + :param top_k: + :param top_logprobs: + :param top_p: + :param trace: 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. + :param truncation: + :param user: 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 256 characters. + :param retries: Override the default retry configuration for this method + :param server_url: Override the default server URL for this method + :param timeout_ms: Override the default request timeout configuration for this method in milliseconds + :param http_headers: Additional headers to set or replace on requests. + """ + + async def send_async( + self, + *, + http_referer: Optional[str] = None, + x_open_router_title: Optional[str] = None, + x_open_router_categories: Optional[str] = None, + x_open_router_metadata: Optional[components.MetadataLevel] = None, + background: OptionalNullable[bool] = UNSET, + cache_control: Optional[ + Union[ + components.AnthropicCacheControlDirective, + components.AnthropicCacheControlDirectiveTypedDict, + ] + ] = None, + debug: Optional[ + Union[components.ChatDebugOptions, components.ChatDebugOptionsTypedDict] + ] = None, + frequency_penalty: OptionalNullable[float] = UNSET, + image_config: Optional[ + Union[ + Mapping[str, components.ImageConfig], + Mapping[str, components.ImageConfigTypedDict], + ] + ] = None, + include: OptionalNullable[Iterable[components.ResponseIncludesEnum]] = UNSET, + input: Optional[ + Union[components.InputsUnion, components.InputsUnionTypedDict] + ] = None, + instructions: OptionalNullable[str] = UNSET, + max_output_tokens: OptionalNullable[int] = UNSET, + max_tool_calls: OptionalNullable[int] = UNSET, + metadata: OptionalNullable[Mapping[str, str]] = UNSET, + modalities: Optional[Iterable[components.OutputModalityEnum]] = None, + model: Optional[str] = None, + models: Optional[Iterable[str]] = None, + parallel_tool_calls: OptionalNullable[bool] = UNSET, + plugins: Optional[ + Union[ + Iterable[components.ResponsesRequestPlugin], + Iterable[components.ResponsesRequestPluginTypedDict], + ] + ] = None, + presence_penalty: OptionalNullable[float] = UNSET, + previous_response_id: Optional[Any] = None, + prompt: OptionalNullable[ + Union[ + components.StoredPromptTemplate, + components.StoredPromptTemplateTypedDict, + ] + ] = UNSET, + prompt_cache_key: OptionalNullable[str] = UNSET, + prompt_cache_options: OptionalNullable[ + Union[components.PromptCacheOptions, components.PromptCacheOptionsTypedDict] + ] = UNSET, + provider: OptionalNullable[ + Union[ + components.ProviderPreferences, components.ProviderPreferencesTypedDict + ] + ] = UNSET, + reasoning: OptionalNullable[ + Union[components.ReasoningConfig, components.ReasoningConfigTypedDict] + ] = UNSET, + safety_identifier: OptionalNullable[str] = UNSET, + service_tier: OptionalNullable[components.ResponsesRequestServiceTier] = "auto", + session_id: Optional[str] = None, + stop_server_tools_when: Optional[ + Union[ + Iterable[components.StopServerToolsWhenCondition], + Iterable[components.StopServerToolsWhenConditionTypedDict], + ] + ] = None, + stream: Optional[bool] = False, + temperature: OptionalNullable[float] = UNSET, + text: Optional[ + Union[components.TextExtendedConfig, components.TextExtendedConfigTypedDict] + ] = None, + tool_choice: Optional[ + Union[ + components.OpenAIResponsesToolChoiceUnion, + components.OpenAIResponsesToolChoiceUnionTypedDict, + ] + ] = None, + tools: Optional[ + Union[ + Iterable[components.ResponsesRequestToolUnion], + Iterable[components.ResponsesRequestToolUnionTypedDict], + ] + ] = None, + top_k: Optional[int] = None, + top_logprobs: OptionalNullable[int] = UNSET, + top_p: OptionalNullable[float] = UNSET, + trace: Optional[ + Union[components.TraceConfig, components.TraceConfigTypedDict] + ] = None, + truncation: OptionalNullable[components.OpenAIResponsesTruncation] = UNSET, + user: Optional[str] = None, + retries: OptionalNullable[utils.RetryConfig] = UNSET, + server_url: Optional[str] = None, + timeout_ms: Optional[int] = None, + http_headers: Optional[Mapping[str, str]] = None, + ) -> Union[ + components.OpenResponsesResult, + eventstreaming.EventStreamAsync[components.StreamEvents], + ]: + r"""Create a response + + Creates a streaming or non-streaming response using OpenResponses API format + + :param http_referer: The app identifier should be your app's URL and is used as the primary identifier for rankings. + This is used to track API usage per application. + + :param x_open_router_title: The app display name allows you to customize how your app appears in OpenRouter's dashboard. + + :param x_open_router_categories: Comma-separated list of app categories (e.g. \"cli-agent,cloud-agent\"). Used for marketplace rankings. + + :param x_open_router_metadata: Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility. + :param background: + :param cache_control: Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format. + :param debug: Debug options for inspecting request transformations (streaming only) + :param frequency_penalty: + :param image_config: 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. + :param include: + :param input: Input for a response request - can be a string or array of items + :param instructions: + :param max_output_tokens: + :param max_tool_calls: Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set. + :param metadata: 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. + :param modalities: Output modalities for the response. Supported values are \"text\" and \"image\". + :param model: + :param models: + :param parallel_tool_calls: + :param plugins: Plugins you want to enable for this request, including their settings. + :param presence_penalty: + :param previous_response_id: Not supported. The Responses API is stateless: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead. + :param prompt: + :param prompt_cache_key: + :param prompt_cache_options: Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. + :param provider: When multiple model providers are available, optionally indicate your routing preference. + :param reasoning: Configuration for reasoning mode in the response + :param safety_identifier: Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account. + :param service_tier: + :param session_id: A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. + :param stop_server_tools_when: Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call. + :param stream: + :param temperature: + :param text: Text output configuration including format and verbosity + :param tool_choice: + :param tools: + :param top_k: + :param top_logprobs: + :param top_p: + :param trace: 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. + :param truncation: + :param user: 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 256 characters. + :param retries: Override the default retry configuration for this method + :param server_url: Override the default server URL for this method + :param timeout_ms: Override the default request timeout configuration for this method in milliseconds + :param http_headers: Additional headers to set or replace on requests. + """ + base_url = None + url_variables = None + if timeout_ms is None: + timeout_ms = self.sdk_configuration.timeout_ms + + if server_url is not None: + base_url = server_url + else: + base_url = self._get_url(base_url, url_variables) + + request = operations.CreateResponsesRequest( + http_referer=http_referer, + x_open_router_title=x_open_router_title, + x_open_router_categories=x_open_router_categories, + x_open_router_metadata=x_open_router_metadata, + responses_request=components.ResponsesRequest( + background=background, + cache_control=utils.get_pydantic_model( + cache_control, Optional[components.AnthropicCacheControlDirective] + ), + debug=utils.get_pydantic_model( + debug, Optional[components.ChatDebugOptions] + ), + frequency_penalty=frequency_penalty, + image_config=utils.unmarshal( + image_config, Optional[Dict[str, components.ImageConfig]] + ), + include=utils.unmarshal( + include, OptionalNullable[List[components.ResponseIncludesEnum]] + ), + input=utils.get_pydantic_model(input, Optional[components.InputsUnion]), + instructions=instructions, + max_output_tokens=max_output_tokens, + max_tool_calls=max_tool_calls, + metadata=utils.unmarshal(metadata, OptionalNullable[Dict[str, str]]), + modalities=utils.unmarshal( + modalities, Optional[List[components.OutputModalityEnum]] + ), + model=model, + models=utils.unmarshal(models, Optional[List[str]]), + parallel_tool_calls=parallel_tool_calls, + plugins=utils.get_pydantic_model( + plugins, Optional[List[components.ResponsesRequestPlugin]] + ), + presence_penalty=presence_penalty, + previous_response_id=previous_response_id, + prompt=utils.get_pydantic_model( + prompt, OptionalNullable[components.StoredPromptTemplate] + ), + prompt_cache_key=prompt_cache_key, + prompt_cache_options=utils.get_pydantic_model( + prompt_cache_options, + OptionalNullable[components.PromptCacheOptions], + ), + provider=utils.get_pydantic_model( + provider, OptionalNullable[components.ProviderPreferences] + ), + reasoning=utils.get_pydantic_model( + reasoning, OptionalNullable[components.ReasoningConfig] + ), + safety_identifier=safety_identifier, + service_tier=service_tier, + session_id=session_id, + stop_server_tools_when=utils.get_pydantic_model( + stop_server_tools_when, + Optional[List[components.StopServerToolsWhenCondition]], + ), + stream=stream, + temperature=temperature, + text=utils.get_pydantic_model( + text, Optional[components.TextExtendedConfig] + ), + tool_choice=utils.get_pydantic_model( + tool_choice, Optional[components.OpenAIResponsesToolChoiceUnion] + ), + tools=utils.get_pydantic_model( + tools, Optional[List[components.ResponsesRequestToolUnion]] + ), + top_k=top_k, + top_logprobs=top_logprobs, + top_p=top_p, + trace=utils.get_pydantic_model(trace, Optional[components.TraceConfig]), + truncation=truncation, + user=user, + ), + ) + + req = self._build_request_async( + method="POST", + path="/responses", + base_url=base_url, + url_variables=url_variables, + request=request, + request_body_required=True, + request_has_path_params=False, + request_has_query_params=True, + user_agent_header="user-agent", + accept_header_value="text/event-stream" + if stream is True + else "application/json", + http_headers=http_headers, + _globals=operations.CreateResponsesGlobals( + http_referer=self.sdk_configuration.globals.http_referer, + x_open_router_title=self.sdk_configuration.globals.x_open_router_title, + x_open_router_categories=self.sdk_configuration.globals.x_open_router_categories, + ), + security=self.sdk_configuration.security, + get_serialized_body=lambda: utils.serialize_request_body( + request.responses_request, + False, + False, + "json", + components.ResponsesRequest, + ), + allow_empty_value=None, + timeout_ms=timeout_ms, + ) + + if retries == UNSET: + if self.sdk_configuration.retry_config is not UNSET: + retries = self.sdk_configuration.retry_config + else: + retries = utils.RetryConfig( + "backoff", utils.BackoffStrategy(500, 60000, 1.5, 3600000), True + ) + + retry_config = None + if isinstance(retries, utils.RetryConfig): + retry_config = (retries, ["5XX"]) + + http_res = await self.do_request_async( + hook_ctx=HookContext( + config=self.sdk_configuration, + base_url=base_url or "", + operation_id="createResponses", + oauth2_scopes=None, + security_source=get_security_from_env( + self.sdk_configuration.security, components.Security + ), + tags=["responses", "beta.responses"], + extensions=None, + ), + request=req, + is_error_status_code=lambda c: utils.match_status_codes(["4XX", "5XX"], c), + stream=stream is True, + retry_config=retry_config, + ) + + response_data: Any = None + if utils.match_response(http_res, "200", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + return unmarshal_json_response( + components.OpenResponsesResult, http_res, http_res_text + ) + if utils.match_response(http_res, "200", "text/event-stream"): + return eventstreaming.EventStreamAsync( + http_res, + lambda raw: unmarshal_json_response( + components.ResponsesStreamingResponse, http_res, raw + ).data, + sentinel="[DONE]", + client_ref=self, + ) + if utils.match_response(http_res, "400", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.BadRequestResponseErrorData, http_res, http_res_text + ) + raise errors.BadRequestResponseError(response_data, http_res, http_res_text) + if utils.match_response(http_res, "401", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.UnauthorizedResponseErrorData, http_res, http_res_text + ) + raise errors.UnauthorizedResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "402", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.PaymentRequiredResponseErrorData, http_res, http_res_text + ) + raise errors.PaymentRequiredResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "403", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.ForbiddenResponseErrorData, http_res, http_res_text + ) + raise errors.ForbiddenResponseError(response_data, http_res, http_res_text) + if utils.match_response(http_res, "404", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.NotFoundResponseErrorData, http_res, http_res_text + ) + raise errors.NotFoundResponseError(response_data, http_res, http_res_text) + if utils.match_response(http_res, "408", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.RequestTimeoutResponseErrorData, http_res, http_res_text + ) + raise errors.RequestTimeoutResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "413", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.PayloadTooLargeResponseErrorData, http_res, http_res_text + ) + raise errors.PayloadTooLargeResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "422", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.UnprocessableEntityResponseErrorData, http_res, http_res_text + ) + raise errors.UnprocessableEntityResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "429", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.TooManyRequestsResponseErrorData, http_res, http_res_text + ) + raise errors.TooManyRequestsResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "500", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.InternalServerResponseErrorData, http_res, http_res_text + ) + raise errors.InternalServerResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "502", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.BadGatewayResponseErrorData, http_res, http_res_text + ) + raise errors.BadGatewayResponseError(response_data, http_res, http_res_text) + if utils.match_response(http_res, "503", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.ServiceUnavailableResponseErrorData, http_res, http_res_text + ) + raise errors.ServiceUnavailableResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "524", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.EdgeNetworkTimeoutResponseErrorData, http_res, http_res_text + ) + raise errors.EdgeNetworkTimeoutResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "529", "application/json"): + http_res_text = await utils.stream_to_text_async(http_res) + response_data = unmarshal_json_response( + errors.ProviderOverloadedResponseErrorData, http_res, http_res_text + ) + raise errors.ProviderOverloadedResponseError( + response_data, http_res, http_res_text + ) + if utils.match_response(http_res, "4XX", "*"): + http_res_text = await utils.stream_to_text_async(http_res) + raise errors.OpenRouterDefaultError( + "API error occurred", http_res, http_res_text + ) + if utils.match_response(http_res, "5XX", "*"): + http_res_text = await utils.stream_to_text_async(http_res) + raise errors.OpenRouterDefaultError( + "API error occurred", http_res, http_res_text + ) + + http_res_text = await utils.stream_to_text_async(http_res) + raise errors.OpenRouterDefaultError( + "Unexpected response received", http_res, http_res_text + ) diff --git a/src/openrouter/responses.py b/src/openrouter/responses.py index cc793c72..db9f7f73 100644 --- a/src/openrouter/responses.py +++ b/src/openrouter/responses.py @@ -20,7 +20,7 @@ class Responses(BaseSDK): - r"""beta.responses endpoints""" + r"""responses endpoints""" @overload def send( @@ -797,7 +797,7 @@ def send( security_source=get_security_from_env( self.sdk_configuration.security, components.Security ), - tags=["beta.responses"], + tags=["responses", "beta.responses"], extensions=None, ), request=req, @@ -1716,7 +1716,7 @@ async def send_async( security_source=get_security_from_env( self.sdk_configuration.security, components.Security ), - tags=["beta.responses"], + tags=["responses", "beta.responses"], extensions=None, ), request=req, diff --git a/src/openrouter/sdk.py b/src/openrouter/sdk.py index a6a9afda..ced544d3 100644 --- a/src/openrouter/sdk.py +++ b/src/openrouter/sdk.py @@ -38,6 +38,7 @@ from openrouter.presets import Presets from openrouter.providers import Providers from openrouter.rerank import Rerank + from openrouter.responses import Responses from openrouter.stt import Stt from openrouter.tts import Tts from openrouter.video_generation import VideoGeneration @@ -95,6 +96,8 @@ class OpenRouter(BaseSDK): r"""Provider information endpoints""" rerank: "Rerank" r"""Rerank endpoints""" + responses: "Responses" + r"""responses endpoints""" video_generation: "VideoGeneration" r"""Video Generation endpoints""" workspaces: "Workspaces" @@ -124,6 +127,7 @@ class OpenRouter(BaseSDK): "presets": ("openrouter.presets", "Presets"), "providers": ("openrouter.providers", "Providers"), "rerank": ("openrouter.rerank", "Rerank"), + "responses": ("openrouter.responses", "Responses"), "video_generation": ("openrouter.video_generation", "VideoGeneration"), "workspaces": ("openrouter.workspaces", "Workspaces"), } diff --git a/tests/test_responses_namespace.py b/tests/test_responses_namespace.py new file mode 100644 index 00000000..b4be3218 --- /dev/null +++ b/tests/test_responses_namespace.py @@ -0,0 +1,10 @@ +from openrouter import OpenRouter + + +def test_responses_namespace_is_ga_and_beta_alias_remains_available(): + client = OpenRouter(api_key="test-key") + + assert client.responses is not None + assert client.beta.responses is not None + assert type(client.responses) is type(client.beta.responses) + assert client.beta.analytics is not None diff --git a/uv.lock b/uv.lock index b0baabf3..8f92c861 100644 --- a/uv.lock +++ b/uv.lock @@ -75,7 +75,7 @@ name = "exceptiongroup" version = "1.3.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "typing-extensions" }, + { name = "typing-extensions", marker = "python_full_version < '3.11'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/0b/9f/a65090624ecf468cdca03533906e7c69ed7588582240cfe7cc9e770b50eb/exceptiongroup-1.3.0.tar.gz", hash = "sha256:b241f5885f560bc56a59ee63ca4c6a8bfa46ae4ad651af316d4e81817bb9fd88", size = 29749, upload-time = "2025-05-10T17:42:51.123Z" } wheels = [ @@ -213,7 +213,7 @@ wheels = [ [[package]] name = "openrouter" -version = "1.0.22" +version = "1.1.0" source = { editable = "." } dependencies = [ { name = "httpcore" },