BerriAI/litellm · error · OpenRouterException

Error transforming OpenRouter image edit response: {e}

Error message

Error transforming OpenRouter image edit response: {e}

What it means

After the OpenRouter image-edit response parses as JSON, LiteLLM maps choices[].message.images[] entries into ImageResponse objects and extracts usage/cost. Any exception during this mapping (missing keys, unexpected nesting, None where a string is expected) is caught and re-raised as an OpenRouterException with a generic status_code=500 and empty headers. The original exception text is embedded in the message.

Source

Thrown at litellm/llms/openrouter/image_edit/transformation.py:248

                            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

    def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException:
        return OpenRouterException(
            message=error_message,
            status_code=status_code,
            headers=headers,
        )

    # Private helper methods

    def _map_size_to_aspect_ratio(self, size: str) -> str:

View on GitHub (pinned to 77b7c6c40c)

Solutions

Enable litellm verbose logging (litellm.set_verbose=True) or log the raw response to see which field broke the mapper
Reproduce the request with curl against OpenRouter and compare the JSON against the expected choices[].message.images[] shape
Confirm the model is image-capable and served through OpenRouter's image-edit endpoint
Upgrade litellm - response-schema drift for OpenRouter is typically patched upstream quickly
If the latest version still fails, open a litellm issue with the sanitized raw JSON

Defensive patterns

Strategy: try-catch

Try / catch

Catch OpenRouterException and test whether the message starts with 'Error transforming' - that indicates a schema/mapping defect, so retrying the same model is futile; capture verbose logs and fail over to a different image model or provider.

Prevention

Pin known-good image model versions instead of floating aliases
Keep litellm.set_verbose available in debug builds to capture raw payloads
Update litellm promptly when OpenRouter announces response format changes

When it happens

Trigger: OpenRouter returns a response whose choices/message/images shape differs from what the mapper expects: choices without images, image entries missing image_url, null fields where the mapper indexes into dicts, or a schema change deployed by OpenRouter for a specific image model.

Common situations: Schema drift between your litellm version and OpenRouter's current image-edit response format; using a chat-only model on the image-edit route so response fields are absent; A/B changes on OpenRouter's side that omit url/b64 fields.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/9f004cf70feead7c. Report an issue: GitHub.