Principle:Helicone Helicone Cross Provider Transform

Knowledge Sources	Helicone
Domains	LLM Observability, AI Gateway, Cross-Provider Compatibility, Response Normalization
Last Updated	2026-02-14 00:00 GMT

Overview

Cross-Provider Transform is the process of converting LLM request and response payloads between different provider formats at runtime, enabling the AI Gateway to accept requests in one format (typically OpenAI) and route them to any supported provider.

Description

Helicone's AI Gateway acts as a universal LLM proxy that allows users to write requests in a single format (OpenAI Chat Completions) and have them transparently routed to Anthropic, Google Gemini, or other providers. This requires two transformation steps:

1. Request transformation (outbound) -- converting the OpenAI-format request body into the target provider's native format before forwarding. For example, toAnthropic() converts OpenAI messages with system/user/assistant roles into Anthropic's format with a separate system parameter, messages array with user/assistant roles, and max_tokens instead of max_completion_tokens.

1. Response normalization (inbound) -- converting the provider's native response back into OpenAI format so that the caller receives a consistent response structure regardless of which provider handled the request. The normalizeAIGatewayResponse() function handles this for both streaming and non-streaming responses.

This differs from the observability-focused normalization (Mapper Type Detection / Request Parsing) in that Cross-Provider Transform operates at the proxy level on live traffic, while observability normalization operates at the logging level on stored request/response pairs. Cross-Provider Transform must handle streaming SSE conversion, cache control annotations, tool/function mapping, and reasoning/thinking configuration across providers.

Usage

Use Cross-Provider Transform within the AI Gateway when routing an OpenAI-format request to a non-OpenAI provider, and when normalizing the response back before returning it to the caller. Also used in the prompt playground when executing prompts against different providers. The response normalization is also used for usage/token count normalization across all providers.

Theoretical Basis

Cross-Provider Transform is grounded in the adapter pattern applied to API request/response bodies. The key design decisions are:

OpenAI as Lingua Franca

OpenAI's Chat Completions format is chosen as the canonical input format because it is the most widely adopted LLM API format. All other provider formats are mapped from OpenAI rather than creating a custom intermediate representation. This reduces the number of required transformers from O(n^2) provider-to-provider mappings to O(n) OpenAI-to-provider mappings.

Asymmetric Transformation

Request transformation and response normalization are not symmetric inverses. The request transform (toAnthropic, toGoogle) is a structural conversion that handles:

• System message extraction -- Anthropic requires system messages as a separate top-level parameter, not in the messages array
• Content format mapping -- OpenAI's multimodal content parts (text, image_url) map to Anthropic's content blocks (text, image with source) and Gemini's parts (text, inlineData)
• Tool format conversion -- OpenAI's tools[].function.parameters maps to Anthropic's tools[].input_schema and Gemini's functionDeclarations[].parameters
• Reasoning/thinking configuration -- OpenAI's reasoning_effort maps to Anthropic's thinking block and Gemini's thinkingConfig
• Cache control -- Anthropic's prompt caching with cache_control: { type: "ephemeral", ttl: "5m" } breakpoints

Response normalization must handle provider-native streaming formats (Anthropic SSE events, Google streaming responses) and convert them to OpenAI SSE format, as well as normalizing usage/token counts using provider-specific usage processors.

Streaming Conversion

For streaming responses, dedicated converter classes (AnthropicToOpenAIStreamConverter, GoogleToOpenAIStreamConverter) process SSE event lines incrementally, mapping provider-specific event types to OpenAI ChatCompletionChunk objects. AWS Bedrock's binary event stream format receives special handling with base64 decoding of event payloads.

Responses API Support

When the body mapping is set to "RESPONSES", the normalized OpenAI Chat Completions format is further converted to the OpenAI Responses API format using toResponses() for non-streaming and ChatToResponsesStreamConverter for streaming, unless the provider natively supports the Responses API.

Related Pages

Implemented By

• Implementation:Helicone_Helicone_Cross_Provider_Transform_Functions