Implementation:BerriAI Litellm Responses Utils

Property	Value
sources	litellm/responses/utils.py
domains	Responses API, Utilities, Parameter Mapping, Usage Transformation
last_updated	2026-02-15 16:00 GMT

Overview

The Responses Utils module provides utility classes for constructing Responses API requests, encoding and decoding response IDs with provider metadata, converting text formats, extracting MCP headers, and transforming Response API usage data to chat completion usage format.

Description

This module contains two primary utility classes. ResponsesAPIRequestUtils handles request construction: validating parameters against provider-supported lists, filtering and mapping optional parameters, building and decoding base64-encoded response IDs that embed custom_llm_provider and model_id, converting Pydantic text_format models to the Responses API text parameter format, and extracting MCP authentication headers from requests. ResponseAPILoggingUtils handles the transformation of Response API usage objects (which use input_tokens/output_tokens) to the standard chat completion Usage format (which uses prompt_tokens/completion_tokens), including mapping of token detail breakdowns.

Usage

Import this module when building Responses API requests, when you need to encode or decode response IDs that carry LiteLLM routing metadata, or when transforming usage data between Response API and chat completion formats for logging and billing purposes.

Code Reference

Source Location

Property	Value
Repository	github.com/BerriAI/litellm
File	litellm/responses/utils.py
Lines	498
Module	litellm.responses.utils

Signature

class ResponsesAPIRequestUtils:
    @staticmethod
    def get_optional_params_responses_api(
        model: str,
        responses_api_provider_config: BaseResponsesAPIConfig,
        response_api_optional_params: ResponsesAPIOptionalRequestParams,
        allowed_openai_params: Optional[List[str]] = None,
    ) -> Dict

    @staticmethod
    def get_requested_response_api_optional_param(
        params: Dict[str, Any],
    ) -> ResponsesAPIOptionalRequestParams

    @staticmethod
    def _update_responses_api_response_id_with_model_id(
        responses_api_response: Union[ResponsesAPIResponse, Dict[str, Any]],
        custom_llm_provider: Optional[str],
        litellm_metadata: Optional[Dict[str, Any]] = None,
    ) -> Union[ResponsesAPIResponse, Dict[str, Any]]

    @staticmethod
    def _decode_responses_api_response_id(
        response_id: str,
    ) -> DecodedResponseId

    @staticmethod
    def convert_text_format_to_text_param(
        text_format: Optional[Union[Type[BaseModel], dict]],
        text: Optional[ResponseText] = None,
    ) -> Optional[ResponseText]

    @staticmethod
    def extract_mcp_headers_from_request(
        secret_fields: Optional[Dict[str, Any]],
        tools: Optional[Iterable[Any]],
    ) -> tuple[Optional[str], Optional[Dict], Optional[Dict], Optional[Dict]]

class ResponseAPILoggingUtils:
    @staticmethod
    def _is_response_api_usage(usage: Union[dict, ResponseAPIUsage]) -> bool

    @staticmethod
    def _transform_response_api_usage_to_chat_usage(
        usage_input: Optional[Union[dict, ResponseAPIUsage]],
    ) -> Usage

Import

from litellm.responses.utils import ResponsesAPIRequestUtils, ResponseAPILoggingUtils

I/O Contract

Inputs

Method	Key Parameters	Description
get_optional_params_responses_api	model, provider_config, optional_params	Maps and validates optional params against provider support
_update_responses_api_response_id_with_model_id	response, custom_llm_provider, litellm_metadata	Encodes provider and model info into response ID
_decode_responses_api_response_id	response_id (str)	Decodes a base64-encoded response ID
convert_text_format_to_text_param	text_format (Pydantic model or dict)	Converts structured output format to text parameter
extract_mcp_headers_from_request	secret_fields, tools	Extracts MCP auth headers from request context
_transform_response_api_usage_to_chat_usage	usage (ResponseAPIUsage or dict)	Transforms Response API usage to chat completion format

Outputs

Method	Return Type	Description
get_optional_params_responses_api	Dict	Provider-mapped parameters
_update_responses_api_response_id_with_model_id	ResponsesAPIResponse or Dict	Response with encoded ID
_decode_responses_api_response_id	DecodedResponseId	Dict with custom_llm_provider, model_id, response_id
convert_text_format_to_text_param	Optional[ResponseText]	Text parameter with format spec
_transform_response_api_usage_to_chat_usage	Usage	Chat completion usage with prompt/completion tokens

Usage Examples

from litellm.responses.utils import ResponsesAPIRequestUtils

# Decode a LiteLLM-encoded response ID
decoded = ResponsesAPIRequestUtils._decode_responses_api_response_id(
    response_id="resp_bGl0ZWxsbTpjdXN0b21fbGxtX3Byb3ZpZGVyOm9wZW5haTttb2RlbF9pZDptb2RlbC0xMjM7cmVzcG9uc2VfaWQ6cmVzcF9hYmMxMjM="
)
print(decoded)
# {'custom_llm_provider': 'openai', 'model_id': 'model-123', 'response_id': 'resp_abc123'}

from litellm.responses.utils import ResponseAPILoggingUtils

# Transform Response API usage to chat completion format
usage = ResponseAPILoggingUtils._transform_response_api_usage_to_chat_usage(
    {"input_tokens": 100, "output_tokens": 50, "total_tokens": 150}
)
print(usage.prompt_tokens)   # 100
print(usage.completion_tokens)  # 50

Related Pages

• BerriAI_Litellm_Responses_API -- The main Responses API module that uses these utilities for request construction and response processing
• BerriAI_Litellm_Responses_Streaming_Iterator -- Streaming iterators that use response ID encoding from this module