docs: clarify when to use openai/responses/ prefix for built-in tools

[Chesars]

Relevant issues

#17583

Pre-Submission checklist

• N/A - Documentation only change, no code tests needed
• N/A - Documentation only change
• N/A - Documentation only change
• My PR's scope is as isolated as possible, it only solves 1 specific problem

Type

📖 Documentation

Summary

The existing documentation for the Responses API bridge only showed examples with models that have mode: responses (like o3-deep-research), which work automatically. This update clarifies that models with mode: chat (like gpt-4o, gpt-5) require the openai/responses/ prefix to use built-in tools like web_search_preview.

What's added:

• Explanation of the mode property from model_prices_and_context_window.json
• List of models with mode: responses vs mode: chat
• Example showing the common error and how to fix it
• SDK example using the prefix with gpt-4o
• Updated proxy example with both automatic and prefix-based configs
• Fixed invalid trailing comma in original JSON example

Current docs:

Call any Responses API model from OpenAI's /chat/completions endpoint.

after:

Each model has a mode property defined in model_prices_and_context_window.json that specifies which API endpoint it uses by default:

• mode: responses - Model automatically uses the Responses API
• mode: chat - Model defaults to the Chat Completions API

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
litellm	Ready	Preview	Comment	Dec 9, 2025 2:37pm

[mmabrouk]

I wouldn't write like this. This is too verbose and not very helpful to the user. I would instead use:

LiteLLM offers a chat completion to response API bridge mode. This mode lets you use the completion method interface while calling the OpenAI response API under the hood.

Using this bridge makes sense when you want to use response API specific features (like built-in tools, web search preview, or code interpreter) or when you need models that are only available through the response API.

How to force the use of the response API bridge

Use the 'openai/responses' prefix in the model name. For example:

response = litellm.completion(
    model="openai/responses/gpt-4o",
    tools=[{"type": "web_search_preview"}],  # Supported in Responses API
    ...
)

[mmabrouk]

This is litellm internals, not helpful to the user. I would remove.

[mmabrouk]

This is worth its own section under how to use response API. Say that when you call these models, the response API gets used automatically under the hood.

@krrishdholakia I would strongly recommend changing this behavior and making it opt-in through a parameter. See my comment here

[mmabrouk]

Thanks for the PR @Chesars ! I have added a couple of comments. Overall I feel it's too verbose and not very well organized. I offered some possible edits.

Note though that I am not a maintainer, so not sure what are the best practices / organization for the documentation!