From 9754747a506c4bf84e716807fe7eb61a1eb6ea58 Mon Sep 17 00:00:00 2001 From: YAN Date: Wed, 9 Sep 2026 23:13:54 +0800 Subject: [PATCH] [Feat] OpenRouter: route image generation/edit to /api/v1/images OpenRouter serves most image models (openai/gpt-image-*, krea/*, bytedance-seed/*, ...) only through its dedicated `POST {api_base}/images` endpoint. Routing image generation and edit through `/chat/completions` instead -- the previous behavior of this provider -- either 500s outright or answers "No endpoints found that support the requested output modalities" for any model whose only output modality is image, since chat/completions never had image-only output at all. Hybrid text+image models (google/gemini-2.5-flash-image) happen to work either way, which is why this gap was easy to miss. This continues the approach in #34908, which is open but conflicting with main. It ports that PR's core idea -- extract a shared `litellm/llms/openrouter/image_api.py` module that owns the endpoint URL, the OpenAI-param -> OpenRouter-param translation (size -> aspect_ratio, response_format rejection since the endpoint only ever returns base64), and response parsing/usage-cost mapping, so image_generation and image_edit's transformation configs both become thin adapters over one tested code path -- and rebases it onto current main's typing style and the current `BaseImageEditConfig`/`BaseImageGenerationConfig` `validate_environment` signatures (which now take `litellm_params` and `api_base`). It adds one behavior not in #34908: `map_image_params` coerces the `n`/`output_compression`/`seed` scalar params to `int` before they reach OpenRouter. A caller invoking image generation with a JSON body already gets real ints, but a caller invoking image edit as multipart/form-data has every field arrive as a string (form fields have no native type), so an unconverted `n: "1"` reaches OpenRouter's `/api/v1/images` schema validator and 400s with an opaque "expected number, received string" -- this was only caught because we run both transports against the same route in production. The coercion rejects non-numeric and boolean values with a clear `UnsupportedParamsError` instead of forwarding a value OpenRouter would reject anyway. Response parsing and the `OpenRouterImagesResponse`/`OpenRouterImageUsage` pydantic models (litellm/types/llms/openrouter.py) validate the actual `/api/v1/images` response shape (data[].b64_json, usage.cost, usage.cost_details, usage.completion_tokens_details.image_tokens, usage.prompt_tokens_details.image_tokens for edit) rather than parsing a raw dict, so a shape change fails loudly in one place instead of silently producing an empty ImageResponse. Testing: - tests/test_litellm/llms/openrouter/image_edit/test_openrouter_image_edit_transformation.py and .../image_generation/test_openrouter_image_gen_transformation.py rewritten against the new endpoint and request/response shape, including the int-coercion cases; `pytest tests/test_litellm/llms/openrouter -k image` passes 111/111 locally. - `ruff check` and `ruff format --check` pass on all changed files. - Verified end-to-end against a production-scale LiteLLM 1.82.3-based gateway with a real OPENROUTER_API_KEY: both image generation and image edit against openai/gpt-image-2.5-flare return 200 with base64 image data, where they previously failed under the /chat/completions-only implementation. Co-Authored-By: Claude Fable 5.1 --- litellm/llms/openrouter/image_api.py | 280 ++++++ .../openrouter/image_edit/transformation.py | 323 ++----- .../image_generation/transformation.py | 360 ++----- litellm/types/llms/openrouter.py | 53 ++ ...st_openrouter_image_edit_transformation.py | 894 +++++++++--------- .../openrouter/image_generation/__init__.py | 0 ...est_openrouter_image_gen_transformation.py | 881 +++++++++-------- 7 files changed, 1333 insertions(+), 1458 deletions(-) create mode 100644 litellm/llms/openrouter/image_api.py create mode 100644 tests/test_litellm/llms/openrouter/image_generation/__init__.py diff --git a/litellm/llms/openrouter/image_api.py b/litellm/llms/openrouter/image_api.py new file mode 100644 index 00000000000..805ab064826 --- /dev/null +++ b/litellm/llms/openrouter/image_api.py @@ -0,0 +1,280 @@ +""" +Shared plumbing for OpenRouter's unified image API, ``POST {api_base}/images``. + +Both image_generation and image_edit configs (see the sibling ``image_generation/`` and +``image_edit/`` packages) map their OpenAI-shaped requests onto this one endpoint: +generation sends ``{model, prompt, ...}``, edit adds ``input_references`` carrying the +source image(s). This module is the single place that owns the URL, the OpenAI-param -> +OpenRouter-param translation, and the response parsing, so the two transformation configs +stay thin adapters instead of duplicating that logic (as the pre-images-API version did, +via chat/completions, before this port of upstream BerriAI/litellm#34908). + +Every OpenRouter image model is catalogued behind this endpoint, including models whose +only output modality is ``image`` (e.g. future `openai/gpt-image-2.5-flare` aliases) that +``/chat/completions`` cannot serve at all -- that gap is the reason this endpoint exists +as a distinct code path rather than a header-only URL swap on the chat transport. + +Response format: +{ + "created": 0, + "data": [{"b64_json": "iVBORw0KGgo...", "media_type": "image/png"}], + "usage": { + "prompt_tokens": 0, + "completion_tokens": 4175, + "total_tokens": 4175, + "cost": 0.06, + "completion_tokens_details": {"image_tokens": 4175}, + "cost_details": {"upstream_inference_cost": 0.06} + } +} +""" + +import re +from collections.abc import Mapping + +import httpx +from pydantic import ValidationError + +from litellm.exceptions import UnsupportedParamsError +from litellm.llms.openrouter.common_utils import OpenRouterException +from litellm.secret_managers.main import get_secret_str +from litellm.types.llms.openrouter import OpenRouterImagesResponse +from litellm.types.utils import ( + ImageObject, + ImageResponse, + ImageUsage, + ImageUsageInputTokensDetails, +) + +DEFAULT_OPENROUTER_API_BASE = "https://openrouter.ai/api/v1" + +# OpenRouter's image models only accept these aspect ratios; pixel sizes are mapped onto +# the closest one below rather than rejected, since most callers pass OpenAI-style sizes. +SUPPORTED_ASPECT_RATIOS: tuple[tuple[int, int], ...] = ( + (1, 1), + (2, 3), + (3, 2), + (3, 4), + (4, 3), + (4, 5), + (5, 4), + (9, 16), + (16, 9), + (21, 9), +) + +PIXEL_SIZE_PATTERN = re.compile(r"(\d+)x(\d+)") + +# Params consumed by the transformation layer itself (model/prompt are pulled out +# explicitly when building the request body; extra_headers never belongs in the body). +NON_BODY_PARAMS = frozenset({"model", "prompt", "extra_headers"}) + +# Per OpenRouter's /api/v1/images schema (openrouter.ai/docs/features/multimodal/image-generation), +# these are the only scalar params typed as integer; everything else that survives translation +# (size/quality/aspect_ratio/background/output_format/response_format) is a string and passes +# through untouched. Callers may invoke image generation with a JSON body (values already +# typed) and image edit with multipart/form-data (every field arrives as `str`) against the +# same route, so without this coercion the multipart path can send OpenRouter e.g. `n: "1"` +# and OpenRouter's Zod validator 400s with "expected number, received string" -- generation +# looked fine only because JSON already carries real ints. +INT_PARAMS = frozenset({"n", "output_compression", "seed"}) + + +def resolve_images_url(api_base: str | None) -> str: + """ + Build the OpenRouter images endpoint URL from a configured api_base. + + Called by both OpenRouterImageGenerationConfig.get_complete_url and + OpenRouterImageEditConfig.get_complete_url so the two request types always agree on + where the unified image API lives, and so an operator override of api_base (e.g. in + LiteLLM's DB-stored route config) doesn't need updating in two places. + """ + base_url = (api_base or get_secret_str("OPENROUTER_API_BASE") or DEFAULT_OPENROUTER_API_BASE).rstrip("/") + if base_url.endswith("/images"): + return base_url + return f"{base_url}/images" + + +def map_size_to_aspect_ratio(size: str) -> str | None: + """ + Map an OpenAI ``WxH`` size onto the closest aspect ratio OpenRouter accepts. + + Returns None for "auto" and for anything that isn't a recognizable pixel size, so the + model's own default aspect ratio applies instead of a guessed one -- guessing a ratio + for a value we can't parse would silently override a caller's intended default. + """ + match = PIXEL_SIZE_PATTERN.fullmatch(size.strip()) + if match is None: + return None + + width, height = int(match.group(1)), int(match.group(2)) + if width == 0 or height == 0: + return None + + target = width / height + closest = min(SUPPORTED_ASPECT_RATIOS, key=lambda ratio: abs(ratio[0] / ratio[1] - target)) + return f"{closest[0]}:{closest[1]}" + + +def map_image_params(params: Mapping[str, object], model: str, drop_params: bool) -> dict[str, object]: + """ + Translate OpenAI image params into OpenRouter's image API params. + + Shared by image_generation and image_edit's map_openai_params so "size" -> + "aspect_ratio" and the response_format rejection stay identical on both call paths -- + OpenRouter's image models don't accept pixel dimensions, and the endpoint always + returns base64 regardless of what the caller asked for. + """ + response_format = params.get("response_format") + if response_format is not None: + _reject_unsupported_response_format(value=str(response_format), model=model, drop_params=drop_params) + + mapped: dict[str, object] = {} + for key, value in params.items(): + new_key, new_value = _translate_param(key=key, value=value, model=model) + if new_key is not None: + mapped[new_key] = new_value + return mapped + + +def _translate_param(key: str, value: object, model: str) -> tuple[str | None, object]: + if key == "response_format": + return None, None + if key == "size": + aspect_ratio = map_size_to_aspect_ratio(str(value)) + return ("aspect_ratio", aspect_ratio) if aspect_ratio is not None else (None, None) + if key in INT_PARAMS and value is not None: + return key, _coerce_int_param(key=key, value=value, model=model) + return key, value + + +def _coerce_int_param(key: str, value: object, model: str) -> int: + """ + Normalize a scalar OpenRouter integer param regardless of caller transport. + + The JSON-bodied /v1/images/generations path already hands us a real int, but the + multipart-form /v1/images/edits path (FastAPI form fields have no native type) hands + us a `str` for every field including `n`. Coercing here -- once, for both call paths + -- means a caller-transport quirk can never surface as a raw provider 400; a value + that truly cannot be an int fails loudly and specifically instead of reaching + OpenRouter and coming back as an opaque Zod validation error. + """ + if isinstance(value, bool): + # bool is an int subclass in Python; reject it explicitly rather than silently + # sending 0/1 for a field where that would be a nonsensical image count/seed. + raise UnsupportedParamsError( + model=model, + llm_provider="openrouter", + message=f"OpenRouter's image API expects `{key}` to be an integer, got a boolean.", + ) + if isinstance(value, int): + return value + try: + return int(str(value).strip()) + except (TypeError, ValueError): + raise UnsupportedParamsError( + model=model, + llm_provider="openrouter", + message=( + f"OpenRouter's image API expects `{key}` to be an integer, got " + f"{value!r}. Pass a numeric value (e.g. `{key}=1`)." + ), + ) + + +def _reject_unsupported_response_format(value: str, model: str, drop_params: bool) -> None: + # OpenRouter's image API has no url-mode; only b64_json is ever returned. Fail loudly + # unless the caller opted into silently dropping unsupported params. + if value == "b64_json" or drop_params: + return + raise UnsupportedParamsError( + model=model, + llm_provider="openrouter", + message=( + "OpenRouter's image API always returns base64 image data, so " + f"response_format='{value}' is not supported. Request 'b64_json', or set " + "`drop_params: true` to ignore it." + ), + ) + + +def parse_images_response(raw_response: httpx.Response) -> OpenRouterImagesResponse: + """Validate the raw HTTP body against the typed OpenRouter images schema.""" + try: + return OpenRouterImagesResponse.model_validate(raw_response.json()) + except (ValueError, ValidationError) as e: + raise OpenRouterException( + message=f"Error parsing OpenRouter image response: {e!s}", + status_code=raw_response.status_code, + headers=raw_response.headers, + ) + + +def apply_images_response( + parsed: OpenRouterImagesResponse, + model_response: ImageResponse, + model: str, +) -> ImageResponse: + """ + Populate a litellm ImageResponse from a parsed OpenRouter images response. + + Called by both image_generation and image_edit's transform_*_response so usage/cost + bookkeeping (spend-log accuracy) stays in one place instead of being copy-pasted per + request type. + """ + model_response.data = [ + ImageObject( + b64_json=image.b64_json, + url=image.url, + revised_prompt=image.revised_prompt, + ) + for image in parsed.data + ] + + if parsed.created: + model_response.created = parsed.created + + _set_usage_and_cost(model_response=model_response, parsed=parsed, model=model) + + return model_response + + +def _set_usage_and_cost( + model_response: ImageResponse, + parsed: OpenRouterImagesResponse, + model: str, +) -> None: + if not hasattr(model_response, "_hidden_params") or model_response._hidden_params is None: + model_response._hidden_params = {} + model_response._hidden_params["model"] = parsed.model or model + + usage = parsed.usage + if usage is None: + return + + image_tokens = usage.completion_tokens_details.image_tokens if usage.completion_tokens_details else None + input_image_tokens = (usage.prompt_tokens_details.image_tokens or 0) if usage.prompt_tokens_details else 0 + model_response.usage = ImageUsage( + input_tokens=usage.prompt_tokens, + input_tokens_details=ImageUsageInputTokensDetails( + image_tokens=input_image_tokens, + text_tokens=usage.prompt_tokens - input_image_tokens, + ), + output_tokens=image_tokens if image_tokens is not None else usage.completion_tokens, + total_tokens=usage.total_tokens, + ) + + # Feed the upstream-reported cost straight into the spend-log path via the same + # hidden-header convention the rest of the OpenRouter configs use, so settlement + # prefers OpenRouter's real cost over litellm's static price table when both are + # present. + if usage.cost is not None: + additional_headers = dict(model_response._hidden_params.get("additional_headers") or {}) + additional_headers["llm_provider-x-litellm-response-cost"] = usage.cost + model_response._hidden_params["additional_headers"] = additional_headers + + if usage.cost_details: + model_response._hidden_params["response_cost_details"] = { + **(model_response._hidden_params.get("response_cost_details") or {}), + **usage.cost_details, + } diff --git a/litellm/llms/openrouter/image_edit/transformation.py b/litellm/llms/openrouter/image_edit/transformation.py index b01c25aad0c..32fd85d59eb 100644 --- a/litellm/llms/openrouter/image_edit/transformation.py +++ b/litellm/llms/openrouter/image_edit/transformation.py @@ -1,48 +1,33 @@ """ OpenRouter Image Edit Support -OpenRouter provides image editing through chat completion endpoints. -The source image is sent as a base64 data URL in the message content, -and the response contains edited images in the message's images array. +OpenRouter edits images through the same endpoint it generates them from, +``POST https://openrouter.ai/api/v1/images``. The source image travels in +``input_references`` as a base64 data URL. Models whose only output modality is ``image`` +(``openai/gpt-image-*``, ``bytedance-seed/*``, ...) are reachable only there, and asking +``/chat/completions`` for ``modalities: ["image", "text"]`` on one of them answers with +"No endpoints found that support the requested output modalities". This mirrors the +approach in upstream BerriAI/litellm#34908; the previous version of this file drove edits +through chat completions' image_url content blocks instead, which is why edit-capable +gpt-image-* aliases could not be reached before this change. Request format: { - "model": "google/gemini-2.5-flash-image", - "messages": [{ - "role": "user", - "content": [ - {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}, - {"type": "text", "text": "Edit this image by..."} - ] - }], - "modalities": ["image", "text"] + "model": "openai/gpt-image-2", + "prompt": "Add a sunset behind the mountain", + "input_references": [ + {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}} + ], + "aspect_ratio": "1:1" } -Response format: -{ - "choices": [{ - "message": { - "content": "Here is the edited image.", - "role": "assistant", - "images": [{ - "image_url": {"url": "data:image/png;base64,..."}, - "type": "image_url" - }] - } - }], - "usage": { - "completion_tokens": 1299, - "prompt_tokens": 300, - "total_tokens": 1599, - "completion_tokens_details": {"image_tokens": 1290}, - "cost": 0.0387243 - } -} +See ``litellm/llms/openrouter/image_api.py`` for the response format and the parameter +mapping shared with image generation. """ import base64 from io import BufferedReader, BytesIO -from typing import TYPE_CHECKING, Any, Final, cast +from typing import TYPE_CHECKING, Any, cast import httpx from httpx._types import RequestFiles @@ -52,16 +37,17 @@ from litellm.images.utils import ImageEditRequestUtils from litellm.llms.base_llm.chat.transformation import BaseLLMException from litellm.llms.base_llm.image_edit.transformation import BaseImageEditConfig from litellm.llms.openrouter.common_utils import OpenRouterException +from litellm.llms.openrouter.image_api import ( + NON_BODY_PARAMS, + apply_images_response, + map_image_params, + parse_images_response, + resolve_images_url, +) from litellm.secret_managers.main import get_secret_str from litellm.types.images.main import ImageEditOptionalRequestParams from litellm.types.router import GenericLiteLLMParams -from litellm.types.utils import ( - FileTypes, - ImageObject, - ImageResponse, - ImageUsage, - ImageUsageInputTokensDetails, -) +from litellm.types.utils import FileTypes, ImageResponse if TYPE_CHECKING: from litellm.litellm_core_utils.litellm_logging import Logging as _LiteLLMLoggingObj @@ -72,16 +58,10 @@ else: class OpenRouterImageEditConfig(BaseImageEditConfig): - """ - Configuration for OpenRouter image editing via chat completions. - - OpenRouter uses the chat completions endpoint for image editing. - The source image is sent as a base64 data URL in the message content, - and the response contains edited images in the message's images array. - """ + """Maps ``/v1/images/edits`` onto OpenRouter's ``/api/v1/images`` endpoint.""" def get_supported_openai_params(self, model: str) -> list: - return ["size", "quality", "n"] + return ["background", "n", "quality", "response_format", "size"] def map_openai_params( self, @@ -89,25 +69,10 @@ class OpenRouterImageEditConfig(BaseImageEditConfig): model: str, drop_params: bool, ) -> dict: - supported_params: Final = self.get_supported_openai_params(model) - mapped_params: Final[dict[str, Any]] = {} - - for key, value in image_edit_optional_params.items(): - if key in supported_params: - if key == "size": - if "image_config" not in mapped_params: - mapped_params["image_config"] = {} - mapped_params["image_config"]["aspect_ratio"] = self._map_size_to_aspect_ratio(cast(str, value)) - elif key == "quality": - image_size = self._map_quality_to_image_size(cast(str, value)) - if image_size: - if "image_config" not in mapped_params: - mapped_params["image_config"] = {} - mapped_params["image_config"]["image_size"] = image_size - else: - mapped_params[key] = value - - return mapped_params + # Same size/response_format translation as image generation, factored into + # image_api so both request types can never drift on how "size" maps to + # "aspect_ratio". + return map_image_params(params=image_edit_optional_params, model=model, drop_params=drop_params) def validate_environment( self, @@ -117,18 +82,18 @@ class OpenRouterImageEditConfig(BaseImageEditConfig): litellm_params: dict | None = None, api_base: str | None = None, ) -> dict: - api_key = api_key or litellm.api_key or get_secret_str("OPENROUTER_API_KEY") - if not api_key: + resolved_api_key = api_key or litellm.api_key or get_secret_str("OPENROUTER_API_KEY") + if not resolved_api_key: raise ValueError("OPENROUTER_API_KEY is not set") headers.update( { - "Authorization": f"Bearer {api_key}", + "Authorization": f"Bearer {resolved_api_key}", } ) return headers def use_multipart_form_data(self) -> bool: - """OpenRouter uses JSON requests, not multipart/form-data.""" + """OpenRouter's image API takes JSON, not multipart/form-data.""" return False def get_complete_url( @@ -137,11 +102,7 @@ class OpenRouterImageEditConfig(BaseImageEditConfig): api_base: str | None, litellm_params: dict, ) -> str: - base_url = api_base or get_secret_str("OPENROUTER_API_BASE") or "https://openrouter.ai/api/v1" - base_url = base_url.rstrip("/") - if not base_url.endswith("/chat/completions"): - return f"{base_url}/chat/completions" - return base_url + return resolve_images_url(api_base) def transform_image_edit_request( self, @@ -152,45 +113,28 @@ class OpenRouterImageEditConfig(BaseImageEditConfig): litellm_params: GenericLiteLLMParams, headers: dict, ) -> tuple[dict, RequestFiles]: - content_parts: Final[list[dict[str, object]]] = [] + """ + Build the ``/images`` edit request: source image(s) as ``input_references``. - # Add source image(s) as base64 data URLs - if image is not None: - images: Final = image if isinstance(image, list) else [image] - for img in images: - if img is None: - continue - mime_type = ImageEditRequestUtils.get_image_content_type(img) - image_bytes = self._read_image_bytes(img) - b64_data = base64.b64encode(image_bytes).decode("utf-8") - content_parts.append( - { - "type": "image_url", - "image_url": {"url": f"data:{mime_type};base64,{b64_data}"}, - } - ) + OpenRouter has no image-less edit mode (unlike some OpenAI-style edit APIs that + accept a mask-only request), so we fail fast here rather than sending a request + that would otherwise 400 further downstream with a less actionable message. + """ + images = [img for img in (image if isinstance(image, list) else [image]) if img is not None] + if not images: + raise ValueError("An image is required to edit; OpenRouter has no image-less edit mode.") - # Add the text prompt - if prompt: - content_parts.append({"type": "text", "text": prompt}) - - request_body: Final[dict[str, object]] = { + request_body: dict[str, Any] = { "model": model, - "messages": [ - { - "role": "user", - "content": content_parts, - } - ], - "modalities": ["image", "text"], } - - # Add mapped optional params (image_config, n, etc.) + if prompt is not None: + request_body["prompt"] = prompt for key, value in image_edit_optional_request_params.items(): - if key not in ("model", "messages", "modalities"): + if key not in NON_BODY_PARAMS: request_body[key] = value + request_body["input_references"] = [self._input_reference(img) for img in images] - empty_files: Final = cast(RequestFiles, []) + empty_files = cast(RequestFiles, []) return request_body, empty_files def transform_image_edit_response( @@ -199,60 +143,13 @@ class OpenRouterImageEditConfig(BaseImageEditConfig): raw_response: httpx.Response, logging_obj: LiteLLMLoggingObj, ) -> ImageResponse: - try: - response_json: Final = raw_response.json() - except Exception as e: - raise OpenRouterException( - message=f"Error parsing OpenRouter response: {e}", - status_code=raw_response.status_code, - headers=raw_response.headers, - ) - - model_response: Final = ImageResponse() - model_response.data = [] - - try: - choices: Final = response_json.get("choices", []) - - for choice in choices: - message = choice.get("message", {}) - images = message.get("images", []) - - for image_data in images: - image_url_obj = image_data.get("image_url", {}) - image_url = image_url_obj.get("url") - - if image_url: - if image_url.startswith("data:"): - # Extract base64 data from data URL - parts = image_url.split(",", 1) - b64_data = parts[1] if len(parts) > 1 else None - - model_response.data.append( - ImageObject( - b64_json=b64_data, - url=None, - revised_prompt=None, - ) - ) - else: - model_response.data.append( - ImageObject( - b64_json=None, - url=image_url, - revised_prompt=None, - ) - ) - - except Exception as e: - raise OpenRouterException( - message=f"Error transforming OpenRouter image edit response: {e}", - status_code=500, - headers={}, - ) - - self._set_usage_and_cost(model_response, response_json, model) - return model_response + # Parsing/usage-mapping is shared with image_generation via image_api so a fix to + # cost or usage extraction only needs to happen once. + return apply_images_response( + parsed=parse_images_response(raw_response), + model_response=ImageResponse(), + model=model, + ) def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException: return OpenRouterException( @@ -261,104 +158,20 @@ class OpenRouterImageEditConfig(BaseImageEditConfig): headers=headers, ) - # Private helper methods - - def _map_size_to_aspect_ratio(self, size: str) -> str: - """ - Map OpenAI size format to OpenRouter aspect_ratio format. - - Uses the same mapping as image generation since OpenRouter - handles both through the same chat completions endpoint. - """ - size_to_aspect_ratio: Final = { - "256x256": "1:1", - "512x512": "1:1", - "1024x1024": "1:1", - "1536x1024": "3:2", - "1792x1024": "16:9", - "1024x1536": "2:3", - "1024x1792": "9:16", - "auto": "1:1", + def _input_reference(self, image: FileTypes) -> dict: + """Encode one source image as an ``input_references`` entry (base64 data URL).""" + mime_type = ImageEditRequestUtils.get_image_content_type(image) + b64_data = base64.b64encode(self._read_image_bytes(image)).decode("utf-8") + return { + "type": "image_url", + "image_url": {"url": f"data:{mime_type};base64,{b64_data}"}, } - return size_to_aspect_ratio.get(size, "1:1") - - def _map_quality_to_image_size(self, quality: str) -> str | None: - """ - Map OpenAI quality to OpenRouter image_size format. - - Uses the same mapping as image generation since OpenRouter - handles both through the same chat completions endpoint. - """ - quality_to_image_size: Final = { - "low": "1K", - "standard": "1K", - "medium": "2K", - "high": "4K", - "hd": "4K", - "auto": "1K", - } - return quality_to_image_size.get(quality) - - def _set_usage_and_cost( - self, - model_response: ImageResponse, - response_json: dict, - model: str, - ) -> None: - """Extract and set usage and cost information from OpenRouter response.""" - usage_data: Final = response_json.get("usage", {}) - if usage_data: - prompt_tokens: Final = usage_data.get("prompt_tokens", 0) - total_tokens: Final = usage_data.get("total_tokens", 0) - - completion_tokens_details: Final = usage_data.get("completion_tokens_details", {}) - image_tokens: Final = completion_tokens_details.get("image_tokens", 0) - - # For image edit, input may include image tokens - input_image_tokens = 0 - prompt_tokens_details: Final = usage_data.get("prompt_tokens_details", {}) - if prompt_tokens_details: - input_image_tokens = prompt_tokens_details.get("image_tokens", 0) - - model_response.usage = ImageUsage( - input_tokens=prompt_tokens, - input_tokens_details=ImageUsageInputTokensDetails( - image_tokens=input_image_tokens, - text_tokens=prompt_tokens - input_image_tokens, - ), - output_tokens=image_tokens, - total_tokens=total_tokens, - ) - - cost: Final = usage_data.get("cost") - if cost is not None: - if not hasattr(model_response, "_hidden_params"): - model_response._hidden_params = {} - if "additional_headers" not in model_response._hidden_params: - model_response._hidden_params["additional_headers"] = {} - model_response._hidden_params["additional_headers"]["llm_provider-x-litellm-response-cost"] = float( - cost - ) - - cost_details: Final = usage_data.get("cost_details", {}) - if cost_details: - if "response_cost_details" not in model_response._hidden_params: - model_response._hidden_params["response_cost_details"] = {} - model_response._hidden_params["response_cost_details"].update(cost_details) - - model_response._hidden_params["model"] = response_json.get("model", model) def _read_image_bytes(self, image: FileTypes) -> bytes: - """Read raw bytes from various image input types.""" + """Read raw bytes from various image input types without consuming the stream position.""" if isinstance(image, bytes): return image - if isinstance(image, BytesIO): - current_pos = image.tell() - image.seek(0) - data = image.read() - image.seek(current_pos) - return data - if isinstance(image, BufferedReader): + if isinstance(image, (BytesIO, BufferedReader)): current_pos = image.tell() image.seek(0) data = image.read() diff --git a/litellm/llms/openrouter/image_generation/transformation.py b/litellm/llms/openrouter/image_generation/transformation.py index 6bbda324336..b188bcad3c0 100644 --- a/litellm/llms/openrouter/image_generation/transformation.py +++ b/litellm/llms/openrouter/image_generation/transformation.py @@ -1,33 +1,31 @@ """ OpenRouter Image Generation Support -OpenRouter provides image generation through chat completion endpoints. -Models like google/gemini-2.5-flash-image return images in the message content. +OpenRouter serves image generation from a dedicated endpoint, +``POST https://openrouter.ai/api/v1/images``. Models whose only output modality is +``image`` (``krea/*``, ``openai/gpt-image-*``, ``bytedance-seed/*``, ...) are reachable +*only* there -- sending them to ``/chat/completions`` answers with an opaque HTTP 500. +Hybrid text+image models such as ``google/gemini-2.5-flash-image`` are served from both, +so this config routes every OpenRouter image generation call through ``/images`` rather +than picking per-model, keeping one code path for all of them. This continues the +approach in upstream BerriAI/litellm#34908; the previous version of this file drove image +generation through ``/chat/completions`` instead, which meant models whose only output +modality is image (e.g. ``openai/gpt-image-2.5-flare``) could never resolve, since that +kind of model has no chat-completions image output at all. -Response format: +Request format: { - "choices": [{ - "message": { - "content": "Here is a beautiful sunset for you! ", - "role": "assistant", - "images": [{ - "image_url": {"url": "data:image/png;base64,..."}, - "index": 0, - "type": "image_url" - }] - } - }], - "usage": { - "completion_tokens": 1299, - "prompt_tokens": 6, - "total_tokens": 1305, - "completion_tokens_details": {"image_tokens": 1290}, - "cost": 0.0387243 - } + "model": "krea/krea-2-large", + "prompt": "a red panda astronaut floating in space", + "n": 1, + "aspect_ratio": "1:1" } + +See ``litellm/llms/openrouter/image_api.py`` for the response format and the parameter +mapping shared with image edit. """ -from typing import TYPE_CHECKING, Any, Final +from typing import TYPE_CHECKING, Any import httpx @@ -37,47 +35,31 @@ from litellm.llms.base_llm.image_generation.transformation import ( BaseImageGenerationConfig, ) from litellm.llms.openrouter.common_utils import OpenRouterException +from litellm.llms.openrouter.image_api import ( + NON_BODY_PARAMS, + apply_images_response, + map_image_params, + parse_images_response, + resolve_images_url, +) from litellm.secret_managers.main import get_secret_str from litellm.types.llms.openai import ( AllMessageValues, OpenAIImageGenerationOptionalParams, ) -from litellm.types.utils import ( - ImageObject, - ImageResponse, - ImageUsage, - ImageUsageInputTokensDetails, -) +from litellm.types.utils import ImageResponse if TYPE_CHECKING: - import tiktoken - from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj else: LiteLLMLoggingObj = Any class OpenRouterImageGenerationConfig(BaseImageGenerationConfig): - """ - Configuration for OpenRouter image generation via chat completions. - - OpenRouter uses chat completion endpoints for image generation, - so we need to transform image generation requests to chat format - and extract images from chat responses. - """ + """Maps ``/v1/images/generations`` onto OpenRouter's ``/api/v1/images`` endpoint.""" def get_supported_openai_params(self, model: str) -> list[OpenAIImageGenerationOptionalParams]: - """ - Get supported OpenAI parameters for OpenRouter image generation. - - Since OpenRouter uses chat completions for image generation, - we support standard image generation params. - """ - return [ - "size", - "quality", - "n", - ] + return ["n", "quality", "response_format", "size"] def map_openai_params( self, @@ -87,154 +69,17 @@ class OpenRouterImageGenerationConfig(BaseImageGenerationConfig): drop_params: bool, ) -> dict: """ - Map image generation params to OpenRouter chat completion format. + Map OpenAI image generation params onto OpenRouter's image API shape. - Maps OpenAI parameters to OpenRouter's image_config format: - - size -> image_config.aspect_ratio - - quality -> image_config.image_size + Delegates the size -> aspect_ratio conversion and response_format handling to + image_api.map_image_params so image_edit's map_openai_params stays byte-identical + in behavior; only the surrounding dict-merge shape differs because the two base + configs pass params in slightly different argument shapes. """ - supported_params: Final = self.get_supported_openai_params(model) - - for key, value in non_default_params.items(): - if key in supported_params: - if key == "size": - # Map OpenAI size to OpenRouter aspect_ratio - aspect_ratio = self._map_size_to_aspect_ratio(value) - if "image_config" not in optional_params: - optional_params["image_config"] = {} - optional_params["image_config"]["aspect_ratio"] = aspect_ratio - elif key == "quality": - # Map OpenAI quality to OpenRouter image_size - image_size = self._map_quality_to_image_size(value) - if image_size: - if "image_config" not in optional_params: - optional_params["image_config"] = {} - optional_params["image_config"]["image_size"] = image_size - else: - # Pass through other supported params (like n) - optional_params[key] = value - elif not drop_params: - # If not supported and drop_params is False, pass through - optional_params[key] = value - - return optional_params - - def _map_size_to_aspect_ratio(self, size: str) -> str: - """ - Map OpenAI size format to OpenRouter aspect_ratio format. - - OpenAI sizes: - - 1024x1024 (square) - - 1536x1024 (landscape) - - 1024x1536 (portrait) - - 1792x1024 (wide landscape, dall-e-3) - - 1024x1792 (tall portrait, dall-e-3) - - 256x256, 512x512 (dall-e-2) - - auto (default) - - OpenRouter aspect_ratios: - - 1:1 → 1024×1024 (default) - - 2:3 → 832×1248 - - 3:2 → 1248×832 - - 3:4 → 864×1184 - - 4:3 → 1184×864 - - 4:5 → 896×1152 - - 5:4 → 1152×896 - - 9:16 → 768×1344 - - 16:9 → 1344×768 - - 21:9 → 1536×672 - """ - size_to_aspect_ratio: Final = { - # Square formats - "256x256": "1:1", - "512x512": "1:1", - "1024x1024": "1:1", - # Landscape formats - "1536x1024": "3:2", # 1.5:1 ratio, closest to 3:2 - "1792x1024": "16:9", # 1.75:1 ratio, closest to 16:9 - # Portrait formats - "1024x1536": "2:3", # 0.67:1 ratio, closest to 2:3 - "1024x1792": "9:16", # 0.57:1 ratio, closest to 9:16 - # Default - "auto": "1:1", + return { + **optional_params, + **map_image_params(params=non_default_params, model=model, drop_params=drop_params), } - return size_to_aspect_ratio.get(size, "1:1") - - def _map_quality_to_image_size(self, quality: str) -> str | None: - """ - Map OpenAI quality to OpenRouter image_size format. - - OpenAI quality values: - - auto (default) - automatically select best quality - - high, medium, low - for GPT image models - - hd, standard - for dall-e-3 - - OpenRouter image_size values (Gemini only): - - 1K → Standard resolution (default) - - 2K → Higher resolution - - 4K → Highest resolution - """ - quality_to_image_size: Final = { - # OpenAI quality mappings - "low": "1K", - "standard": "1K", - "medium": "2K", - "high": "4K", - "hd": "4K", - # Auto defaults to standard - "auto": "1K", - } - return quality_to_image_size.get(quality) - - def _set_usage_and_cost( - self, - model_response: ImageResponse, - response_json: dict, - model: str, - ) -> None: - """ - Extract and set usage and cost information from OpenRouter response. - - Args: - model_response: ImageResponse object to populate - response_json: Parsed JSON response from OpenRouter - model: The model name - """ - usage_data: Final = response_json.get("usage", {}) - if usage_data: - prompt_tokens: Final = usage_data.get("prompt_tokens", 0) - total_tokens: Final = usage_data.get("total_tokens", 0) - - completion_tokens_details: Final = usage_data.get("completion_tokens_details", {}) - image_tokens: Final = completion_tokens_details.get("image_tokens", 0) - - model_response.usage = ImageUsage( - input_tokens=prompt_tokens, - input_tokens_details=ImageUsageInputTokensDetails( - image_tokens=0, # Input doesn't contain images for generation - text_tokens=prompt_tokens, - ), - output_tokens=image_tokens, - total_tokens=total_tokens, - ) - - cost: Final = usage_data.get("cost") - if cost is not None: - if not hasattr(model_response, "_hidden_params"): - model_response._hidden_params = {} - if "additional_headers" not in model_response._hidden_params: - model_response._hidden_params["additional_headers"] = {} - model_response._hidden_params["additional_headers"]["llm_provider-x-litellm-response-cost"] = float( - cost - ) - - cost_details: Final = usage_data.get("cost_details", {}) - if cost_details: - if "response_cost_details" not in model_response._hidden_params: - model_response._hidden_params["response_cost_details"] = {} - model_response._hidden_params["response_cost_details"].update(cost_details) - - model_response._hidden_params["model"] = response_json.get("model", model) def get_complete_url( self, @@ -245,19 +90,7 @@ class OpenRouterImageGenerationConfig(BaseImageGenerationConfig): litellm_params: dict, stream: bool | None = None, ) -> str: - """ - Get the complete URL for OpenRouter image generation. - - OpenRouter uses chat completions endpoint for image generation. - Default: https://openrouter.ai/api/v1/chat/completions - """ - if api_base: - if not api_base.endswith("/chat/completions"): - api_base = api_base.rstrip("/") - return f"{api_base}/chat/completions" - return api_base - - return "https://openrouter.ai/api/v1/chat/completions" + return resolve_images_url(api_base) def validate_environment( self, @@ -269,10 +102,10 @@ class OpenRouterImageGenerationConfig(BaseImageGenerationConfig): api_key: str | None = None, api_base: str | None = None, ) -> dict: - api_key = api_key or litellm.api_key or get_secret_str("OPENROUTER_API_KEY") + resolved_api_key = api_key or litellm.api_key or get_secret_str("OPENROUTER_API_KEY") headers.update( { - "Authorization": f"Bearer {api_key}", + "Authorization": f"Bearer {resolved_api_key}", } ) return headers @@ -286,30 +119,17 @@ class OpenRouterImageGenerationConfig(BaseImageGenerationConfig): headers: dict, ) -> dict: """ - Transform image generation request to OpenRouter chat completion format. + Build the ``/images`` request body: ``{model, prompt, ...mapped optional params}``. - Args: - model: The model name - prompt: The image generation prompt - optional_params: Optional parameters (including image_config) - litellm_params: LiteLLM parameters - headers: Request headers - - Returns: - dict: Request body in chat completion format with image_config + NON_BODY_PARAMS is excluded because "model" and "prompt" are already set + explicitly above and "extra_headers" belongs on the transport, not the JSON body. """ - request_body: Final = { + return { "model": model, - "messages": [{"role": "user", "content": prompt}], + "prompt": prompt, + **{key: value for key, value in optional_params.items() if key not in NON_BODY_PARAMS}, } - # These will be passed through to OpenRouter - for key, value in optional_params.items(): - if key not in ["model", "messages", "modalities"]: - request_body[key] = value - - return request_body - def transform_image_generation_response( self, model: str, @@ -319,87 +139,17 @@ class OpenRouterImageGenerationConfig(BaseImageGenerationConfig): request_data: dict, optional_params: dict, litellm_params: dict, - encoding: "tiktoken.Encoding | None", + encoding: Any, api_key: str | None = None, json_mode: bool | None = None, ) -> ImageResponse: - """ - Transform OpenRouter chat completion response to ImageResponse format. - - Extracts images from the message content and maps usage/cost information. - - Args: - model: The model name - raw_response: Raw HTTP response from OpenRouter - model_response: ImageResponse object to populate - logging_obj: Logging object - request_data: Original request data - optional_params: Optional parameters - litellm_params: LiteLLM parameters - encoding: Encoding - api_key: API key - json_mode: JSON mode flag - - Returns: - ImageResponse: Populated image response - """ - try: - response_json: Final = raw_response.json() - except Exception as e: - raise OpenRouterException( - message=f"Error parsing OpenRouter response: {e}", - status_code=raw_response.status_code, - headers=raw_response.headers, - ) - - if not model_response.data: - model_response.data = [] - - try: - choices: Final = response_json.get("choices", []) - - for choice in choices: - message = choice.get("message", {}) - images = message.get("images", []) - - for image_data in images: - image_url_obj = image_data.get("image_url", {}) - image_url = image_url_obj.get("url") - - if image_url: - if image_url.startswith("data:"): - # Extract base64 data - # Format: data:image/png;base64, - parts = image_url.split(",", 1) - b64_data = parts[1] if len(parts) > 1 else None - - model_response.data.append( - ImageObject( - b64_json=b64_data, - url=None, - revised_prompt=None, - ) - ) - else: - model_response.data.append( - ImageObject( - b64_json=None, - url=image_url, - revised_prompt=None, - ) - ) - - # Extract and set usage and cost information - self._set_usage_and_cost(model_response, response_json, model) - - return model_response - - except Exception as e: - raise OpenRouterException( - message=f"Error transforming OpenRouter image generation response: {e}", - status_code=500, - headers={}, - ) + # Parsing/usage-mapping is shared with image_edit via image_api so a fix to cost + # or usage extraction only needs to happen once. + return apply_images_response( + parsed=parse_images_response(raw_response), + model_response=model_response, + model=model, + ) def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException: """Get the appropriate error class for OpenRouter errors.""" diff --git a/litellm/types/llms/openrouter.py b/litellm/types/llms/openrouter.py index 1558ff576b5..45a42f1c286 100644 --- a/litellm/types/llms/openrouter.py +++ b/litellm/types/llms/openrouter.py @@ -1,3 +1,6 @@ +from collections.abc import Mapping + +from pydantic import BaseModel from typing_extensions import TypedDict @@ -5,3 +8,53 @@ class OpenRouterErrorMessage(TypedDict): message: str code: int metadata: dict + + +class OpenRouterImageCompletionTokensDetails(BaseModel): + """``usage.completion_tokens_details`` on ``POST /api/v1/images`` responses.""" + + image_tokens: int | None = None + reasoning_tokens: int | None = None + + +class OpenRouterImagePromptTokensDetails(BaseModel): + """``usage.prompt_tokens_details`` on ``POST /api/v1/images`` responses (image edit only).""" + + image_tokens: int | None = None + text_tokens: int | None = None + + +class OpenRouterImageUsage(BaseModel): + """Usage block of the OpenRouter unified image API response, incl. real cost for spend-log settlement.""" + + prompt_tokens: int = 0 + completion_tokens: int = 0 + total_tokens: int = 0 + cost: float | None = None + cost_details: Mapping[str, float | None] | None = None + completion_tokens_details: OpenRouterImageCompletionTokensDetails | None = None + prompt_tokens_details: OpenRouterImagePromptTokensDetails | None = None + + +class OpenRouterImageData(BaseModel): + """One image entry in ``data[]``; OpenRouter always returns base64, never a bare URL, but both fields are modeled defensively.""" + + b64_json: str | None = None + url: str | None = None + media_type: str | None = None + revised_prompt: str | None = None + + +class OpenRouterImagesResponse(BaseModel): + """ + Response body of ``POST https://openrouter.ai/api/v1/images``. + + Used by litellm/llms/openrouter/image_api.py to validate and parse both image + generation and image edit responses, since both request types answer through this + same endpoint and payload shape. + """ + + data: tuple[OpenRouterImageData, ...] + created: int | None = None + model: str | None = None + usage: OpenRouterImageUsage | None = None diff --git a/tests/test_litellm/llms/openrouter/image_edit/test_openrouter_image_edit_transformation.py b/tests/test_litellm/llms/openrouter/image_edit/test_openrouter_image_edit_transformation.py index 5a78560f61b..5d0e6077190 100644 --- a/tests/test_litellm/llms/openrouter/image_edit/test_openrouter_image_edit_transformation.py +++ b/tests/test_litellm/llms/openrouter/image_edit/test_openrouter_image_edit_transformation.py @@ -1,533 +1,457 @@ import base64 import json +import os +import sys from io import BytesIO -from unittest.mock import MagicMock, patch import httpx import pytest +sys.path.insert(0, os.path.abspath("../../../../..")) # Adds the parent directory to the system path +import litellm +from litellm.images.utils import ImageEditRequestUtils +from litellm.llms.custom_httpx.http_handler import HTTPHandler from litellm.llms.openrouter.common_utils import OpenRouterException -from litellm.llms.openrouter.image_edit.transformation import ( - OpenRouterImageEditConfig, -) +from litellm.llms.openrouter.image_edit.transformation import OpenRouterImageEditConfig from litellm.types.router import GenericLiteLLMParams -from litellm.types.utils import ImageResponse + +# Verbatim shape of a `POST https://openrouter.ai/api/v1/images` response. +OPENROUTER_IMAGES_RESPONSE = { + "created": 0, + "data": [{"b64_json": "iVBORw0KGgoAAAANS", "media_type": "image/png"}], + "usage": { + "prompt_tokens": 300, + "completion_tokens": 1299, + "total_tokens": 1599, + "cost": 0.05, + "is_byok": False, + "prompt_tokens_details": {"image_tokens": 258, "cached_tokens": 0}, + "cost_details": {"upstream_inference_cost": 0.05}, + "completion_tokens_details": {"reasoning_tokens": 0, "image_tokens": 1290}, + }, +} + +PNG_BYTES = b"\x89PNG\r\n\x1a\n" + b"\x00" * 100 -class TestOpenRouterImageEditTransformation: +class RequestRecorder: + """httpx.MockTransport handler that keeps the request it was called with.""" + + def __init__(self, response_payload: dict, status_code: int = 200): + self.response_payload = response_payload + self.status_code = status_code + self.request: httpx.Request | None = None + + def __call__(self, request: httpx.Request) -> httpx.Response: + self.request = request + return httpx.Response(status_code=self.status_code, json=self.response_payload) + + def body(self) -> dict: + assert self.request is not None, "no request was sent" + return json.loads(self.request.content) + + +def make_client(recorder: RequestRecorder) -> HTTPHandler: + return HTTPHandler(client=httpx.Client(transport=httpx.MockTransport(recorder))) + + +def make_httpx_response(payload: object, status_code: int = 200) -> httpx.Response: + return httpx.Response( + status_code=status_code, + json=payload, + request=httpx.Request(method="POST", url="https://openrouter.ai/api/v1/images"), + ) + + +class TestOpenRouterImageEditEndpoint: + """OpenRouter edits images from /api/v1/images, never /chat/completions.""" + def setup_method(self): - """Set up test fixtures before each test method.""" self.config = OpenRouterImageEditConfig() - self.model = "google/gemini-2.5-flash-image" - self.logging_obj = MagicMock() - self.sample_image_bytes = b"\x89PNG\r\n\x1a\n" + b"\x00" * 100 + self.model = "openai/gpt-image-2" - def test_get_supported_openai_params(self): - """Test that get_supported_openai_params returns correct parameters.""" - supported_params = self.config.get_supported_openai_params(self.model) + def test_get_complete_url_appends_images_path(self): + result = self.config.get_complete_url( + model=self.model, + api_base="https://openrouter.ai/api/v1", + litellm_params={}, + ) - assert "size" in supported_params - assert "quality" in supported_params - assert "n" in supported_params - assert len(supported_params) == 3 + assert result == "https://openrouter.ai/api/v1/images" - def test_use_multipart_form_data_returns_false(self): - """Test that OpenRouter uses JSON, not multipart/form-data.""" + def test_get_complete_url_defaults_to_openrouter(self, monkeypatch): + monkeypatch.delenv("OPENROUTER_API_BASE", raising=False) + + result = self.config.get_complete_url(model=self.model, api_base=None, litellm_params={}) + + assert result == "https://openrouter.ai/api/v1/images" + + def test_get_complete_url_reads_api_base_from_env(self, monkeypatch): + monkeypatch.setenv("OPENROUTER_API_BASE", "https://gateway.internal/openrouter/v1/") + + result = self.config.get_complete_url(model=self.model, api_base=None, litellm_params={}) + + assert result == "https://gateway.internal/openrouter/v1/images" + + def test_get_complete_url_does_not_duplicate_images_path(self): + result = self.config.get_complete_url( + model=self.model, + api_base="https://openrouter.ai/api/v1/images", + litellm_params={}, + ) + + assert result == "https://openrouter.ai/api/v1/images" + + def test_uses_json_not_multipart(self): assert self.config.use_multipart_form_data() is False - # Parameter mapping tests - def test_map_openai_params_size(self): - """Test that size is mapped to image_config.aspect_ratio.""" +class TestOpenRouterImageEditParams: + def setup_method(self): + self.config = OpenRouterImageEditConfig() + self.model = "openai/gpt-image-2" + + def test_get_supported_openai_params(self): + assert set(self.config.get_supported_openai_params(self.model)) == { + "background", + "n", + "quality", + "response_format", + "size", + } + + @pytest.mark.parametrize( + "size, expected_aspect_ratio", + [ + ("256x256", "1:1"), + ("1024x1024", "1:1"), + ("1536x1024", "3:2"), + ("1792x1024", "16:9"), + ("1024x1536", "2:3"), + ("1024x1792", "9:16"), + ("1184x864", "4:3"), + ("1536x672", "21:9"), + ], + ) + def test_size_maps_to_nearest_supported_aspect_ratio(self, size, expected_aspect_ratio): + result = self.config.map_openai_params( + image_edit_optional_params={"size": size}, + model=self.model, + drop_params=False, + ) + + assert result == {"aspect_ratio": expected_aspect_ratio} + + def test_aspect_ratio_is_not_nested_under_image_config(self): + """`image_config` is a chat completions concept; /images takes the params flat.""" result = self.config.map_openai_params( image_edit_optional_params={"size": "1024x1024"}, model=self.model, drop_params=False, ) - assert "image_config" in result - assert result["image_config"]["aspect_ratio"] == "1:1" + assert "image_config" not in result - def test_map_openai_params_quality(self): - """Test that quality is mapped to image_config.image_size.""" + @pytest.mark.parametrize("size", ["auto", "", "large", "1024", "0x0"]) + def test_size_without_a_pixel_value_is_omitted(self, size): + """No aspect_ratio is better than guessing 1:1 and silently squaring the output.""" + result = self.config.map_openai_params( + image_edit_optional_params={"size": size}, + model=self.model, + drop_params=False, + ) + + assert result == {} + + @pytest.mark.parametrize("quality", ["auto", "low", "medium", "high"]) + def test_quality_passes_through_untranslated(self, quality): + """OpenRouter reuses OpenAI's quality enum; translating it to an `image_size` tier + silently drops the caller's intent on models that take `quality`.""" + result = self.config.map_openai_params( + image_edit_optional_params={"quality": quality}, + model=self.model, + drop_params=False, + ) + + assert result == {"quality": quality} + + def test_image_size_tier_is_not_synthesized_from_quality(self): result = self.config.map_openai_params( image_edit_optional_params={"quality": "high"}, model=self.model, drop_params=False, ) - assert "image_config" in result - assert result["image_config"]["image_size"] == "4K" + assert "image_size" not in result + assert "resolution" not in result - def test_map_openai_params_size_and_quality(self): - """Test that both size and quality are mapped correctly.""" + def test_n_and_background_pass_through(self): result = self.config.map_openai_params( - image_edit_optional_params={"size": "1792x1024", "quality": "hd"}, + image_edit_optional_params={"n": 2, "background": "transparent"}, model=self.model, drop_params=False, ) - assert result["image_config"]["aspect_ratio"] == "16:9" - assert result["image_config"]["image_size"] == "4K" + assert result == {"n": 2, "background": "transparent"} - def test_map_openai_params_n_passthrough(self): - """Test that n parameter is passed through directly.""" + def test_multipart_string_n_is_coerced_to_int(self): + """ + a caller may invoke /v1/images/edits as multipart/form-data, where every field + (including `n`) arrives as `str`. OpenRouter's /api/v1/images schema requires `n` + as a number, so an uncoerced `"1"` 400s with a Zod "expected number, received + string" error. This is the regression this fix closes. + """ result = self.config.map_openai_params( - image_edit_optional_params={"n": 2}, + image_edit_optional_params={"n": "1"}, model=self.model, drop_params=False, ) - assert result["n"] == 2 + assert result == {"n": 1} + assert isinstance(result["n"], int) - def test_map_openai_params_unknown_quality_ignored(self): - """Test that unknown quality values produce no image_size mapping.""" + def test_multipart_string_n_with_whitespace_is_coerced(self): result = self.config.map_openai_params( - image_edit_optional_params={"quality": "unknown_value"}, + image_edit_optional_params={"n": " 3 "}, model=self.model, drop_params=False, ) - assert "image_config" not in result + assert result == {"n": 3} - # Size-to-aspect-ratio mapping tests - - def test_map_size_to_aspect_ratio_square(self): - """Test mapping square sizes to 1:1 aspect ratio.""" - assert self.config._map_size_to_aspect_ratio("256x256") == "1:1" - assert self.config._map_size_to_aspect_ratio("512x512") == "1:1" - assert self.config._map_size_to_aspect_ratio("1024x1024") == "1:1" - - def test_map_size_to_aspect_ratio_landscape(self): - """Test mapping landscape sizes to correct aspect ratios.""" - assert self.config._map_size_to_aspect_ratio("1536x1024") == "3:2" - assert self.config._map_size_to_aspect_ratio("1792x1024") == "16:9" - - def test_map_size_to_aspect_ratio_portrait(self): - """Test mapping portrait sizes to correct aspect ratios.""" - assert self.config._map_size_to_aspect_ratio("1024x1536") == "2:3" - assert self.config._map_size_to_aspect_ratio("1024x1792") == "9:16" - - def test_map_size_to_aspect_ratio_unknown_defaults_to_1_1(self): - """Test that unknown size defaults to 1:1.""" - assert self.config._map_size_to_aspect_ratio("999x999") == "1:1" - - # Quality-to-image-size mapping tests - - def test_map_quality_to_image_size(self): - """Test quality to image size mappings.""" - assert self.config._map_quality_to_image_size("low") == "1K" - assert self.config._map_quality_to_image_size("standard") == "1K" - assert self.config._map_quality_to_image_size("auto") == "1K" - assert self.config._map_quality_to_image_size("medium") == "2K" - assert self.config._map_quality_to_image_size("high") == "4K" - assert self.config._map_quality_to_image_size("hd") == "4K" - - def test_map_quality_to_image_size_unknown_returns_none(self): - """Test that unknown quality returns None.""" - assert self.config._map_quality_to_image_size("unknown") is None - - # URL tests - - def test_get_complete_url_default(self): - """Test that default URL is OpenRouter chat completions endpoint.""" - result = self.config.get_complete_url( - model=self.model, - api_base=None, - litellm_params={}, - ) - - assert result == "https://openrouter.ai/api/v1/chat/completions" - - def test_get_complete_url_with_custom_base(self): - """Test that custom api_base gets /chat/completions appended.""" - result = self.config.get_complete_url( - model=self.model, - api_base="https://custom.openrouter.ai/api/v1", - litellm_params={}, - ) - - assert result == "https://custom.openrouter.ai/api/v1/chat/completions" - - def test_get_complete_url_with_complete_base(self): - """Test that api_base already ending in /chat/completions is not duplicated.""" - url = "https://custom.openrouter.ai/api/v1/chat/completions" - result = self.config.get_complete_url( - model=self.model, - api_base=url, - litellm_params={}, - ) - - assert result == url - - # Validate environment tests - - @patch("litellm.llms.openrouter.image_edit.transformation.get_secret_str") - def test_validate_environment_with_api_key(self, mock_get_secret): - """Test that validate_environment sets authorization header with provided key.""" - headers = {} - result = self.config.validate_environment( - headers=headers, - model=self.model, - api_key="test_api_key", - ) - - assert result["Authorization"] == "Bearer test_api_key" - mock_get_secret.assert_not_called() - - @patch("litellm.llms.openrouter.image_edit.transformation.get_secret_str") - def test_validate_environment_with_secret_key(self, mock_get_secret): - """Test that validate_environment falls back to secret key.""" - mock_get_secret.return_value = "secret_api_key" - headers = {} - result = self.config.validate_environment( - headers=headers, - model=self.model, - api_key=None, - ) - - assert result["Authorization"] == "Bearer secret_api_key" - - @patch("litellm.llms.openrouter.image_edit.transformation.litellm") - @patch("litellm.llms.openrouter.image_edit.transformation.get_secret_str") - def test_validate_environment_missing_api_key_raises( - self, mock_get_secret, mock_litellm - ): - """Test that validate_environment raises ValueError when no API key is available.""" - mock_get_secret.return_value = None - mock_litellm.api_key = None - - with pytest.raises(ValueError, match="OPENROUTER_API_KEY is not set"): - self.config.validate_environment( - headers={}, + def test_non_numeric_n_raises_a_clear_400_instead_of_reaching_openrouter(self): + with pytest.raises(litellm.UnsupportedParamsError) as exc_info: + self.config.map_openai_params( + image_edit_optional_params={"n": "not-a-number"}, model=self.model, - api_key=None, + drop_params=False, ) - # Request transformation tests + assert "expects `n` to be an integer" in str(exc_info.value) + assert "not-a-number" in str(exc_info.value) - def test_transform_image_edit_request_basic(self): - """Test basic request transformation with image and prompt.""" - data, files = self.config.transform_image_edit_request( + def test_boolean_n_raises_instead_of_silently_sending_zero_or_one(self): + with pytest.raises(litellm.UnsupportedParamsError) as exc_info: + self.config.map_openai_params( + image_edit_optional_params={"n": True}, + model=self.model, + drop_params=False, + ) + + assert "boolean" in str(exc_info.value) + + def test_b64_json_response_format_is_accepted_and_not_sent(self): + result = self.config.map_openai_params( + image_edit_optional_params={"response_format": "b64_json"}, model=self.model, - prompt="Add a sunset to this image", - image=self.sample_image_bytes, - image_edit_optional_request_params={}, + drop_params=False, + ) + + assert result == {} + + def test_url_response_format_raises(self): + with pytest.raises(litellm.UnsupportedParamsError) as exc_info: + self.config.map_openai_params( + image_edit_optional_params={"response_format": "url"}, + model=self.model, + drop_params=False, + ) + + assert "response_format='url' is not supported" in str(exc_info.value) + + def test_url_response_format_is_dropped_when_drop_params_is_set(self): + result = self.config.map_openai_params( + image_edit_optional_params={"response_format": "url", "size": "1024x1024"}, + model=self.model, + drop_params=True, + ) + + assert result == {"aspect_ratio": "1:1"} + + def test_mask_is_rejected_because_openrouter_has_no_mask(self): + with pytest.raises(litellm.UnsupportedParamsError) as exc_info: + ImageEditRequestUtils.get_optional_params_image_edit( + model=self.model, + image_edit_provider_config=self.config, + image_edit_optional_params={"mask": "data:image/png;base64,abc"}, + ) + + assert "mask" in str(exc_info.value) + + +class TestOpenRouterImageEditRequest: + def setup_method(self): + self.config = OpenRouterImageEditConfig() + self.model = "openai/gpt-image-2" + + def _transform(self, image=PNG_BYTES, prompt="Add a sunset", optional_params=None): + return self.config.transform_image_edit_request( + model=self.model, + prompt=prompt, + image=image, + image_edit_optional_request_params=optional_params or {}, litellm_params=GenericLiteLLMParams(), headers={}, ) + def test_source_image_travels_in_input_references_not_in_messages(self): + data, files = self._transform() + assert data["model"] == self.model - assert data["modalities"] == ["image", "text"] - assert len(data["messages"]) == 1 - assert data["messages"][0]["role"] == "user" - - content = data["messages"][0]["content"] - assert len(content) == 2 - - # First content part should be the image - assert content[0]["type"] == "image_url" - assert content[0]["image_url"]["url"].startswith("data:image/png;base64,") - - # Second content part should be the text prompt - assert content[1]["type"] == "text" - assert content[1]["text"] == "Add a sunset to this image" - - # Files should be empty (JSON mode) + assert data["prompt"] == "Add a sunset" + assert "messages" not in data + assert "modalities" not in data assert list(files) == [] - def test_transform_image_edit_request_with_bytesio(self): - """Test request transformation with BytesIO image input.""" - image = BytesIO(self.sample_image_bytes) - data, files = self.config.transform_image_edit_request( - model=self.model, - prompt="Edit this", - image=image, - image_edit_optional_request_params={}, - litellm_params=GenericLiteLLMParams(), - headers={}, - ) + assert data["input_references"] == [ + { + "type": "image_url", + "image_url": {"url": f"data:image/png;base64,{base64.b64encode(PNG_BYTES).decode()}"}, + } + ] - content = data["messages"][0]["content"] - assert content[0]["type"] == "image_url" - assert content[0]["image_url"]["url"].startswith("data:image/png;base64,") + def test_multiple_source_images_become_multiple_references(self): + data, _ = self._transform(image=[PNG_BYTES, PNG_BYTES]) - def test_transform_image_edit_request_with_multiple_images(self): - """Test request transformation with a list of images.""" - images = [self.sample_image_bytes, self.sample_image_bytes] - data, files = self.config.transform_image_edit_request( - model=self.model, - prompt="Combine these images", - image=images, - image_edit_optional_request_params={}, - litellm_params=GenericLiteLLMParams(), - headers={}, - ) + assert len(data["input_references"]) == 2 + assert all(ref["type"] == "image_url" for ref in data["input_references"]) - content = data["messages"][0]["content"] - # Two image parts + one text part - assert len(content) == 3 - assert content[0]["type"] == "image_url" - assert content[1]["type"] == "image_url" - assert content[2]["type"] == "text" + def test_bytesio_image_is_read_without_moving_the_caller_position(self): + image = BytesIO(PNG_BYTES) + image.seek(4) - def test_transform_image_edit_request_with_optional_params(self): - """Test that optional params are included in request body.""" - data, files = self.config.transform_image_edit_request( - model=self.model, - prompt="Edit this", - image=self.sample_image_bytes, - image_edit_optional_request_params={ - "image_config": {"aspect_ratio": "16:9"}, - "n": 2, - }, - litellm_params=GenericLiteLLMParams(), - headers={}, - ) + data, _ = self._transform(image=image) - assert data["image_config"]["aspect_ratio"] == "16:9" + assert data["input_references"][0]["image_url"]["url"].endswith(base64.b64encode(PNG_BYTES).decode()) + assert image.tell() == 4 + + def test_jpeg_content_type_is_detected(self): + jpeg_bytes = b"\xff\xd8\xff\xe0" + b"\x00" * 100 + + data, _ = self._transform(image=jpeg_bytes) + + assert data["input_references"][0]["image_url"]["url"].startswith("data:image/jpeg;base64,") + + def test_mapped_params_are_sent_flat(self): + data, _ = self._transform(optional_params={"aspect_ratio": "16:9", "n": 2, "quality": "high"}) + + assert data["aspect_ratio"] == "16:9" assert data["n"] == 2 + assert data["quality"] == "high" - def test_transform_image_edit_request_base64_encoding(self): - """Test that image bytes are correctly base64-encoded in the request.""" - raw_bytes = b"test_image_data" - expected_b64 = base64.b64encode(raw_bytes).decode("utf-8") + def test_extra_headers_are_not_leaked_into_the_request_body(self): + data, _ = self._transform(optional_params={"extra_headers": {"X-Title": "litellm"}}) - data, _ = self.config.transform_image_edit_request( + assert "extra_headers" not in data + + def test_missing_image_raises_instead_of_generating_a_new_one(self): + """Without input_references OpenRouter would happily generate an unrelated image.""" + with pytest.raises(ValueError, match="image is required"): + self._transform(image=[]) + + def test_unsupported_image_type_raises(self): + with pytest.raises(ValueError, match="Unsupported image type"): + self._transform(image="not_an_image") + + def test_prompt_is_omitted_when_absent(self): + data, _ = self._transform(prompt=None) + + assert "prompt" not in data + + +class TestOpenRouterImageEditResponse: + def setup_method(self): + self.config = OpenRouterImageEditConfig() + self.model = "openai/gpt-image-2" + + def _transform(self, payload: object, status_code: int = 200): + return self.config.transform_image_edit_response( model=self.model, - prompt="Edit", - image=raw_bytes, - image_edit_optional_request_params={}, - litellm_params=GenericLiteLLMParams(), - headers={}, + raw_response=make_httpx_response(payload, status_code=status_code), + logging_obj=None, ) - image_url = data["messages"][0]["content"][0]["image_url"]["url"] - # Extract the base64 part after the data URL prefix - b64_part = image_url.split(",", 1)[1] - assert b64_part == expected_b64 - - def test_transform_image_edit_request_no_prompt(self): - """Test request transformation with no prompt (image-only).""" - data, _ = self.config.transform_image_edit_request( - model=self.model, - prompt=None, - image=self.sample_image_bytes, - image_edit_optional_request_params={}, - litellm_params=GenericLiteLLMParams(), - headers={}, - ) - - content = data["messages"][0]["content"] - # Only image, no text part - assert len(content) == 1 - assert content[0]["type"] == "image_url" - - # Response transformation tests - - def test_transform_image_edit_response_with_base64(self): - """Test response transformation with base64 image data.""" - response_data = { - "choices": [ - { - "message": { - "content": "Here is the edited image.", - "role": "assistant", - "images": [ - { - "image_url": { - "url": "data:image/png;base64,iVBORw0KGgoAAAANS" - }, - "type": "image_url", - } - ], - } - } - ], - "usage": { - "prompt_tokens": 300, - "completion_tokens": 1299, - "total_tokens": 1599, - "completion_tokens_details": {"image_tokens": 1290}, - "cost": 0.05, - }, - "model": self.model, - } - - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} - - result = self.config.transform_image_edit_response( - model=self.model, - raw_response=mock_response, - logging_obj=self.logging_obj, - ) + def test_extracts_base64_image_from_data_array(self): + result = self._transform(OPENROUTER_IMAGES_RESPONSE) assert len(result.data) == 1 assert result.data[0].b64_json == "iVBORw0KGgoAAAANS" assert result.data[0].url is None - def test_transform_image_edit_response_with_url(self): - """Test response transformation with URL image data.""" - response_data = { - "choices": [ - { - "message": { - "content": "Edited.", - "role": "assistant", - "images": [ - { - "image_url": {"url": "https://example.com/edited.png"}, - "type": "image_url", - } - ], - } - } - ], - "usage": {"prompt_tokens": 10, "total_tokens": 1310}, - "model": self.model, - } + def test_extracts_multiple_images(self): + payload = {"created": 0, "data": [{"b64_json": "image1data"}, {"b64_json": "image2data"}]} - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} + result = self._transform(payload) - result = self.config.transform_image_edit_response( - model=self.model, - raw_response=mock_response, - logging_obj=self.logging_obj, - ) + assert [image.b64_json for image in result.data] == ["image1data", "image2data"] + + def test_extracts_url_image(self): + payload = {"created": 0, "data": [{"url": "https://example.com/edited.png"}]} + + result = self._transform(payload) - assert len(result.data) == 1 assert result.data[0].url == "https://example.com/edited.png" assert result.data[0].b64_json is None - def test_transform_image_edit_response_usage_and_cost(self): - """Test that usage and cost are correctly extracted from response.""" - response_data = { - "choices": [ - { - "message": { - "content": "Edited.", - "role": "assistant", - "images": [ - { - "image_url": {"url": "data:image/png;base64,abc123"}, - "type": "image_url", - } - ], - } - } - ], - "usage": { - "prompt_tokens": 300, - "completion_tokens": 1299, - "total_tokens": 1599, - "completion_tokens_details": {"image_tokens": 1290}, - "prompt_tokens_details": {"image_tokens": 258}, - "cost": 0.05, - "cost_details": {"input_cost": 0.01, "output_cost": 0.04}, - }, - "model": self.model, - } + def test_maps_usage_and_cost(self): + result = self._transform(OPENROUTER_IMAGES_RESPONSE) - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} - - result = self.config.transform_image_edit_response( - model=self.model, - raw_response=mock_response, - logging_obj=self.logging_obj, - ) - - # Check usage assert result.usage is not None assert result.usage.input_tokens == 300 assert result.usage.output_tokens == 1290 assert result.usage.total_tokens == 1599 assert result.usage.input_tokens_details.image_tokens == 258 assert result.usage.input_tokens_details.text_tokens == 42 + assert result._hidden_params["additional_headers"]["llm_provider-x-litellm-response-cost"] == 0.05 + assert result._hidden_params["response_cost_details"]["upstream_inference_cost"] == 0.05 - # Check cost - assert ( - result._hidden_params["additional_headers"][ - "llm_provider-x-litellm-response-cost" - ] - == 0.05 - ) - - # Check cost details - assert result._hidden_params["response_cost_details"]["input_cost"] == 0.01 - assert result._hidden_params["response_cost_details"]["output_cost"] == 0.04 - - # Check model - assert result._hidden_params["model"] == self.model - - def test_transform_image_edit_response_multiple_images(self): - """Test response transformation with multiple output images.""" - response_data = { - "choices": [ - { - "message": { - "content": "Here are your edits.", - "role": "assistant", - "images": [ - { - "image_url": {"url": "data:image/png;base64,img1data"}, - "type": "image_url", - }, - { - "image_url": {"url": "data:image/png;base64,img2data"}, - "type": "image_url", - }, - ], - } - } - ], - "usage": {"prompt_tokens": 300, "total_tokens": 2600}, - "model": self.model, + def test_falls_back_to_completion_tokens_when_image_tokens_absent(self): + payload = { + "data": [{"b64_json": "abc"}], + "usage": {"prompt_tokens": 6, "completion_tokens": 1299, "total_tokens": 1305}, } - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} + result = self._transform(payload) - result = self.config.transform_image_edit_response( - model=self.model, - raw_response=mock_response, - logging_obj=self.logging_obj, + assert result.usage.output_tokens == 1299 + assert result.usage.input_tokens_details.image_tokens == 0 + + def test_zero_created_does_not_overwrite_litellm_timestamp(self): + result = self._transform(OPENROUTER_IMAGES_RESPONSE) + + assert result.created > 0 + + def test_reports_response_model(self): + payload = {"data": [{"b64_json": "abc"}], "model": "openai/gpt-image-2"} + + result = self._transform(payload) + + assert result._hidden_params["model"] == "openai/gpt-image-2" + + def test_response_without_data_raises(self): + with pytest.raises(OpenRouterException) as exc_info: + self._transform({"created": 0}) + + assert "Error parsing OpenRouter image response" in str(exc_info.value) + + def test_unparseable_response_raises(self): + raw_response = httpx.Response( + status_code=502, + text="bad gateway", + request=httpx.Request(method="POST", url="https://openrouter.ai/api/v1/images"), ) - assert len(result.data) == 2 - assert result.data[0].b64_json == "img1data" - assert result.data[1].b64_json == "img2data" - - def test_transform_image_edit_response_json_error(self): - """Test that invalid JSON response raises OpenRouterException.""" - mock_response = MagicMock() - mock_response.json.side_effect = json.JSONDecodeError("Invalid JSON", "", 0) - mock_response.status_code = 500 - mock_response.headers = {} - with pytest.raises(OpenRouterException) as exc_info: self.config.transform_image_edit_response( model=self.model, - raw_response=mock_response, - logging_obj=self.logging_obj, + raw_response=raw_response, + logging_obj=None, ) - assert "Error parsing OpenRouter response" in str(exc_info.value) - assert exc_info.value.status_code == 500 + assert exc_info.value.status_code == 502 def test_get_error_class(self): - """Test that get_error_class returns OpenRouterException.""" error = self.config.get_error_class( error_message="Test error", status_code=400, @@ -537,22 +461,112 @@ class TestOpenRouterImageEditTransformation: assert isinstance(error, OpenRouterException) assert error.status_code == 400 - # Read image bytes tests - def test_read_image_bytes_from_bytes(self): - """Test reading bytes directly.""" - result = self.config._read_image_bytes(b"raw_bytes") - assert result == b"raw_bytes" +class TestOpenRouterImageEditEnvironment: + def setup_method(self): + self.config = OpenRouterImageEditConfig() + self.model = "openai/gpt-image-2" - def test_read_image_bytes_from_bytesio(self): - """Test reading bytes from BytesIO.""" - bio = BytesIO(b"bytesio_data") - bio.seek(5) # Move position to test seek reset - result = self.config._read_image_bytes(bio) - assert result == b"bytesio_data" - assert bio.tell() == 5 # Position should be restored + def test_validate_environment_prefers_explicit_api_key(self, monkeypatch): + monkeypatch.setenv("OPENROUTER_API_KEY", "env_key") - def test_read_image_bytes_unsupported_type(self): - """Test that unsupported image type raises ValueError.""" - with pytest.raises(ValueError, match="Unsupported image type"): - self.config._read_image_bytes("not_an_image") # type: ignore + headers = self.config.validate_environment(headers={}, model=self.model, api_key="test_api_key") + + assert headers["Authorization"] == "Bearer test_api_key" + + def test_validate_environment_falls_back_to_env_api_key(self, monkeypatch): + monkeypatch.setenv("OPENROUTER_API_KEY", "secret_api_key") + + headers = self.config.validate_environment(headers={}, model=self.model, api_key=None) + + assert headers["Authorization"] == "Bearer secret_api_key" + + def test_validate_environment_without_api_key_raises(self, monkeypatch): + monkeypatch.delenv("OPENROUTER_API_KEY", raising=False) + monkeypatch.setattr(litellm, "api_key", None) + + with pytest.raises(ValueError, match="OPENROUTER_API_KEY is not set"): + self.config.validate_environment(headers={}, model=self.model, api_key=None) + + +class TestOpenRouterImageEditEndToEnd: + """Covers param mapping + URL + body together, the way the proxy drives it.""" + + def test_openai_style_edit_reaches_the_openrouter_images_endpoint(self): + recorder = RequestRecorder(OPENROUTER_IMAGES_RESPONSE) + + response = litellm.image_edit( + model="openrouter/openai/gpt-image-2", + image=PNG_BYTES, + prompt="Add a sunset behind the mountain", + n=1, + size="1024x1024", + response_format="b64_json", + api_key="sk-test", + api_base="https://openrouter.ai/api/v1", + client=make_client(recorder), + ) + + assert recorder.request is not None + assert str(recorder.request.url) == "https://openrouter.ai/api/v1/images" + assert recorder.request.headers["Authorization"] == "Bearer sk-test" + assert recorder.body() == { + "model": "openai/gpt-image-2", + "prompt": "Add a sunset behind the mountain", + "input_references": [ + { + "type": "image_url", + "image_url": {"url": f"data:image/png;base64,{base64.b64encode(PNG_BYTES).decode()}"}, + } + ], + "n": 1, + "aspect_ratio": "1:1", + } + assert response.data[0].b64_json == "iVBORw0KGgoAAAANS" + + def test_image_only_model_no_longer_asks_for_text_modality(self): + """`modalities: ["image", "text"]` is what made OpenRouter answer 404 for these models.""" + recorder = RequestRecorder(OPENROUTER_IMAGES_RESPONSE) + + litellm.image_edit( + model="openrouter/openai/gpt-image-2", + image=PNG_BYTES, + prompt="Add a sunset", + api_key="sk-test", + api_base="https://openrouter.ai/api/v1", + client=make_client(recorder), + ) + + assert "chat/completions" not in str(recorder.request.url) + assert "modalities" not in recorder.body() + + def test_hybrid_image_model_uses_the_same_endpoint(self): + recorder = RequestRecorder(OPENROUTER_IMAGES_RESPONSE) + + litellm.image_edit( + model="openrouter/google/gemini-2.5-flash-image", + image=PNG_BYTES, + prompt="Add a sunset", + api_key="sk-test", + api_base="https://openrouter.ai/api/v1", + client=make_client(recorder), + ) + + assert str(recorder.request.url) == "https://openrouter.ai/api/v1/images" + assert recorder.body()["model"] == "google/gemini-2.5-flash-image" + + def test_openrouter_error_is_surfaced(self): + recorder = RequestRecorder( + {"error": {"message": "No endpoints found that support image edit", "code": 404}}, + status_code=404, + ) + + with pytest.raises(litellm.NotFoundError): + litellm.image_edit( + model="openrouter/openai/gpt-image-2", + image=PNG_BYTES, + prompt="Add a sunset", + api_key="sk-test", + api_base="https://openrouter.ai/api/v1", + client=make_client(recorder), + ) diff --git a/tests/test_litellm/llms/openrouter/image_generation/__init__.py b/tests/test_litellm/llms/openrouter/image_generation/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/test_litellm/llms/openrouter/image_generation/test_openrouter_image_gen_transformation.py b/tests/test_litellm/llms/openrouter/image_generation/test_openrouter_image_gen_transformation.py index e45270fb5e3..178e3de1eec 100644 --- a/tests/test_litellm/llms/openrouter/image_generation/test_openrouter_image_gen_transformation.py +++ b/tests/test_litellm/llms/openrouter/image_generation/test_openrouter_image_gen_transformation.py @@ -1,170 +1,91 @@ import json -from unittest.mock import MagicMock, patch +import os +import sys import httpx import pytest +sys.path.insert(0, os.path.abspath("../../../../..")) # Adds the parent directory to the system path +import litellm +from litellm.llms.custom_httpx.http_handler import HTTPHandler +from litellm.llms.openrouter.common_utils import OpenRouterException from litellm.llms.openrouter.image_generation.transformation import ( OpenRouterImageGenerationConfig, ) -from litellm.llms.openrouter.common_utils import OpenRouterException from litellm.types.utils import ImageResponse +# Verbatim shape of a `POST https://openrouter.ai/api/v1/images` response. +OPENROUTER_IMAGES_RESPONSE = { + "created": 0, + "data": [{"b64_json": "iVBORw0KGgoAAAANS", "media_type": "image/png"}], + "usage": { + "prompt_tokens": 0, + "completion_tokens": 4175, + "total_tokens": 4175, + "cost": 0.06, + "is_byok": False, + "prompt_tokens_details": {"cached_tokens": 0}, + "cost_details": { + "upstream_inference_cost": 0.06, + "upstream_inference_prompt_cost": 0.0, + "upstream_inference_completions_cost": 0.06, + }, + "completion_tokens_details": {"reasoning_tokens": 0, "image_tokens": 4175}, + }, +} + + +class RequestRecorder: + """httpx.MockTransport handler that keeps the request it was called with.""" + + def __init__(self, response_payload: dict, status_code: int = 200): + self.response_payload = response_payload + self.status_code = status_code + self.request: httpx.Request | None = None + + def __call__(self, request: httpx.Request) -> httpx.Response: + self.request = request + return httpx.Response(status_code=self.status_code, json=self.response_payload) + + def body(self) -> dict: + assert self.request is not None, "no request was sent" + return json.loads(self.request.content) + + +def make_client(recorder: RequestRecorder) -> HTTPHandler: + return HTTPHandler(client=httpx.Client(transport=httpx.MockTransport(recorder))) + + +def make_httpx_response(payload: object, status_code: int = 200) -> httpx.Response: + return httpx.Response( + status_code=status_code, + json=payload, + request=httpx.Request(method="POST", url="https://openrouter.ai/api/v1/images"), + ) + + +class TestOpenRouterImageGenerationEndpoint: + """OpenRouter serves image generation from /api/v1/images, never /chat/completions.""" -class TestOpenRouterImageGenerationTransformation: def setup_method(self): - """Set up test fixtures before each test method.""" self.config = OpenRouterImageGenerationConfig() - self.model = "google/gemini-2.5-flash-image" - self.logging_obj = MagicMock() + self.model = "krea/krea-2-large" - def test_get_supported_openai_params(self): - """Test that get_supported_openai_params returns correct parameters.""" - supported_params = self.config.get_supported_openai_params(self.model) - - assert "size" in supported_params - assert "quality" in supported_params - assert "n" in supported_params - assert len(supported_params) == 3 - - def test_map_size_to_aspect_ratio_square(self): - """Test mapping square sizes to aspect ratio.""" - assert self.config._map_size_to_aspect_ratio("256x256") == "1:1" - assert self.config._map_size_to_aspect_ratio("512x512") == "1:1" - assert self.config._map_size_to_aspect_ratio("1024x1024") == "1:1" - - def test_map_size_to_aspect_ratio_landscape(self): - """Test mapping landscape sizes to aspect ratio.""" - assert self.config._map_size_to_aspect_ratio("1536x1024") == "3:2" - assert self.config._map_size_to_aspect_ratio("1792x1024") == "16:9" - - def test_map_size_to_aspect_ratio_portrait(self): - """Test mapping portrait sizes to aspect ratio.""" - assert self.config._map_size_to_aspect_ratio("1024x1536") == "2:3" - assert self.config._map_size_to_aspect_ratio("1024x1792") == "9:16" - - def test_map_size_to_aspect_ratio_auto(self): - """Test mapping auto size to default aspect ratio.""" - assert self.config._map_size_to_aspect_ratio("auto") == "1:1" - - def test_map_size_to_aspect_ratio_unknown(self): - """Test mapping unknown size defaults to 1:1.""" - assert self.config._map_size_to_aspect_ratio("999x999") == "1:1" - - def test_map_quality_to_image_size_low(self): - """Test mapping low quality values to 1K.""" - assert self.config._map_quality_to_image_size("low") == "1K" - assert self.config._map_quality_to_image_size("standard") == "1K" - assert self.config._map_quality_to_image_size("auto") == "1K" - - def test_map_quality_to_image_size_medium(self): - """Test mapping medium quality to 2K.""" - assert self.config._map_quality_to_image_size("medium") == "2K" - - def test_map_quality_to_image_size_high(self): - """Test mapping high quality values to 4K.""" - assert self.config._map_quality_to_image_size("high") == "4K" - assert self.config._map_quality_to_image_size("hd") == "4K" - - def test_map_quality_to_image_size_unknown(self): - """Test mapping unknown quality returns None.""" - assert self.config._map_quality_to_image_size("unknown") is None - - def test_map_openai_params_size_only(self): - """Test that map_openai_params correctly maps size parameter.""" - non_default_params = {"size": "1024x1024"} - optional_params = {} - - result = self.config.map_openai_params( - non_default_params=non_default_params, - optional_params=optional_params, + def test_get_complete_url_appends_images_path(self): + result = self.config.get_complete_url( + api_base="https://openrouter.ai/api/v1", + api_key="test_key", model=self.model, - drop_params=False, + optional_params={}, + litellm_params={}, ) - assert "image_config" in result - assert result["image_config"]["aspect_ratio"] == "1:1" + assert result == "https://openrouter.ai/api/v1/images" - def test_map_openai_params_quality_only(self): - """Test that map_openai_params correctly maps quality parameter.""" - non_default_params = {"quality": "high"} - optional_params = {} + def test_get_complete_url_defaults_to_openrouter(self, monkeypatch): + monkeypatch.delenv("OPENROUTER_API_BASE", raising=False) - result = self.config.map_openai_params( - non_default_params=non_default_params, - optional_params=optional_params, - model=self.model, - drop_params=False, - ) - - assert "image_config" in result - assert result["image_config"]["image_size"] == "4K" - - def test_map_openai_params_size_and_quality(self): - """Test that map_openai_params correctly maps both size and quality.""" - non_default_params = {"size": "1792x1024", "quality": "hd"} - optional_params = {} - - result = self.config.map_openai_params( - non_default_params=non_default_params, - optional_params=optional_params, - model=self.model, - drop_params=False, - ) - - assert "image_config" in result - assert result["image_config"]["aspect_ratio"] == "16:9" - assert result["image_config"]["image_size"] == "4K" - - def test_map_openai_params_with_n_parameter(self): - """Test that map_openai_params correctly passes through n parameter.""" - non_default_params = {"size": "1024x1024", "n": 2} - optional_params = {} - - result = self.config.map_openai_params( - non_default_params=non_default_params, - optional_params=optional_params, - model=self.model, - drop_params=False, - ) - - assert "image_config" in result - assert result["image_config"]["aspect_ratio"] == "1:1" - assert result["n"] == 2 - - def test_map_openai_params_unsupported_param_drop_false(self): - """Test that unsupported params are passed through when drop_params=False.""" - non_default_params = {"size": "1024x1024", "unsupported_param": "value"} - optional_params = {} - - result = self.config.map_openai_params( - non_default_params=non_default_params, - optional_params=optional_params, - model=self.model, - drop_params=False, - ) - - assert "image_config" in result - assert result["unsupported_param"] == "value" - - def test_map_openai_params_unsupported_param_drop_true(self): - """Test that unsupported params are dropped when drop_params=True.""" - non_default_params = {"size": "1024x1024", "unsupported_param": "value"} - optional_params = {} - - result = self.config.map_openai_params( - non_default_params=non_default_params, - optional_params=optional_params, - model=self.model, - drop_params=True, - ) - - assert "image_config" in result - assert "unsupported_param" not in result - - def test_get_complete_url_default(self): - """Test that get_complete_url returns default OpenRouter URL.""" result = self.config.get_complete_url( api_base=None, api_key="test_key", @@ -173,152 +94,247 @@ class TestOpenRouterImageGenerationTransformation: litellm_params={}, ) - assert result == "https://openrouter.ai/api/v1/chat/completions" + assert result == "https://openrouter.ai/api/v1/images" - def test_get_complete_url_with_custom_base(self): - """Test that get_complete_url uses custom api_base.""" - custom_base = "https://custom.openrouter.ai/api/v1" + def test_get_complete_url_reads_api_base_from_env(self, monkeypatch): + monkeypatch.setenv("OPENROUTER_API_BASE", "https://gateway.internal/openrouter/v1/") result = self.config.get_complete_url( - api_base=custom_base, + api_base=None, api_key="test_key", model=self.model, optional_params={}, litellm_params={}, ) - assert result == f"{custom_base}/chat/completions" - - def test_get_complete_url_with_base_already_complete(self): - """Test that get_complete_url doesn't duplicate /chat/completions.""" - custom_base = "https://custom.openrouter.ai/api/v1/chat/completions" + assert result == "https://gateway.internal/openrouter/v1/images" + def test_get_complete_url_does_not_duplicate_images_path(self): result = self.config.get_complete_url( - api_base=custom_base, + api_base="https://openrouter.ai/api/v1/images", api_key="test_key", model=self.model, optional_params={}, litellm_params={}, ) - assert result == custom_base + assert result == "https://openrouter.ai/api/v1/images" - @patch("litellm.llms.openrouter.image_generation.transformation.get_secret_str") - def test_validate_environment_with_api_key(self, mock_get_secret): - """Test that validate_environment correctly sets authorization header.""" - headers = {} - api_key = "test_api_key" - result = self.config.validate_environment( - headers=headers, - model=self.model, - messages=[], +class TestOpenRouterImageGenerationParams: + def setup_method(self): + self.config = OpenRouterImageGenerationConfig() + self.model = "krea/krea-2-large" + + def test_get_supported_openai_params(self): + assert set(self.config.get_supported_openai_params(self.model)) == { + "n", + "quality", + "response_format", + "size", + } + + @pytest.mark.parametrize( + "size, expected_aspect_ratio", + [ + ("256x256", "1:1"), + ("512x512", "1:1"), + ("1024x1024", "1:1"), + ("1536x1024", "3:2"), + ("1792x1024", "16:9"), + ("1024x1536", "2:3"), + ("1024x1792", "9:16"), + ("1184x864", "4:3"), + ("896x1152", "4:5"), + ("1536x672", "21:9"), + ], + ) + def test_size_maps_to_nearest_supported_aspect_ratio(self, size, expected_aspect_ratio): + result = self.config.map_openai_params( + non_default_params={"size": size}, optional_params={}, - litellm_params={}, - api_key=api_key, + model=self.model, + drop_params=False, ) - assert result["Authorization"] == f"Bearer {api_key}" - mock_get_secret.assert_not_called() + assert result == {"aspect_ratio": expected_aspect_ratio} - @patch("litellm.llms.openrouter.image_generation.transformation.get_secret_str") - def test_validate_environment_with_secret_key(self, mock_get_secret): - """Test that validate_environment uses secret API key when api_key is None.""" - mock_get_secret.return_value = "secret_api_key" - headers = {} - - result = self.config.validate_environment( - headers=headers, - model=self.model, - messages=[], + @pytest.mark.parametrize("size", ["auto", "", "large", "1024", "0x0"]) + def test_size_without_a_pixel_value_is_omitted(self, size): + """No aspect_ratio is better than guessing 1:1 and silently squaring the output.""" + result = self.config.map_openai_params( + non_default_params={"size": size}, optional_params={}, - litellm_params={}, - api_key=None, + model=self.model, + drop_params=False, ) - assert result["Authorization"] == "Bearer secret_api_key" - mock_get_secret.assert_called_once_with("OPENROUTER_API_KEY") + assert result == {} - def test_transform_image_generation_request_basic(self): - """Test that transform_image_generation_request creates correct request body.""" - prompt = "A beautiful sunset over mountains" + @pytest.mark.parametrize("quality", ["auto", "low", "medium", "high"]) + def test_quality_passes_through_untranslated(self, quality): + """OpenRouter reuses OpenAI's quality enum; translating it to `resolution` silently + drops the caller's intent on models that take `quality` (openai/gpt-image-*).""" + result = self.config.map_openai_params( + non_default_params={"quality": quality}, + optional_params={}, + model=self.model, + drop_params=False, + ) + + assert result == {"quality": quality} + + def test_resolution_is_not_synthesized_from_quality(self): + result = self.config.map_openai_params( + non_default_params={"quality": "high"}, + optional_params={}, + model=self.model, + drop_params=False, + ) + + assert "resolution" not in result + + def test_n_is_passed_through(self): + result = self.config.map_openai_params( + non_default_params={"n": 2, "size": "1024x1024"}, + optional_params={}, + model=self.model, + drop_params=False, + ) + + assert result == {"n": 2, "aspect_ratio": "1:1"} + + def test_string_n_is_coerced_to_int(self): + """ + Same coercion as image_edit's map_openai_params (shared via image_api.map_image_params): + any caller that hands generation a string-typed `n` -- not just the multipart edit path -- + must not reach OpenRouter as a string, since its /api/v1/images schema requires a number. + """ + result = self.config.map_openai_params( + non_default_params={"n": "4"}, + optional_params={}, + model=self.model, + drop_params=False, + ) + + assert result == {"n": 4} + assert isinstance(result["n"], int) + + def test_non_numeric_n_raises_a_clear_400(self): + with pytest.raises(litellm.UnsupportedParamsError) as exc_info: + self.config.map_openai_params( + non_default_params={"n": "many"}, + optional_params={}, + model=self.model, + drop_params=False, + ) + + assert "expects `n` to be an integer" in str(exc_info.value) + + def test_b64_json_response_format_is_accepted_and_not_sent(self): + """Open WebUI always sends response_format=b64_json; it must not need additional_drop_params.""" + result = self.config.map_openai_params( + non_default_params={"response_format": "b64_json"}, + optional_params={}, + model=self.model, + drop_params=False, + ) + + assert result == {} + + def test_url_response_format_raises(self): + with pytest.raises(litellm.UnsupportedParamsError) as exc_info: + self.config.map_openai_params( + non_default_params={"response_format": "url"}, + optional_params={}, + model=self.model, + drop_params=False, + ) + + assert "response_format='url' is not supported" in str(exc_info.value) + + def test_url_response_format_is_dropped_when_drop_params_is_set(self): + result = self.config.map_openai_params( + non_default_params={"response_format": "url", "size": "1024x1024"}, + optional_params={}, + model=self.model, + drop_params=True, + ) + + assert result == {"aspect_ratio": "1:1"} + + def test_map_openai_params_does_not_mutate_its_input(self): optional_params = {} + self.config.map_openai_params( + non_default_params={"size": "1024x1024"}, + optional_params=optional_params, + model=self.model, + drop_params=False, + ) + + assert optional_params == {} + + +class TestOpenRouterImageGenerationRequest: + def setup_method(self): + self.config = OpenRouterImageGenerationConfig() + self.model = "krea/krea-2-large" + + def test_request_body_is_prompt_based_not_chat_based(self): result = self.config.transform_image_generation_request( model=self.model, - prompt=prompt, - optional_params=optional_params, + prompt="a red panda astronaut", + optional_params={"aspect_ratio": "16:9", "resolution": "4K", "n": 1}, litellm_params={}, headers={}, ) - assert result["model"] == self.model - assert result["messages"] == [{"role": "user", "content": prompt}] - assert "modalities" not in result # modalities should not be added by default - - def test_transform_image_generation_request_with_image_config(self): - """Test that transform_image_generation_request includes image_config.""" - prompt = "A beautiful sunset" - optional_params = { - "image_config": {"aspect_ratio": "16:9", "image_size": "4K"}, - "n": 2, + assert result == { + "model": self.model, + "prompt": "a red panda astronaut", + "aspect_ratio": "16:9", + "resolution": "4K", + "n": 1, } + assert "messages" not in result + assert "modalities" not in result + def test_extra_headers_are_not_leaked_into_the_request_body(self): result = self.config.transform_image_generation_request( model=self.model, - prompt=prompt, - optional_params=optional_params, + prompt="a red panda astronaut", + optional_params={"extra_headers": {"X-Title": "litellm"}, "seed": 7}, litellm_params={}, headers={}, ) - assert result["model"] == self.model - assert result["messages"] == [{"role": "user", "content": prompt}] - assert result["image_config"]["aspect_ratio"] == "16:9" - assert result["image_config"]["image_size"] == "4K" - assert result["n"] == 2 + assert result == {"model": self.model, "prompt": "a red panda astronaut", "seed": 7} - def test_transform_image_generation_response_with_base64_images(self): - """Test that transform_image_generation_response correctly extracts base64 images.""" - response_data = { - "choices": [ - { - "message": { - "content": "Here is your image!", - "role": "assistant", - "images": [ - { - "image_url": { - "url": "data:image/png;base64,iVBORw0KGgoAAAANS" - }, - "index": 0, - "type": "image_url", - } - ], - } - } - ], - "usage": { - "prompt_tokens": 10, - "completion_tokens": 1300, - "total_tokens": 1310, - "completion_tokens_details": {"image_tokens": 1290}, - "cost": 0.0387243, - }, - "model": "google/gemini-2.5-flash-image", - } - - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} - - model_response = ImageResponse(data=[]) - - result = self.config.transform_image_generation_response( + def test_provider_native_params_pass_through(self): + result = self.config.transform_image_generation_request( model=self.model, - raw_response=mock_response, - model_response=model_response, + prompt="a red panda astronaut", + optional_params={"output_format": "webp", "input_references": ["https://example.com/a.png"]}, + litellm_params={}, + headers={}, + ) + + assert result["output_format"] == "webp" + assert result["input_references"] == ["https://example.com/a.png"] + + +class TestOpenRouterImageGenerationResponse: + def setup_method(self): + self.config = OpenRouterImageGenerationConfig() + self.model = "krea/krea-2-large" + self.logging_obj = None + + def _transform(self, payload: object, status_code: int = 200) -> ImageResponse: + return self.config.transform_image_generation_response( + model=self.model, + raw_response=make_httpx_response(payload, status_code=status_code), + model_response=ImageResponse(), logging_obj=self.logging_obj, request_data={}, optional_params={}, @@ -326,202 +342,95 @@ class TestOpenRouterImageGenerationTransformation: encoding=None, ) + def test_extracts_base64_image(self): + result = self._transform(OPENROUTER_IMAGES_RESPONSE) + assert len(result.data) == 1 assert result.data[0].b64_json == "iVBORw0KGgoAAAANS" assert result.data[0].url is None - def test_transform_image_generation_response_with_url_images(self): - """Test that transform_image_generation_response correctly extracts URL images.""" - response_data = { - "choices": [ - { - "message": { - "content": "Here is your image!", - "role": "assistant", - "images": [ - { - "image_url": {"url": "https://example.com/image.png"}, - "index": 0, - "type": "image_url", - } - ], - } - } + def test_extracts_multiple_images(self): + payload = { + "created": 0, + "data": [ + {"b64_json": "image1data", "media_type": "image/png"}, + {"b64_json": "image2data", "media_type": "image/png"}, ], - "usage": { - "prompt_tokens": 10, - "completion_tokens": 1300, - "total_tokens": 1310, - }, - "model": "google/gemini-2.5-flash-image", } - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} + result = self._transform(payload) - model_response = ImageResponse(data=[]) + assert [image.b64_json for image in result.data] == ["image1data", "image2data"] - result = self.config.transform_image_generation_response( - model=self.model, - raw_response=mock_response, - model_response=model_response, - logging_obj=self.logging_obj, - request_data={}, - optional_params={}, - litellm_params={}, - encoding=None, - ) + def test_extracts_url_image(self): + payload = {"created": 0, "data": [{"url": "https://example.com/image.png"}]} + + result = self._transform(payload) - assert len(result.data) == 1 assert result.data[0].url == "https://example.com/image.png" assert result.data[0].b64_json is None - def test_transform_image_generation_response_with_usage_and_cost(self): - """Test that transform_image_generation_response correctly extracts usage and cost.""" - response_data = { - "choices": [ - { - "message": { - "content": "Here is your image!", - "role": "assistant", - "images": [ - { - "image_url": {"url": "data:image/png;base64,abc123"}, - "index": 0, - "type": "image_url", - } - ], - } - } - ], - "usage": { - "prompt_tokens": 10, - "completion_tokens": 1300, - "total_tokens": 1310, - "completion_tokens_details": {"image_tokens": 1290}, - "cost": 0.0387243, - "cost_details": {"input_cost": 0.001, "output_cost": 0.037}, - }, - "model": "google/gemini-2.5-flash-image", - } + def test_maps_usage_and_cost(self): + result = self._transform(OPENROUTER_IMAGES_RESPONSE) - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} - - model_response = ImageResponse(data=[]) - - result = self.config.transform_image_generation_response( - model=self.model, - raw_response=mock_response, - model_response=model_response, - logging_obj=self.logging_obj, - request_data={}, - optional_params={}, - litellm_params={}, - encoding=None, - ) - - # Check usage assert result.usage is not None - assert result.usage.input_tokens == 10 - assert result.usage.output_tokens == 1290 - assert result.usage.total_tokens == 1310 - assert result.usage.input_tokens_details.text_tokens == 10 + assert result.usage.input_tokens == 0 + assert result.usage.output_tokens == 4175 + assert result.usage.total_tokens == 4175 assert result.usage.input_tokens_details.image_tokens == 0 + assert result.usage.input_tokens_details.text_tokens == 0 + assert result._hidden_params["additional_headers"]["llm_provider-x-litellm-response-cost"] == 0.06 + assert result._hidden_params["response_cost_details"]["upstream_inference_cost"] == 0.06 - # Check cost - assert hasattr(result, "_hidden_params") - assert "additional_headers" in result._hidden_params - assert ( - result._hidden_params["additional_headers"][ - "llm_provider-x-litellm-response-cost" - ] - == 0.0387243 - ) - - # Check cost details - assert "response_cost_details" in result._hidden_params - assert result._hidden_params["response_cost_details"]["input_cost"] == 0.001 - assert result._hidden_params["response_cost_details"]["output_cost"] == 0.037 - - # Check model - assert result._hidden_params["model"] == "google/gemini-2.5-flash-image" - - def test_transform_image_generation_response_multiple_images(self): - """Test that transform_image_generation_response handles multiple images.""" - response_data = { - "choices": [ - { - "message": { - "content": "Here are your images!", - "role": "assistant", - "images": [ - { - "image_url": { - "url": "data:image/png;base64,image1data" - }, - "index": 0, - "type": "image_url", - }, - { - "image_url": { - "url": "data:image/png;base64,image2data" - }, - "index": 1, - "type": "image_url", - }, - ], - } - } - ], - "usage": { - "prompt_tokens": 10, - "completion_tokens": 2600, - "total_tokens": 2610, - }, - "model": "google/gemini-2.5-flash-image", + def test_falls_back_to_completion_tokens_when_image_tokens_absent(self): + payload = { + "data": [{"b64_json": "abc"}], + "usage": {"prompt_tokens": 6, "completion_tokens": 1299, "total_tokens": 1305}, } - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} + result = self._transform(payload) - model_response = ImageResponse(data=[]) + assert result.usage.output_tokens == 1299 + assert result.usage.input_tokens == 6 - result = self.config.transform_image_generation_response( - model=self.model, - raw_response=mock_response, - model_response=model_response, - logging_obj=self.logging_obj, - request_data={}, - optional_params={}, - litellm_params={}, - encoding=None, + def test_zero_created_does_not_overwrite_litellm_timestamp(self): + """OpenRouter answers `created: 0`; clobbering the response timestamp with it breaks clients.""" + result = self._transform(OPENROUTER_IMAGES_RESPONSE) + + assert result.created > 0 + + def test_created_is_used_when_openrouter_sends_one(self): + payload = {"created": 1785224458, "data": [{"b64_json": "abc"}]} + + result = self._transform(payload) + + assert result.created == 1785224458 + + def test_reports_response_model(self): + payload = {"data": [{"b64_json": "abc"}], "model": "krea/krea-2-large"} + + result = self._transform(payload) + + assert result._hidden_params["model"] == "krea/krea-2-large" + + def test_response_without_data_raises(self): + with pytest.raises(OpenRouterException) as exc_info: + self._transform({"created": 0}) + + assert "Error parsing OpenRouter image response" in str(exc_info.value) + + def test_unparseable_response_raises(self): + raw_response = httpx.Response( + status_code=502, + text="bad gateway", + request=httpx.Request(method="POST", url="https://openrouter.ai/api/v1/images"), ) - assert len(result.data) == 2 - assert result.data[0].b64_json == "image1data" - assert result.data[1].b64_json == "image2data" - - def test_transform_image_generation_response_json_error(self): - """Test that transform_image_generation_response raises error on invalid JSON.""" - mock_response = MagicMock() - mock_response.json.side_effect = json.JSONDecodeError("Invalid JSON", "", 0) - mock_response.status_code = 500 - mock_response.headers = {} - - model_response = ImageResponse(data=[]) - with pytest.raises(OpenRouterException) as exc_info: self.config.transform_image_generation_response( model=self.model, - raw_response=mock_response, - model_response=model_response, + raw_response=raw_response, + model_response=ImageResponse(), logging_obj=self.logging_obj, request_data={}, optional_params={}, @@ -529,48 +438,9 @@ class TestOpenRouterImageGenerationTransformation: encoding=None, ) - assert "Error parsing OpenRouter response" in str(exc_info.value) - assert exc_info.value.status_code == 500 - - def test_transform_image_generation_response_transformation_error(self): - """Test that transform_image_generation_response handles transformation errors.""" - response_data = { - "choices": [ - { - "message": { - "content": "Here is your image!", - "role": "assistant", - "images": "invalid_format", # Invalid format - } - } - ] - } - - mock_response = MagicMock() - mock_response.json.return_value = response_data - mock_response.status_code = 200 - mock_response.headers = {} - - model_response = ImageResponse(data=[]) - - with pytest.raises(OpenRouterException) as exc_info: - self.config.transform_image_generation_response( - model=self.model, - raw_response=mock_response, - model_response=model_response, - logging_obj=self.logging_obj, - request_data={}, - optional_params={}, - litellm_params={}, - encoding=None, - ) - - assert "Error transforming OpenRouter image generation response" in str( - exc_info.value - ) + assert exc_info.value.status_code == 502 def test_get_error_class(self): - """Test that get_error_class returns OpenRouterException.""" error = self.config.get_error_class( error_message="Test error", status_code=400, @@ -580,3 +450,98 @@ class TestOpenRouterImageGenerationTransformation: assert isinstance(error, OpenRouterException) assert "Test error" in str(error) assert error.status_code == 400 + + +class TestOpenRouterImageGenerationEnvironment: + def setup_method(self): + self.config = OpenRouterImageGenerationConfig() + self.model = "krea/krea-2-large" + + def test_validate_environment_prefers_explicit_api_key(self, monkeypatch): + monkeypatch.setenv("OPENROUTER_API_KEY", "env_key") + + headers = self.config.validate_environment( + headers={}, + model=self.model, + messages=[], + optional_params={}, + litellm_params={}, + api_key="test_api_key", + ) + + assert headers["Authorization"] == "Bearer test_api_key" + + def test_validate_environment_falls_back_to_env_api_key(self, monkeypatch): + monkeypatch.setenv("OPENROUTER_API_KEY", "secret_api_key") + + headers = self.config.validate_environment( + headers={}, + model=self.model, + messages=[], + optional_params={}, + litellm_params={}, + api_key=None, + ) + + assert headers["Authorization"] == "Bearer secret_api_key" + + +class TestOpenRouterImageGenerationEndToEnd: + """Covers param mapping + URL + body together, the way the proxy drives it.""" + + def test_openai_style_request_reaches_the_openrouter_images_endpoint(self): + recorder = RequestRecorder(OPENROUTER_IMAGES_RESPONSE) + + response = litellm.image_generation( + model="openrouter/krea/krea-2-large", + prompt="a red panda astronaut", + n=1, + size="1024x1024", + response_format="b64_json", + api_key="sk-test", + api_base="https://openrouter.ai/api/v1", + client=make_client(recorder), + ) + + assert recorder.request is not None + assert str(recorder.request.url) == "https://openrouter.ai/api/v1/images" + assert recorder.request.headers["Authorization"] == "Bearer sk-test" + assert recorder.body() == { + "model": "krea/krea-2-large", + "prompt": "a red panda astronaut", + "n": 1, + "aspect_ratio": "1:1", + } + assert response.data[0].b64_json == "iVBORw0KGgoAAAANS" + + def test_hybrid_image_model_uses_the_same_endpoint(self): + recorder = RequestRecorder(OPENROUTER_IMAGES_RESPONSE) + + litellm.image_generation( + model="openrouter/google/gemini-2.5-flash-image", + prompt="a red panda astronaut", + api_key="sk-test", + api_base="https://openrouter.ai/api/v1", + client=make_client(recorder), + ) + + assert str(recorder.request.url) == "https://openrouter.ai/api/v1/images" + assert recorder.body() == { + "model": "google/gemini-2.5-flash-image", + "prompt": "a red panda astronaut", + } + + def test_openrouter_error_is_surfaced(self): + recorder = RequestRecorder( + {"error": {"message": "No endpoints found matching your data policy", "code": 404}}, + status_code=404, + ) + + with pytest.raises(litellm.NotFoundError): + litellm.image_generation( + model="openrouter/krea/krea-2-large", + prompt="a red panda astronaut", + api_key="sk-test", + api_base="https://openrouter.ai/api/v1", + client=make_client(recorder), + )