feat(api): adds GPT-5 and new API features: platform.openai.com/docs/guides/gpt-5

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-d6a16b25b969c3e5382e7d413de15bf83d5f7534d5c3ecce64d3a7e847418f9e.yml
-openapi_spec_hash: 0c0bcf4aee9ca2a948dd14b890dfe728
-config_hash: aeff9289bd7f8c8482e4d738c3c2fde1
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-f5c45f4ae5c2075cbc603d6910bba3da31c23714c209fbd3fd82a94f634a126b.yml
+openapi_spec_hash: 3eb8d86c06f0bb5e1190983e5acfc9ba
+config_hash: 9a64321968e21ed72f5c0e02164ea00d

api.md

@@ -6,6 +6,7 @@ from openai.types import (
     ChatModel,
     ComparisonFilter,
     CompoundFilter,
+    CustomToolInputFormat,
     ErrorObject,
     FunctionDefinition,
     FunctionParameters,
@@ -15,6 +16,8 @@ from openai.types import (
     ResponseFormatJSONObject,
     ResponseFormatJSONSchema,
     ResponseFormatText,
+    ResponseFormatTextGrammar,
+    ResponseFormatTextPython,
     ResponsesModel,
 )
 ```
@@ -46,6 +49,7 @@ Types:
 ```python
 from openai.types.chat import (
     ChatCompletion,
+    ChatCompletionAllowedToolChoice,
     ChatCompletionAssistantMessageParam,
     ChatCompletionAudio,
     ChatCompletionAudioParam,
@@ -55,15 +59,20 @@ from openai.types.chat import (
     ChatCompletionContentPartInputAudio,
     ChatCompletionContentPartRefusal,
     ChatCompletionContentPartText,
+    ChatCompletionCustomTool,
     ChatCompletionDeleted,
     ChatCompletionDeveloperMessageParam,
     ChatCompletionFunctionCallOption,
     ChatCompletionFunctionMessageParam,
+    ChatCompletionFunctionTool,
     ChatCompletionMessage,
+    ChatCompletionMessageCustomToolCall,
+    ChatCompletionMessageFunctionToolCall,
     ChatCompletionMessageParam,
     ChatCompletionMessageToolCall,
     ChatCompletionModality,
     ChatCompletionNamedToolChoice,
+    ChatCompletionNamedToolChoiceCustom,
     ChatCompletionPredictionContent,
     ChatCompletionRole,
     ChatCompletionStoreMessage,
@@ -74,6 +83,7 @@ from openai.types.chat import (
     ChatCompletionToolChoiceOption,
     ChatCompletionToolMessageParam,
     ChatCompletionUserMessageParam,
+    ChatCompletionAllowedTools,
     ChatCompletionReasoningEffort,
 )
 ```
@@ -719,6 +729,7 @@ Types:
 ```python
 from openai.types.responses import (
     ComputerTool,
+    CustomTool,
     EasyInputMessage,
     FileSearchTool,
     FunctionTool,
@@ -741,6 +752,10 @@ from openai.types.responses import (
     ResponseContentPartAddedEvent,
     ResponseContentPartDoneEvent,
     ResponseCreatedEvent,
+    ResponseCustomToolCall,
+    ResponseCustomToolCallInputDeltaEvent,
+    ResponseCustomToolCallInputDoneEvent,
+    ResponseCustomToolCallOutput,
     ResponseError,
     ResponseErrorEvent,
     ResponseFailedEvent,
@@ -810,6 +825,8 @@ from openai.types.responses import (
     ResponseWebSearchCallInProgressEvent,
     ResponseWebSearchCallSearchingEvent,
     Tool,
+    ToolChoiceAllowed,
+    ToolChoiceCustom,
     ToolChoiceFunction,
     ToolChoiceMcp,
     ToolChoiceOptions,

src/openai/lib/_parsing/_completions.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import logging
 from typing import TYPE_CHECKING, Any, Iterable, cast
 from typing_extensions import TypeVar, TypeGuard, assert_never
 
@@ -19,14 +20,15 @@
     ParsedChatCompletion,
     ChatCompletionMessage,
     ParsedFunctionToolCall,
-    ChatCompletionToolParam,
     ParsedChatCompletionMessage,
+    ChatCompletionFunctionToolParam,
     completion_create_params,
 )
 from ..._exceptions import LengthFinishReasonError, ContentFilterFinishReasonError
 from ...types.shared_params import FunctionDefinition
 from ...types.chat.completion_create_params import ResponseFormat as ResponseFormatParam
-from ...types.chat.chat_completion_message_tool_call import Function
+from ...types.chat.chat_completion_tool_param import ChatCompletionToolParam
+from ...types.chat.chat_completion_message_function_tool_call import Function
 
 ResponseFormatT = TypeVar(
     "ResponseFormatT",
@@ -35,12 +37,36 @@
 )
 _default_response_format: None = None
 
+log: logging.Logger = logging.getLogger("openai.lib.parsing")
+
+
+def is_strict_chat_completion_tool_param(
+    tool: ChatCompletionToolParam,
+) -> TypeGuard[ChatCompletionFunctionToolParam]:
+    """Check if the given tool is a strict ChatCompletionFunctionToolParam."""
+    if not tool["type"] == "function":
+        return False
+    if tool["function"].get("strict") is not True:
+        return False
+
+    return True
+
+
+def select_strict_chat_completion_tools(
+    tools: Iterable[ChatCompletionToolParam] | NotGiven = NOT_GIVEN,
+) -> Iterable[ChatCompletionFunctionToolParam] | NotGiven:
+    """Select only the strict ChatCompletionFunctionToolParams from the given tools."""
+    if not is_given(tools):
+        return NOT_GIVEN
+
+    return [t for t in tools if is_strict_chat_completion_tool_param(t)]
+
 
 def validate_input_tools(
     tools: Iterable[ChatCompletionToolParam] | NotGiven = NOT_GIVEN,
-) -> None:
+) -> Iterable[ChatCompletionFunctionToolParam] | NotGiven:
     if not is_given(tools):
-        return
+        return NOT_GIVEN
 
     for tool in tools:
         if tool["type"] != "function":
@@ -54,6 +80,8 @@ def validate_input_tools(
                 f"`{tool['function']['name']}` is not strict. Only `strict` function tools can be auto-parsed"
             )
 
+    return cast(Iterable[ChatCompletionFunctionToolParam], tools)
+
 
 def parse_chat_completion(
     *,
@@ -95,6 +123,14 @@ def parse_chat_completion(
                             type_=ParsedFunctionToolCall,
                         )
                     )
+                elif tool_call.type == "custom":
+                    # warn user that custom tool calls are not callable here
+                    log.warning(
+                        "Custom tool calls are not callable. Ignoring tool call: %s - %s",
+                        tool_call.id,
+                        tool_call.custom.name,
+                        stacklevel=2,
+                    )
                 elif TYPE_CHECKING:  # type: ignore[unreachable]
                     assert_never(tool_call)
                 else:
@@ -129,13 +165,15 @@ def parse_chat_completion(
     )
 
 
-def get_input_tool_by_name(*, input_tools: list[ChatCompletionToolParam], name: str) -> ChatCompletionToolParam | None:
-    return next((t for t in input_tools if t.get("function", {}).get("name") == name), None)
+def get_input_tool_by_name(
+    *, input_tools: list[ChatCompletionToolParam], name: str
+) -> ChatCompletionFunctionToolParam | None:
+    return next((t for t in input_tools if t["type"] == "function" and t.get("function", {}).get("name") == name), None)
 
 
 def parse_function_tool_arguments(
     *, input_tools: list[ChatCompletionToolParam], function: Function | ParsedFunction
-) -> object:
+) -> object | None:
     input_tool = get_input_tool_by_name(input_tools=input_tools, name=function.name)
     if not input_tool:
         return None
@@ -149,7 +187,7 @@ def parse_function_tool_arguments(
     if not input_fn.get("strict"):
         return None
 
-    return json.loads(function.arguments)
+    return json.loads(function.arguments)  # type: ignore[no-any-return]
 
 
 def maybe_parse_content(
@@ -209,6 +247,9 @@ def is_response_format_param(response_format: object) -> TypeGuard[ResponseForma
 
 
 def is_parseable_tool(input_tool: ChatCompletionToolParam) -> bool:
+    if input_tool["type"] != "function":
+        return False
+
     input_fn = cast(object, input_tool.get("function"))
     if isinstance(input_fn, PydanticFunctionTool):
         return True

src/openai/lib/_parsing/_responses.py

@@ -110,6 +110,7 @@ def parse_response(
             or output.type == "local_shell_call"
             or output.type == "mcp_list_tools"
             or output.type == "exec"
+            or output.type == "custom_tool_call"
         ):
             output_list.append(output)
         elif TYPE_CHECKING:  # type: ignore

src/openai/lib/_tools.py

@@ -5,7 +5,7 @@
 import pydantic
 
 from ._pydantic import to_strict_json_schema
-from ..types.chat import ChatCompletionToolParam
+from ..types.chat import ChatCompletionFunctionToolParam
 from ..types.shared_params import FunctionDefinition
 from ..types.responses.function_tool_param import FunctionToolParam as ResponsesFunctionToolParam
 
@@ -42,7 +42,7 @@ def pydantic_function_tool(
     *,
     name: str | None = None,  # inferred from class name by default
     description: str | None = None,  # inferred from class docstring by default
-) -> ChatCompletionToolParam:
+) -> ChatCompletionFunctionToolParam:
     if description is None:
         # note: we intentionally don't use `.getdoc()` to avoid
         # including pydantic's docstrings

src/openai/lib/streaming/chat/_completions.py

@@ -37,11 +37,12 @@
     parse_function_tool_arguments,
 )
 from ...._streaming import Stream, AsyncStream
-from ....types.chat import ChatCompletionChunk, ParsedChatCompletion, ChatCompletionToolParam
+from ....types.chat import ChatCompletionChunk, ParsedChatCompletion
 from ...._exceptions import LengthFinishReasonError, ContentFilterFinishReasonError
 from ....types.chat.chat_completion import ChoiceLogprobs
 from ....types.chat.chat_completion_chunk import Choice as ChoiceChunk
 from ....types.chat.completion_create_params import ResponseFormat as ResponseFormatParam
+from ....types.chat.chat_completion_tool_param import ChatCompletionToolParam
 
 
 class ChatCompletionStream(Generic[ResponseFormatT]):

src/openai/resources/beta/assistants.py

@@ -96,12 +96,11 @@ def create(
 
           name: The name of the assistant. The maximum length is 256 characters.
 
-          reasoning_effort: **o-series models only**
-
-              Constrains effort on reasoning for
+          reasoning_effort: Constrains effort on reasoning for
               [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
-              supported values are `low`, `medium`, and `high`. Reducing reasoning effort can
-              result in faster responses and fewer tokens used on reasoning in a response.
+              supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
+              effort can result in faster responses and fewer tokens used on reasoning in a
+              response.
 
           response_format: Specifies the format that the model must output. Compatible with
               [GPT-4o](https://platform.openai.com/docs/models#gpt-4o),
@@ -220,6 +219,12 @@ def update(
         model: Union[
             str,
             Literal[
+                "gpt-5",
+                "gpt-5-mini",
+                "gpt-5-nano",
+                "gpt-5-2025-08-07",
+                "gpt-5-mini-2025-08-07",
+                "gpt-5-nano-2025-08-07",
                 "gpt-4.1",
                 "gpt-4.1-mini",
                 "gpt-4.1-nano",
@@ -298,12 +303,11 @@ def update(
 
           name: The name of the assistant. The maximum length is 256 characters.
 
-          reasoning_effort: **o-series models only**
-
-              Constrains effort on reasoning for
+          reasoning_effort: Constrains effort on reasoning for
               [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
-              supported values are `low`, `medium`, and `high`. Reducing reasoning effort can
-              result in faster responses and fewer tokens used on reasoning in a response.
+              supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
+              effort can result in faster responses and fewer tokens used on reasoning in a
+              response.
 
           response_format: Specifies the format that the model must output. Compatible with
               [GPT-4o](https://platform.openai.com/docs/models#gpt-4o),
@@ -545,12 +549,11 @@ async def create(
 
           name: The name of the assistant. The maximum length is 256 characters.
 
-          reasoning_effort: **o-series models only**
-
-              Constrains effort on reasoning for
+          reasoning_effort: Constrains effort on reasoning for
               [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
-              supported values are `low`, `medium`, and `high`. Reducing reasoning effort can
-              result in faster responses and fewer tokens used on reasoning in a response.
+              supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
+              effort can result in faster responses and fewer tokens used on reasoning in a
+              response.
 
           response_format: Specifies the format that the model must output. Compatible with
               [GPT-4o](https://platform.openai.com/docs/models#gpt-4o),
@@ -669,6 +672,12 @@ async def update(
         model: Union[
             str,
             Literal[
+                "gpt-5",
+                "gpt-5-mini",
+                "gpt-5-nano",
+                "gpt-5-2025-08-07",
+                "gpt-5-mini-2025-08-07",
+                "gpt-5-nano-2025-08-07",
                 "gpt-4.1",
                 "gpt-4.1-mini",
                 "gpt-4.1-nano",
@@ -747,12 +756,11 @@ async def update(
 
           name: The name of the assistant. The maximum length is 256 characters.
 
-          reasoning_effort: **o-series models only**
-
-              Constrains effort on reasoning for
+          reasoning_effort: Constrains effort on reasoning for
               [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
-              supported values are `low`, `medium`, and `high`. Reducing reasoning effort can
-              result in faster responses and fewer tokens used on reasoning in a response.
+              supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
+              effort can result in faster responses and fewer tokens used on reasoning in a
+              response.
 
           response_format: Specifies the format that the model must output. Compatible with
               [GPT-4o](https://platform.openai.com/docs/models#gpt-4o),