litellm - 💡(How to fix) Fix fix(anthropic): support top-level cache_control in /v1/messages for automatic prompt caching [1 participants]

Description

PR #22442 added cache_control support to map_openai_params() in litellm/llms/anthropic/chat/transformation.py. This resolves the issue for the OpenAI-compatible path (/v1/chat/completions), but the native Anthropic path (/v1/messages) still rejects cache_control as a top-level field.

The failure occurs during Pydantic validation in the /v1/messages request model, before the request reaches the provider layer.

Error

cache_control: Extra inputs are not permitted

Full error:

status_code: 400
body: {'error': {'message': '{"message":"cache_control: Extra inputs are not permitted"}'}}

Steps to Reproduce

Using pydantic-ai's AnthropicProvider pointing at a LiteLLM proxy, with:

AnthropicModelSettings(anthropic_cache="1h")

This results in the following request being sent:

POST /v1/messages?beta=true
{
  "model": "us.anthropic.claude-sonnet-4-6",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "cache_control": {
    "type": "ephemeral",
    "ttl": "1h"
  }
}

This request works when sent directly to Anthropic, but fails via LiteLLM proxy.

LiteLLM version: >=1.83.7-stable (tested on latest as of April 2026)

Root Cause

map_openai_params() (updated in #22442) is only invoked for the OpenAI-compatible path (/v1/chat/completions).

The native /v1/messages endpoint uses a separate Pydantic request model which does not include cache_control as an allowed top-level field. As a result, the request fails validation before reaching the transformation or provider layers.

Expected Behavior

cache_control should be accepted in the /v1/messages request schema and forwarded unchanged to the Anthropic provider, consistent with Anthropic's automatic prompt caching API:

https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching#automatic-caching

Workaround

Block-level caching via:

• anthropic_cache_instructions
• anthropic_cache_tool_definitions

works correctly, since these embed cache_control inside content blocks that are already supported by the /v1/messages schema.

Suggested Fix

Add cache_control as an optional field to the /v1/messages request model (e.g., AnthropicMessagesRequest) and ensure it is forwarded to the Anthropic provider call.

Example:

cache_control: Optional[Dict[Literal["type", "ttl"], str]] = None

This should make behavior consistent across both /v1/chat/completions and /v1/messages.