From d0d09e037efb654ad7060eb16e030c7411d1cf15 Mon Sep 17 00:00:00 2001 From: Chesars Date: Tue, 9 Dec 2025 11:36:03 -0300 Subject: [PATCH 1/5] docs: clarify when to use openai/responses/ prefix for built-in tools 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. Changes: - Explain the `mode` property from model_prices_and_context_window.json - List models with mode: responses vs mode: chat - Add example showing the common error and how to fix it - Add SDK example using the prefix with gpt-4o - Update proxy example with both automatic and prefix-based configs - Fix invalid trailing comma in original JSON example --- docs/my-website/docs/providers/openai.md | 86 +++++++++++++++++++++--- 1 file changed, 77 insertions(+), 9 deletions(-) diff --git a/docs/my-website/docs/providers/openai.md b/docs/my-website/docs/providers/openai.md index bed4cd0aa5b..adddc3efc4a 100644 --- a/docs/my-website/docs/providers/openai.md +++ b/docs/my-website/docs/providers/openai.md @@ -632,7 +632,9 @@ curl -X POST 'http://0.0.0.0:4000/chat/completions' \ ## OpenAI Chat Completion to Responses API Bridge -Call any Responses API model from OpenAI's `/chat/completions` endpoint. +LiteLLM offers a chat completion to Responses API bridge. This lets you use the completion interface while calling the Responses API under the hood. + +This is useful when you want to use [Responses API](https://platform.openai.com/docs/api-reference/responses) specific features (like built-in tools, web search preview, or code interpreter). :::tip gpt-5.4 + reasoning_effort + function tools @@ -649,12 +651,52 @@ response = litellm.completion( ::: +### When to use the `openai/responses/` prefix + +Each model has a `mode` property defined in [`model_prices_and_context_window.json`](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json) that determines which API endpoint it uses by default: + +- **`mode: responses`** - Model automatically uses the Responses API +- **`mode: chat`** - Model defaults to the Chat Completions API + +**Models with `mode: responses`** (automatic Responses API): +- `o3-deep-research`, `o4-mini-deep-research` +- `o1-pro`, `o3-pro` +- `gpt-5.1-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max` +- `codex-mini-latest` + +**Models with `mode: chat`** (require `openai/responses/` prefix for built-in tools): +- `gpt-4o`, `gpt-4o-mini`, `gpt-4.1`, `gpt-4.1-mini` +- `gpt-5`, `gpt-5-mini` +- `o3`, `o4-mini` + +To use built-in tools like `web_search_preview` with `mode: chat` models, add the `openai/responses/` prefix: + +```python +# This will FAIL - gpt-4o has mode: chat, uses Chat Completions API +response = litellm.completion( + model="gpt-4o", + tools=[{"type": "web_search_preview"}], # Not supported in Chat Completions + ... +) + +# This will WORK - prefix forces Responses API +response = litellm.completion( + model="openai/responses/gpt-4o", + tools=[{"type": "web_search_preview"}], # Supported in Responses API + ... +) +``` + +### Examples + +**Using a model with `mode: responses` (automatic):** + ```python import litellm -import os +import os os.environ["OPENAI_API_KEY"] = "sk-1234" @@ -668,6 +710,26 @@ response = litellm.completion( ) print(response) ``` + +**Using a model with `mode: chat` (requires prefix):** + +```python +import litellm +import os + +os.environ["OPENAI_API_KEY"] = "sk-1234" + +# Use the openai/responses/ prefix to enable built-in tools +response = litellm.completion( + model="openai/responses/gpt-4o", + messages=[{"role": "user", "content": "What is the weather in Paris today?"}], + tools=[ + {"type": "web_search_preview"}, + ], +) +print(response) +``` + @@ -675,10 +737,17 @@ print(response) ```yaml model_list: - - model_name: openai-model + # Model with mode: responses (automatic) + - model_name: o3-deep-research litellm_params: model: o3-deep-research-2025-06-26 api_key: os.environ/OPENAI_API_KEY + + # Model with mode: chat (use prefix for built-in tools) + - model_name: gpt-4o-with-tools + litellm_params: + model: openai/responses/gpt-4o + api_key: os.environ/OPENAI_API_KEY ``` 2. Start the proxy @@ -693,15 +762,14 @@ litellm --config config.yaml curl -X POST 'http://0.0.0.0:4000/chat/completions' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer sk-1234' \ --d '{ - "model": "openai-model", +-d '{ + "model": "gpt-4o-with-tools", "messages": [ - {"role": "user", "content": "What is the capital of France?"} + {"role": "user", "content": "What is the weather in Paris today?"} ], "tools": [ - {"type": "web_search_preview"}, - {"type": "code_interpreter", "container": {"type": "auto"}}, - ], + {"type": "web_search_preview"} + ] }' ``` From 01a6c707a32f427c3c2b07cce07e6d863d87715f Mon Sep 17 00:00:00 2001 From: Chesars Date: Wed, 11 Mar 2026 13:34:56 -0300 Subject: [PATCH 2/5] docs: restore gpt-5.4 reasoning_effort tip lost during rebase --- docs/my-website/docs/providers/openai.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/my-website/docs/providers/openai.md b/docs/my-website/docs/providers/openai.md index adddc3efc4a..576a0dcb8ff 100644 --- a/docs/my-website/docs/providers/openai.md +++ b/docs/my-website/docs/providers/openai.md @@ -689,6 +689,21 @@ response = litellm.completion( ### Examples +:::tip gpt-5.4 + reasoning_effort + function tools + +OpenAI does not support `reasoning_effort` with function tools for `gpt-5.4` in `/v1/chat/completions`. Use the responses bridge instead: + +```python +response = litellm.completion( + model="openai/responses/gpt-5.4", # routes to /v1/responses + messages=[{"role": "user", "content": "What's the weather?"}], + tools=[...], + reasoning_effort="low", +) +``` + +::: + From 9e7a6a73ed7051c1b09694a294fa36439f7cc6e6 Mon Sep 17 00:00:00 2001 From: Chesars Date: Wed, 11 Mar 2026 13:48:47 -0300 Subject: [PATCH 3/5] docs: remove duplicate gpt-5.4 tip block --- docs/my-website/docs/providers/openai.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/docs/my-website/docs/providers/openai.md b/docs/my-website/docs/providers/openai.md index 576a0dcb8ff..adddc3efc4a 100644 --- a/docs/my-website/docs/providers/openai.md +++ b/docs/my-website/docs/providers/openai.md @@ -689,21 +689,6 @@ response = litellm.completion( ### Examples -:::tip gpt-5.4 + reasoning_effort + function tools - -OpenAI does not support `reasoning_effort` with function tools for `gpt-5.4` in `/v1/chat/completions`. Use the responses bridge instead: - -```python -response = litellm.completion( - model="openai/responses/gpt-5.4", # routes to /v1/responses - messages=[{"role": "user", "content": "What's the weather?"}], - tools=[...], - reasoning_effort="low", -) -``` - -::: - From 274bf4249378adc5790f7e508e462c375a020bf5 Mon Sep 17 00:00:00 2001 From: Cesar Garcia <128240629+Chesars@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:13:56 -0300 Subject: [PATCH 4/5] Update docs/my-website/docs/providers/openai.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- docs/my-website/docs/providers/openai.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/my-website/docs/providers/openai.md b/docs/my-website/docs/providers/openai.md index adddc3efc4a..8c4108455ab 100644 --- a/docs/my-website/docs/providers/openai.md +++ b/docs/my-website/docs/providers/openai.md @@ -675,17 +675,18 @@ To use built-in tools like `web_search_preview` with `mode: chat` models, add th # This will FAIL - gpt-4o has mode: chat, uses Chat Completions API response = litellm.completion( model="gpt-4o", + messages=[{"role": "user", "content": "What is the weather in Paris today?"}], tools=[{"type": "web_search_preview"}], # Not supported in Chat Completions - ... + # ... other kwargs ) # This will WORK - prefix forces Responses API response = litellm.completion( model="openai/responses/gpt-4o", + messages=[{"role": "user", "content": "What is the weather in Paris today?"}], tools=[{"type": "web_search_preview"}], # Supported in Responses API - ... + # ... other kwargs ) -``` ### Examples From f9a538b5839d7d9c70ea4127775a4ab4e6b91187 Mon Sep 17 00:00:00 2001 From: Chesars Date: Wed, 11 Mar 2026 14:15:54 -0300 Subject: [PATCH 5/5] fix(docs): close unclosed code block before Examples heading --- docs/my-website/docs/providers/openai.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/my-website/docs/providers/openai.md b/docs/my-website/docs/providers/openai.md index 8c4108455ab..9d557303ef2 100644 --- a/docs/my-website/docs/providers/openai.md +++ b/docs/my-website/docs/providers/openai.md @@ -687,6 +687,7 @@ response = litellm.completion( tools=[{"type": "web_search_preview"}], # Supported in Responses API # ... other kwargs ) +``` ### Examples