"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.""" from .basesdk import BaseSDK from enum import Enum 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, List, Literal, Mapping, Optional, Union, overload class GenerateAcceptEnum(str, Enum): APPLICATION_JSON = "application/json" TEXT_EVENT_STREAM = "text/event-stream" class Images(BaseSDK): r"""Images endpoints""" @overload def generate( self, *, model: str, prompt: str, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: Optional[str] = None, aspect_ratio: Optional[components.ImageGenerationRequestAspectRatio] = None, background: Optional[components.ImageGenerationRequestBackground] = None, input_references: Optional[ Union[ List[components.ContentPartImage], List[components.ContentPartImageTypedDict], ] ] = None, n: Optional[int] = None, output_compression: Optional[int] = None, output_format: Optional[components.ImageGenerationRequestOutputFormat] = None, provider: Optional[ Union[ components.ImageGenerationRequestProvider, components.ImageGenerationRequestProviderTypedDict, ] ] = None, quality: Optional[components.ImageGenerationRequestQuality] = None, resolution: Optional[components.ImageGenerationRequestResolution] = None, seed: Optional[int] = None, size: Optional[str] = None, stream: Union[Literal[False], None] = None, retries: OptionalNullable[utils.RetryConfig] = UNSET, server_url: Optional[str] = None, timeout_ms: Optional[int] = None, http_headers: Optional[Mapping[str, str]] = None, ) -> components.ImageGenerationResponse: r"""Generate an image Generates an image from a text prompt via the image generation router :param model: The image generation model to use :param prompt: Text description of the desired image :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 aspect_ratio: Normalized aspect ratio of the generated image. Providers clamp to their supported subset. :param background: Background treatment. `transparent` requires an output_format that supports alpha (png or webp). :param input_references: Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs. :param n: Number of images to generate (1-10). Providers that only support single-image generation reject n > 1. :param output_compression: Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob. :param output_format: Encoding of the returned image bytes. :param provider: Provider-specific passthrough configuration :param quality: Rendering quality. Providers without a quality knob ignore this. :param resolution: Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider. :param seed: If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers. :param size: Optional. A convenience shorthand for output dimensions — pass a tier (\"2K\", \"4K\") or explicit pixels (\"2048x2048\") and we normalize it to the right dimensions for the chosen provider. Interchangeable with resolution + aspect_ratio; use those directly for enumerated, per-model discoverable values. Conflicting size + resolution/aspect_ratio is rejected. :param stream: If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response. :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 accept_header_override: Override the default accept header for this method :param http_headers: Additional headers to set or replace on requests. """ @overload def generate( self, *, model: str, prompt: str, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: Optional[str] = None, aspect_ratio: Optional[components.ImageGenerationRequestAspectRatio] = None, background: Optional[components.ImageGenerationRequestBackground] = None, input_references: Optional[ Union[ List[components.ContentPartImage], List[components.ContentPartImageTypedDict], ] ] = None, n: Optional[int] = None, output_compression: Optional[int] = None, output_format: Optional[components.ImageGenerationRequestOutputFormat] = None, provider: Optional[ Union[ components.ImageGenerationRequestProvider, components.ImageGenerationRequestProviderTypedDict, ] ] = None, quality: Optional[components.ImageGenerationRequestQuality] = None, resolution: Optional[components.ImageGenerationRequestResolution] = None, seed: Optional[int] = None, size: Optional[str] = None, stream: Literal[True], 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.ImageStreamingResponseData]: r"""Generate an image Generates an image from a text prompt via the image generation router :param model: The image generation model to use :param prompt: Text description of the desired image :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 aspect_ratio: Normalized aspect ratio of the generated image. Providers clamp to their supported subset. :param background: Background treatment. `transparent` requires an output_format that supports alpha (png or webp). :param input_references: Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs. :param n: Number of images to generate (1-10). Providers that only support single-image generation reject n > 1. :param output_compression: Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob. :param output_format: Encoding of the returned image bytes. :param provider: Provider-specific passthrough configuration :param quality: Rendering quality. Providers without a quality knob ignore this. :param resolution: Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider. :param seed: If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers. :param size: Optional. A convenience shorthand for output dimensions — pass a tier (\"2K\", \"4K\") or explicit pixels (\"2048x2048\") and we normalize it to the right dimensions for the chosen provider. Interchangeable with resolution + aspect_ratio; use those directly for enumerated, per-model discoverable values. Conflicting size + resolution/aspect_ratio is rejected. :param stream: If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response. :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 accept_header_override: Override the default accept header for this method :param http_headers: Additional headers to set or replace on requests. """ def generate( self, *, model: str, prompt: str, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: Optional[str] = None, aspect_ratio: Optional[components.ImageGenerationRequestAspectRatio] = None, background: Optional[components.ImageGenerationRequestBackground] = None, input_references: Optional[ Union[ List[components.ContentPartImage], List[components.ContentPartImageTypedDict], ] ] = None, n: Optional[int] = None, output_compression: Optional[int] = None, output_format: Optional[components.ImageGenerationRequestOutputFormat] = None, provider: Optional[ Union[ components.ImageGenerationRequestProvider, components.ImageGenerationRequestProviderTypedDict, ] ] = None, quality: Optional[components.ImageGenerationRequestQuality] = None, resolution: Optional[components.ImageGenerationRequestResolution] = None, seed: Optional[int] = None, size: Optional[str] = None, stream: Optional[bool] = None, retries: OptionalNullable[utils.RetryConfig] = UNSET, server_url: Optional[str] = None, timeout_ms: Optional[int] = None, http_headers: Optional[Mapping[str, str]] = None, ) -> operations.CreateImagesResponse: r"""Generate an image Generates an image from a text prompt via the image generation router :param model: The image generation model to use :param prompt: Text description of the desired image :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 aspect_ratio: Normalized aspect ratio of the generated image. Providers clamp to their supported subset. :param background: Background treatment. `transparent` requires an output_format that supports alpha (png or webp). :param input_references: Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs. :param n: Number of images to generate (1-10). Providers that only support single-image generation reject n > 1. :param output_compression: Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob. :param output_format: Encoding of the returned image bytes. :param provider: Provider-specific passthrough configuration :param quality: Rendering quality. Providers without a quality knob ignore this. :param resolution: Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider. :param seed: If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers. :param size: Optional. A convenience shorthand for output dimensions — pass a tier (\"2K\", \"4K\") or explicit pixels (\"2048x2048\") and we normalize it to the right dimensions for the chosen provider. Interchangeable with resolution + aspect_ratio; use those directly for enumerated, per-model discoverable values. Conflicting size + resolution/aspect_ratio is rejected. :param stream: If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response. :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 accept_header_override: Override the default accept header for this method :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.CreateImagesRequest( http_referer=http_referer, x_open_router_title=x_open_router_title, x_open_router_categories=x_open_router_categories, image_generation_request=components.ImageGenerationRequest( aspect_ratio=aspect_ratio, background=background, input_references=utils.get_pydantic_model( input_references, Optional[List[components.ContentPartImage]] ), model=model, n=n, output_compression=output_compression, output_format=output_format, prompt=prompt, provider=utils.get_pydantic_model( provider, Optional[components.ImageGenerationRequestProvider] ), quality=quality, resolution=resolution, seed=seed, size=size, stream=stream, ), ) req = self._build_request( method="POST", path="/images", 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 else "application/json", http_headers=http_headers, _globals=operations.CreateImagesGlobals( 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.image_generation_request, False, False, "json", components.ImageGenerationRequest, ), 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="createImages", oauth2_scopes=None, security_source=get_security_from_env( self.sdk_configuration.security, components.Security ), ), request=req, error_status_codes=[ "400", "401", "402", "403", "404", "429", "4XX", "500", "502", "524", "529", "5XX", ], stream=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.ImageGenerationResponse, http_res, http_res_text ) if utils.match_response(http_res, "200", "text/event-stream"): return eventstreaming.EventStream( http_res, lambda raw: utils.unmarshal_json( raw, components.ImageStreamingResponse ).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, "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, "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 generate_async( self, *, model: str, prompt: str, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: Optional[str] = None, aspect_ratio: Optional[components.ImageGenerationRequestAspectRatio] = None, background: Optional[components.ImageGenerationRequestBackground] = None, input_references: Optional[ Union[ List[components.ContentPartImage], List[components.ContentPartImageTypedDict], ] ] = None, n: Optional[int] = None, output_compression: Optional[int] = None, output_format: Optional[components.ImageGenerationRequestOutputFormat] = None, provider: Optional[ Union[ components.ImageGenerationRequestProvider, components.ImageGenerationRequestProviderTypedDict, ] ] = None, quality: Optional[components.ImageGenerationRequestQuality] = None, resolution: Optional[components.ImageGenerationRequestResolution] = None, seed: Optional[int] = None, size: Optional[str] = None, stream: Union[Literal[False], None] = None, retries: OptionalNullable[utils.RetryConfig] = UNSET, server_url: Optional[str] = None, timeout_ms: Optional[int] = None, http_headers: Optional[Mapping[str, str]] = None, ) -> components.ImageGenerationResponse: r"""Generate an image Generates an image from a text prompt via the image generation router :param model: The image generation model to use :param prompt: Text description of the desired image :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 aspect_ratio: Normalized aspect ratio of the generated image. Providers clamp to their supported subset. :param background: Background treatment. `transparent` requires an output_format that supports alpha (png or webp). :param input_references: Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs. :param n: Number of images to generate (1-10). Providers that only support single-image generation reject n > 1. :param output_compression: Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob. :param output_format: Encoding of the returned image bytes. :param provider: Provider-specific passthrough configuration :param quality: Rendering quality. Providers without a quality knob ignore this. :param resolution: Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider. :param seed: If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers. :param size: Optional. A convenience shorthand for output dimensions — pass a tier (\"2K\", \"4K\") or explicit pixels (\"2048x2048\") and we normalize it to the right dimensions for the chosen provider. Interchangeable with resolution + aspect_ratio; use those directly for enumerated, per-model discoverable values. Conflicting size + resolution/aspect_ratio is rejected. :param stream: If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response. :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 accept_header_override: Override the default accept header for this method :param http_headers: Additional headers to set or replace on requests. """ @overload async def generate_async( self, *, model: str, prompt: str, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: Optional[str] = None, aspect_ratio: Optional[components.ImageGenerationRequestAspectRatio] = None, background: Optional[components.ImageGenerationRequestBackground] = None, input_references: Optional[ Union[ List[components.ContentPartImage], List[components.ContentPartImageTypedDict], ] ] = None, n: Optional[int] = None, output_compression: Optional[int] = None, output_format: Optional[components.ImageGenerationRequestOutputFormat] = None, provider: Optional[ Union[ components.ImageGenerationRequestProvider, components.ImageGenerationRequestProviderTypedDict, ] ] = None, quality: Optional[components.ImageGenerationRequestQuality] = None, resolution: Optional[components.ImageGenerationRequestResolution] = None, seed: Optional[int] = None, size: Optional[str] = None, stream: Literal[True], 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.ImageStreamingResponseData]: r"""Generate an image Generates an image from a text prompt via the image generation router :param model: The image generation model to use :param prompt: Text description of the desired image :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 aspect_ratio: Normalized aspect ratio of the generated image. Providers clamp to their supported subset. :param background: Background treatment. `transparent` requires an output_format that supports alpha (png or webp). :param input_references: Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs. :param n: Number of images to generate (1-10). Providers that only support single-image generation reject n > 1. :param output_compression: Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob. :param output_format: Encoding of the returned image bytes. :param provider: Provider-specific passthrough configuration :param quality: Rendering quality. Providers without a quality knob ignore this. :param resolution: Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider. :param seed: If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers. :param size: Optional. A convenience shorthand for output dimensions — pass a tier (\"2K\", \"4K\") or explicit pixels (\"2048x2048\") and we normalize it to the right dimensions for the chosen provider. Interchangeable with resolution + aspect_ratio; use those directly for enumerated, per-model discoverable values. Conflicting size + resolution/aspect_ratio is rejected. :param stream: If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response. :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 accept_header_override: Override the default accept header for this method :param http_headers: Additional headers to set or replace on requests. """ async def generate_async( self, *, model: str, prompt: str, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: Optional[str] = None, aspect_ratio: Optional[components.ImageGenerationRequestAspectRatio] = None, background: Optional[components.ImageGenerationRequestBackground] = None, input_references: Optional[ Union[ List[components.ContentPartImage], List[components.ContentPartImageTypedDict], ] ] = None, n: Optional[int] = None, output_compression: Optional[int] = None, output_format: Optional[components.ImageGenerationRequestOutputFormat] = None, provider: Optional[ Union[ components.ImageGenerationRequestProvider, components.ImageGenerationRequestProviderTypedDict, ] ] = None, quality: Optional[components.ImageGenerationRequestQuality] = None, resolution: Optional[components.ImageGenerationRequestResolution] = None, seed: Optional[int] = None, size: Optional[str] = None, stream: Optional[bool] = None, retries: OptionalNullable[utils.RetryConfig] = UNSET, server_url: Optional[str] = None, timeout_ms: Optional[int] = None, http_headers: Optional[Mapping[str, str]] = None, ) -> operations.CreateImagesResponse: r"""Generate an image Generates an image from a text prompt via the image generation router :param model: The image generation model to use :param prompt: Text description of the desired image :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 aspect_ratio: Normalized aspect ratio of the generated image. Providers clamp to their supported subset. :param background: Background treatment. `transparent` requires an output_format that supports alpha (png or webp). :param input_references: Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs. :param n: Number of images to generate (1-10). Providers that only support single-image generation reject n > 1. :param output_compression: Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob. :param output_format: Encoding of the returned image bytes. :param provider: Provider-specific passthrough configuration :param quality: Rendering quality. Providers without a quality knob ignore this. :param resolution: Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider. :param seed: If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers. :param size: Optional. A convenience shorthand for output dimensions — pass a tier (\"2K\", \"4K\") or explicit pixels (\"2048x2048\") and we normalize it to the right dimensions for the chosen provider. Interchangeable with resolution + aspect_ratio; use those directly for enumerated, per-model discoverable values. Conflicting size + resolution/aspect_ratio is rejected. :param stream: If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response. :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 accept_header_override: Override the default accept header for this method :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.CreateImagesRequest( http_referer=http_referer, x_open_router_title=x_open_router_title, x_open_router_categories=x_open_router_categories, image_generation_request=components.ImageGenerationRequest( aspect_ratio=aspect_ratio, background=background, input_references=utils.get_pydantic_model( input_references, Optional[List[components.ContentPartImage]] ), model=model, n=n, output_compression=output_compression, output_format=output_format, prompt=prompt, provider=utils.get_pydantic_model( provider, Optional[components.ImageGenerationRequestProvider] ), quality=quality, resolution=resolution, seed=seed, size=size, stream=stream, ), ) req = self._build_request_async( method="POST", path="/images", 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 else "application/json", http_headers=http_headers, _globals=operations.CreateImagesGlobals( 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.image_generation_request, False, False, "json", components.ImageGenerationRequest, ), 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="createImages", oauth2_scopes=None, security_source=get_security_from_env( self.sdk_configuration.security, components.Security ), ), request=req, error_status_codes=[ "400", "401", "402", "403", "404", "429", "4XX", "500", "502", "524", "529", "5XX", ], stream=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.ImageGenerationResponse, http_res, http_res_text ) if utils.match_response(http_res, "200", "text/event-stream"): return eventstreaming.EventStreamAsync( http_res, lambda raw: utils.unmarshal_json( raw, components.ImageStreamingResponse ).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, "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, "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 ) def list_models( self, *, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: 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.ImageModelsListResponse: r"""List image generation models Lists every image generation model with its top-level supported-parameter superset and a URL to its full per-endpoint records. :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 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.ListImageModelsRequest( http_referer=http_referer, x_open_router_title=x_open_router_title, x_open_router_categories=x_open_router_categories, ) req = self._build_request( method="GET", path="/images/models", base_url=base_url, url_variables=url_variables, request=request, request_body_required=False, request_has_path_params=False, request_has_query_params=True, user_agent_header="user-agent", accept_header_value="application/json", http_headers=http_headers, _globals=operations.ListImageModelsGlobals( 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, 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="listImageModels", oauth2_scopes=None, security_source=get_security_from_env( self.sdk_configuration.security, components.Security ), ), request=req, error_status_codes=["4XX", "500", "5XX"], retry_config=retry_config, ) response_data: Any = None if utils.match_response(http_res, "200", "application/json"): return unmarshal_json_response(components.ImageModelsListResponse, http_res) if utils.match_response(http_res, "500", "application/json"): response_data = unmarshal_json_response( errors.InternalServerResponseErrorData, http_res ) raise errors.InternalServerResponseError(response_data, http_res) 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 ) raise errors.OpenRouterDefaultError("Unexpected response received", http_res) async def list_models_async( self, *, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: 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.ImageModelsListResponse: r"""List image generation models Lists every image generation model with its top-level supported-parameter superset and a URL to its full per-endpoint records. :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 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.ListImageModelsRequest( http_referer=http_referer, x_open_router_title=x_open_router_title, x_open_router_categories=x_open_router_categories, ) req = self._build_request_async( method="GET", path="/images/models", base_url=base_url, url_variables=url_variables, request=request, request_body_required=False, request_has_path_params=False, request_has_query_params=True, user_agent_header="user-agent", accept_header_value="application/json", http_headers=http_headers, _globals=operations.ListImageModelsGlobals( 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, 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="listImageModels", oauth2_scopes=None, security_source=get_security_from_env( self.sdk_configuration.security, components.Security ), ), request=req, error_status_codes=["4XX", "500", "5XX"], retry_config=retry_config, ) response_data: Any = None if utils.match_response(http_res, "200", "application/json"): return unmarshal_json_response(components.ImageModelsListResponse, http_res) if utils.match_response(http_res, "500", "application/json"): response_data = unmarshal_json_response( errors.InternalServerResponseErrorData, http_res ) raise errors.InternalServerResponseError(response_data, http_res) 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 ) raise errors.OpenRouterDefaultError("Unexpected response received", http_res) def list_model_endpoints( self, *, author: str, slug: str, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: 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.ImageModelEndpointsResponse: r"""List endpoints for an image model Returns the full per-endpoint records for an image model: each endpoint's definitive supported parameters, pricing, and passthrough allowlist. :param author: Model author/organization :param slug: Model slug :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 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.ListImageModelEndpointsRequest( http_referer=http_referer, x_open_router_title=x_open_router_title, x_open_router_categories=x_open_router_categories, author=author, slug=slug, ) req = self._build_request( method="GET", path="/images/models/{author}/{slug}/endpoints", base_url=base_url, url_variables=url_variables, request=request, request_body_required=False, request_has_path_params=True, request_has_query_params=True, user_agent_header="user-agent", accept_header_value="application/json", http_headers=http_headers, _globals=operations.ListImageModelEndpointsGlobals( 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, 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="listImageModelEndpoints", oauth2_scopes=None, security_source=get_security_from_env( self.sdk_configuration.security, components.Security ), ), request=req, error_status_codes=["404", "4XX", "500", "5XX"], retry_config=retry_config, ) response_data: Any = None if utils.match_response(http_res, "200", "application/json"): return unmarshal_json_response( components.ImageModelEndpointsResponse, http_res ) if utils.match_response(http_res, "404", "application/json"): response_data = unmarshal_json_response( errors.NotFoundResponseErrorData, http_res ) raise errors.NotFoundResponseError(response_data, http_res) if utils.match_response(http_res, "500", "application/json"): response_data = unmarshal_json_response( errors.InternalServerResponseErrorData, http_res ) raise errors.InternalServerResponseError(response_data, http_res) 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 ) raise errors.OpenRouterDefaultError("Unexpected response received", http_res) async def list_model_endpoints_async( self, *, author: str, slug: str, http_referer: Optional[str] = None, x_open_router_title: Optional[str] = None, x_open_router_categories: 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.ImageModelEndpointsResponse: r"""List endpoints for an image model Returns the full per-endpoint records for an image model: each endpoint's definitive supported parameters, pricing, and passthrough allowlist. :param author: Model author/organization :param slug: Model slug :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 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.ListImageModelEndpointsRequest( http_referer=http_referer, x_open_router_title=x_open_router_title, x_open_router_categories=x_open_router_categories, author=author, slug=slug, ) req = self._build_request_async( method="GET", path="/images/models/{author}/{slug}/endpoints", base_url=base_url, url_variables=url_variables, request=request, request_body_required=False, request_has_path_params=True, request_has_query_params=True, user_agent_header="user-agent", accept_header_value="application/json", http_headers=http_headers, _globals=operations.ListImageModelEndpointsGlobals( 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, 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="listImageModelEndpoints", oauth2_scopes=None, security_source=get_security_from_env( self.sdk_configuration.security, components.Security ), ), request=req, error_status_codes=["404", "4XX", "500", "5XX"], retry_config=retry_config, ) response_data: Any = None if utils.match_response(http_res, "200", "application/json"): return unmarshal_json_response( components.ImageModelEndpointsResponse, http_res ) if utils.match_response(http_res, "404", "application/json"): response_data = unmarshal_json_response( errors.NotFoundResponseErrorData, http_res ) raise errors.NotFoundResponseError(response_data, http_res) if utils.match_response(http_res, "500", "application/json"): response_data = unmarshal_json_response( errors.InternalServerResponseErrorData, http_res ) raise errors.InternalServerResponseError(response_data, http_res) 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 ) raise errors.OpenRouterDefaultError("Unexpected response received", http_res)