feat(api): Support images and files for function call outputs in responses, BatchUsage

This release introduces a major version change to reflect a breaking modification in the `ResponseFunctionToolCallOutputItem` and `ResponseCustomToolCallOutput` schemas. Specifically, the `output` field, which previously accepted only a `string` value, has been expanded to support multiple structured types:

```
Before:  output: string
After:   output: string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>
```

This change allows custom tool calls to return images, files, and rich text content in addition to plain strings, aligning `ResponseCustomToolCallOutput` with the broader `ResponseInput` type system. Because this alters the type and shape of the field, it may break existing callsites that only accept strings.

BREAKING CHANGE: `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.

Author: stainless-app[bot]

.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

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,

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"),
+]