[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 <noreply@anthropic.com>
This commit is contained in:
YAN 2026-09-09 23:13:54 +08:00
parent 328a5f5d60
commit 9754747a50
7 changed files with 1333 additions and 1458 deletions

View file

@ -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,
}

View file

@ -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()

View file

@ -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,<base64_data>
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."""

View file

@ -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

View file

@ -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="<html>bad gateway</html>",
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),
)