release: 2.0.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.109.1"
+  ".": "2.0.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 118
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-410219ea680089f02bb55163c673919703f946c3d6ad7ff5d6f607121d5287d5.yml
-openapi_spec_hash: 2b3eee95d3f6796c7a61dfddf694a59a
-config_hash: 666d6bb4b564f0d9d431124b5d1a0665
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-49233088b5e73dbb96bf7af27be3d4547632e3db1c2b00f14184900613325bbc.yml
+openapi_spec_hash: b34f14b141d5019244112901c5c7c2d8
+config_hash: 94e9ba08201c3d1ca46e093e6a0138fa

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.0.0 (2025-09-30)
+
+Full Changelog: [v1.109.1...v2.0.0](https://github.com/openai/openai-python/compare/v1.109.1...v2.0.0)
+
+### ⚠ BREAKING CHANGES
+
+* **api:** `ResponseFunctionToolCallOutputItem.output` and `ResponseCustomToolCallOutput.output` now return `string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>` instead of `string` only. This may break existing callsites that assume `output` is always a string.
+
+### Features
+
+* **api:** Support images and files for function call outputs in responses, BatchUsage ([4105376](https://github.com/openai/openai-python/commit/4105376a60293581371fd5635b805b717d24aa19))
+
 ## 1.109.1 (2025-09-24)
 
 Full Changelog: [v1.109.0...v1.109.1](https://github.com/openai/openai-python/compare/v1.109.0...v1.109.1)

api.md

@@ -687,7 +687,7 @@ Methods:
 Types:
 
 ```python
-from openai.types import Batch, BatchError, BatchRequestCounts
+from openai.types import Batch, BatchError, BatchRequestCounts, BatchUsage
 ```
 
 Methods:
@@ -769,6 +769,8 @@ from openai.types.responses import (
     ResponseFormatTextJSONSchemaConfig,
     ResponseFunctionCallArgumentsDeltaEvent,
     ResponseFunctionCallArgumentsDoneEvent,
+    ResponseFunctionCallOutputItem,
+    ResponseFunctionCallOutputItemList,
     ResponseFunctionToolCall,
     ResponseFunctionToolCallItem,
     ResponseFunctionToolCallOutputItem,
@@ -784,11 +786,14 @@ from openai.types.responses import (
     ResponseInputAudio,
     ResponseInputContent,
     ResponseInputFile,
+    ResponseInputFileContent,
     ResponseInputImage,
+    ResponseInputImageContent,
     ResponseInputItem,
     ResponseInputMessageContentList,
     ResponseInputMessageItem,
     ResponseInputText,
+    ResponseInputTextContent,
     ResponseItem,
     ResponseMcpCallArgumentsDeltaEvent,
     ResponseMcpCallArgumentsDoneEvent,

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai"
-version = "1.109.1"
+version = "2.0.0"
 description = "The official Python library for the openai API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/openai/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "openai"
-__version__ = "1.109.1"  # x-release-please-version
+__version__ = "2.0.0"  # x-release-please-version

src/openai/types/__init__.py

@@ -31,6 +31,7 @@
 from .moderation import Moderation as Moderation
 from .audio_model import AudioModel as AudioModel
 from .batch_error import BatchError as BatchError
+from .batch_usage import BatchUsage as BatchUsage
 from .file_object import FileObject as FileObject
 from .image_model import ImageModel as ImageModel
 from .file_content import FileContent as FileContent

src/openai/types/batch.py

@@ -5,6 +5,7 @@
 
 from .._models import BaseModel
 from .batch_error import BatchError
+from .batch_usage import BatchUsage
 from .shared.metadata import Metadata
 from .batch_request_counts import BatchRequestCounts
 
@@ -80,8 +81,24 @@ class Batch(BaseModel):
     a maximum length of 512 characters.
     """
 
+    model: Optional[str] = None
+    """Model ID used to process the batch, like `gpt-5-2025-08-07`.
+
+    OpenAI offers a wide range of models with different capabilities, performance
+    characteristics, and price points. Refer to the
+    [model guide](https://platform.openai.com/docs/models) to browse and compare
+    available models.
+    """
+
     output_file_id: Optional[str] = None
     """The ID of the file containing the outputs of successfully executed requests."""
 
     request_counts: Optional[BatchRequestCounts] = None
     """The request counts for different statuses within the batch."""
+
+    usage: Optional[BatchUsage] = None
+    """
+    Represents token usage details including input tokens, output tokens, a
+    breakdown of output tokens, and the total tokens used. Only populated on batches
+    created after September 7, 2025.
+    """

src/openai/types/batch_usage.py

@@ -0,0 +1,35 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from .._models import BaseModel
+
+__all__ = ["BatchUsage", "InputTokensDetails", "OutputTokensDetails"]
+
+
+class InputTokensDetails(BaseModel):
+    cached_tokens: int
+    """The number of tokens that were retrieved from the cache.
+
+    [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
+    """
+
+
+class OutputTokensDetails(BaseModel):
+    reasoning_tokens: int
+    """The number of reasoning tokens."""
+
+
+class BatchUsage(BaseModel):
+    input_tokens: int
+    """The number of input tokens."""
+
+    input_tokens_details: InputTokensDetails
+    """A detailed breakdown of the input tokens."""
+
+    output_tokens: int
+    """The number of output tokens."""
+
+    output_tokens_details: OutputTokensDetails
+    """A detailed breakdown of the output tokens."""
+
+    total_tokens: int
+    """The total number of tokens used."""

src/openai/types/responses/__init__.py

@@ -85,10 +85,13 @@
 from .response_conversation_param import ResponseConversationParam as ResponseConversationParam
 from .response_format_text_config import ResponseFormatTextConfig as ResponseFormatTextConfig
 from .response_function_tool_call import ResponseFunctionToolCall as ResponseFunctionToolCall
+from .response_input_file_content import ResponseInputFileContent as ResponseInputFileContent
 from .response_input_message_item import ResponseInputMessageItem as ResponseInputMessageItem
+from .response_input_text_content import ResponseInputTextContent as ResponseInputTextContent
 from .response_refusal_done_event import ResponseRefusalDoneEvent as ResponseRefusalDoneEvent
 from .response_function_web_search import ResponseFunctionWebSearch as ResponseFunctionWebSearch
 from .response_input_content_param import ResponseInputContentParam as ResponseInputContentParam
+from .response_input_image_content import ResponseInputImageContent as ResponseInputImageContent
 from .response_refusal_delta_event import ResponseRefusalDeltaEvent as ResponseRefusalDeltaEvent
 from .response_output_message_param import ResponseOutputMessageParam as ResponseOutputMessageParam
 from .response_output_refusal_param import ResponseOutputRefusalParam as ResponseOutputRefusalParam
@@ -106,8 +109,12 @@
 from .response_content_part_added_event import ResponseContentPartAddedEvent as ResponseContentPartAddedEvent
 from .response_format_text_config_param import ResponseFormatTextConfigParam as ResponseFormatTextConfigParam
 from .response_function_tool_call_param import ResponseFunctionToolCallParam as ResponseFunctionToolCallParam
+from .response_input_file_content_param import ResponseInputFileContentParam as ResponseInputFileContentParam
+from .response_input_text_content_param import ResponseInputTextContentParam as ResponseInputTextContentParam
 from .response_mcp_call_completed_event import ResponseMcpCallCompletedEvent as ResponseMcpCallCompletedEvent
+from .response_function_call_output_item import ResponseFunctionCallOutputItem as ResponseFunctionCallOutputItem
 from .response_function_web_search_param import ResponseFunctionWebSearchParam as ResponseFunctionWebSearchParam
+from .response_input_image_content_param import ResponseInputImageContentParam as ResponseInputImageContentParam
 from .response_reasoning_text_done_event import ResponseReasoningTextDoneEvent as ResponseReasoningTextDoneEvent
 from .response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall as ResponseCodeInterpreterToolCall
 from .response_input_message_content_list import ResponseInputMessageContentList as ResponseInputMessageContentList
@@ -131,6 +138,9 @@
 from .response_format_text_json_schema_config import (
     ResponseFormatTextJSONSchemaConfig as ResponseFormatTextJSONSchemaConfig,
 )
+from .response_function_call_output_item_list import (
+    ResponseFunctionCallOutputItemList as ResponseFunctionCallOutputItemList,
+)
 from .response_function_tool_call_output_item import (
     ResponseFunctionToolCallOutputItem as ResponseFunctionToolCallOutputItem,
 )
@@ -143,6 +153,9 @@
 from .response_mcp_list_tools_completed_event import (
     ResponseMcpListToolsCompletedEvent as ResponseMcpListToolsCompletedEvent,
 )
+from .response_function_call_output_item_param import (
+    ResponseFunctionCallOutputItemParam as ResponseFunctionCallOutputItemParam,
+)
 from .response_image_gen_call_generating_event import (
     ResponseImageGenCallGeneratingEvent as ResponseImageGenCallGeneratingEvent,
 )
@@ -212,6 +225,9 @@
 from .response_format_text_json_schema_config_param import (
     ResponseFormatTextJSONSchemaConfigParam as ResponseFormatTextJSONSchemaConfigParam,
 )
+from .response_function_call_output_item_list_param import (
+    ResponseFunctionCallOutputItemListParam as ResponseFunctionCallOutputItemListParam,
+)
 from .response_code_interpreter_call_code_done_event import (
     ResponseCodeInterpreterCallCodeDoneEvent as ResponseCodeInterpreterCallCodeDoneEvent,
 )

src/openai/types/responses/response_custom_tool_call_output.py

@@ -1,19 +1,30 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Optional
-from typing_extensions import Literal
+from typing import List, Union, Optional
+from typing_extensions import Literal, Annotated, TypeAlias
 
+from ..._utils import PropertyInfo
 from ..._models import BaseModel
+from .response_input_file import ResponseInputFile
+from .response_input_text import ResponseInputText
+from .response_input_image import ResponseInputImage
 
-__all__ = ["ResponseCustomToolCallOutput"]
+__all__ = ["ResponseCustomToolCallOutput", "OutputOutputContentList"]
+
+OutputOutputContentList: TypeAlias = Annotated[
+    Union[ResponseInputText, ResponseInputImage, ResponseInputFile], PropertyInfo(discriminator="type")
+]
 
 
 class ResponseCustomToolCallOutput(BaseModel):
     call_id: str
     """The call ID, used to map this custom tool call output to a custom tool call."""
 
-    output: str
-    """The output from the custom tool call generated by your code."""
+    output: Union[str, List[OutputOutputContentList]]
+    """
+    The output from the custom tool call generated by your code. Can be a string or
+    an list of output content.
+    """
 
     type: Literal["custom_tool_call_output"]
     """The type of the custom tool call output. Always `custom_tool_call_output`."""

src/openai/types/responses/response_custom_tool_call_output_param.py

@@ -2,17 +2,27 @@
 
 from __future__ import annotations
 
-from typing_extensions import Literal, Required, TypedDict
+from typing import Union, Iterable
+from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
-__all__ = ["ResponseCustomToolCallOutputParam"]
+from .response_input_file_param import ResponseInputFileParam
+from .response_input_text_param import ResponseInputTextParam
+from .response_input_image_param import ResponseInputImageParam
+
+__all__ = ["ResponseCustomToolCallOutputParam", "OutputOutputContentList"]
+
+OutputOutputContentList: TypeAlias = Union[ResponseInputTextParam, ResponseInputImageParam, ResponseInputFileParam]
 
 
 class ResponseCustomToolCallOutputParam(TypedDict, total=False):
     call_id: Required[str]
     """The call ID, used to map this custom tool call output to a custom tool call."""
 
-    output: Required[str]
-    """The output from the custom tool call generated by your code."""
+    output: Required[Union[str, Iterable[OutputOutputContentList]]]
+    """
+    The output from the custom tool call generated by your code. Can be a string or
+    an list of output content.
+    """
 
     type: Required[Literal["custom_tool_call_output"]]
     """The type of the custom tool call output. Always `custom_tool_call_output`."""

src/openai/types/responses/response_function_call_arguments_done_event.py

@@ -14,6 +14,9 @@ class ResponseFunctionCallArgumentsDoneEvent(BaseModel):
     item_id: str
     """The ID of the item."""
 
+    name: str
+    """The name of the function that was called."""
+
     output_index: int
     """The index of the output item."""
 

src/openai/types/responses/response_function_call_output_item.py

@@ -0,0 +1,16 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Union
+from typing_extensions import Annotated, TypeAlias
+
+from ..._utils import PropertyInfo
+from .response_input_file_content import ResponseInputFileContent
+from .response_input_text_content import ResponseInputTextContent
+from .response_input_image_content import ResponseInputImageContent
+
+__all__ = ["ResponseFunctionCallOutputItem"]
+
+ResponseFunctionCallOutputItem: TypeAlias = Annotated[
+    Union[ResponseInputTextContent, ResponseInputImageContent, ResponseInputFileContent],
+    PropertyInfo(discriminator="type"),
+]

src/openai/types/responses/response_function_call_output_item_list.py

@@ -0,0 +1,10 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List
+from typing_extensions import TypeAlias
+
+from .response_function_call_output_item import ResponseFunctionCallOutputItem
+
+__all__ = ["ResponseFunctionCallOutputItemList"]
+
+ResponseFunctionCallOutputItemList: TypeAlias = List[ResponseFunctionCallOutputItem]

src/openai/types/responses/response_function_call_output_item_list_param.py

@@ -0,0 +1,18 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import List, Union
+from typing_extensions import TypeAlias
+
+from .response_input_file_content_param import ResponseInputFileContentParam
+from .response_input_text_content_param import ResponseInputTextContentParam
+from .response_input_image_content_param import ResponseInputImageContentParam
+
+__all__ = ["ResponseFunctionCallOutputItemListParam", "ResponseFunctionCallOutputItemParam"]
+
+ResponseFunctionCallOutputItemParam: TypeAlias = Union[
+    ResponseInputTextContentParam, ResponseInputImageContentParam, ResponseInputFileContentParam
+]
+
+ResponseFunctionCallOutputItemListParam: TypeAlias = List[ResponseFunctionCallOutputItemParam]

src/openai/types/responses/response_function_call_output_item_param.py

@@ -0,0 +1,16 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Union
+from typing_extensions import TypeAlias
+
+from .response_input_file_content_param import ResponseInputFileContentParam
+from .response_input_text_content_param import ResponseInputTextContentParam
+from .response_input_image_content_param import ResponseInputImageContentParam
+
+__all__ = ["ResponseFunctionCallOutputItemParam"]
+
+ResponseFunctionCallOutputItemParam: TypeAlias = Union[
+    ResponseInputTextContentParam, ResponseInputImageContentParam, ResponseInputFileContentParam
+]

src/openai/types/responses/response_function_tool_call_output_item.py

@@ -1,11 +1,19 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Optional
-from typing_extensions import Literal
+from typing import List, Union, Optional
+from typing_extensions import Literal, Annotated, TypeAlias
 
+from ..._utils import PropertyInfo
 from ..._models import BaseModel
+from .response_input_file import ResponseInputFile
+from .response_input_text import ResponseInputText
+from .response_input_image import ResponseInputImage
 
-__all__ = ["ResponseFunctionToolCallOutputItem"]
+__all__ = ["ResponseFunctionToolCallOutputItem", "OutputOutputContentList"]
+
+OutputOutputContentList: TypeAlias = Annotated[
+    Union[ResponseInputText, ResponseInputImage, ResponseInputFile], PropertyInfo(discriminator="type")
+]
 
 
 class ResponseFunctionToolCallOutputItem(BaseModel):
@@ -15,8 +23,11 @@ class ResponseFunctionToolCallOutputItem(BaseModel):
     call_id: str
     """The unique ID of the function tool call generated by the model."""
 
-    output: str
-    """A JSON string of the output of the function tool call."""
+    output: Union[str, List[OutputOutputContentList]]
+    """
+    The output from the function call generated by your code. Can be a string or an
+    list of output content.
+    """
 
     type: Literal["function_call_output"]
     """The type of the function tool call output. Always `function_call_output`."""