feat(api): new streaming helpers for background responses

stainless-app[bot] · stainless-app[bot] · commit 2a65d4de0aab · 2025-05-22T19:58:04.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-6af14840a810139bf407013167ce1c8fb21b6ef8eb0cc3db58b51af7d52c4b5a.yml
-openapi_spec_hash: 3241bde6b273cfec0035e522bd07985d
-config_hash: 7367b68a4e7db36885c1a886f57b17f6
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-fc64d7c2c8f51f750813375356c3f3fdfc7fc1b1b34f19c20a5410279d445d37.yml
+openapi_spec_hash: 618285fc70199ee32b9ebe4bf72f7e4c
+config_hash: c497f6b750cc89c0bf2eefc0bc839c70
diff --git a/api.md b/api.md
@@ -764,7 +764,6 @@ from openai.types.responses import (
     ResponseRefusalDoneEvent,
     ResponseStatus,
     ResponseStreamEvent,
-    ResponseTextAnnotationDeltaEvent,
     ResponseTextConfig,
     ResponseTextDeltaEvent,
     ResponseTextDoneEvent,
diff --git a/examples/responses/background_streaming.py b/examples/responses/background_streaming.py
@@ -1,3 +1,4 @@
+#!/usr/bin/env -S rye run python
 from typing import List
 
 import rich
diff --git a/src/openai/lib/streaming/responses/_events.py b/src/openai/lib/streaming/responses/_events.py
@@ -31,7 +31,6 @@
     ResponseMcpCallInProgressEvent,
     ResponseMcpListToolsFailedEvent,
     ResponseAudioTranscriptDoneEvent,
-    ResponseTextAnnotationDeltaEvent,
     ResponseAudioTranscriptDeltaEvent,
     ResponseMcpCallArgumentsDoneEvent,
     ResponseReasoningSummaryDoneEvent,
@@ -118,7 +117,6 @@ class ResponseCompletedEvent(RawResponseCompletedEvent, GenericModel, Generic[Te
         ResponseOutputItemDoneEvent,
         ResponseRefusalDeltaEvent,
         ResponseRefusalDoneEvent,
-        ResponseTextAnnotationDeltaEvent,
         ResponseTextDoneEvent,
         ResponseWebSearchCallCompletedEvent,
         ResponseWebSearchCallInProgressEvent,
diff --git a/src/openai/resources/beta/realtime/realtime.py b/src/openai/resources/beta/realtime/realtime.py
@@ -820,7 +820,7 @@ def clear(self, *, event_id: str | NotGiven = NOT_GIVEN) -> None:
         stop generating audio and emit a `output_audio_buffer.cleared` event. This
         event should be preceded by a `response.cancel` client event to stop the
         generation of the current response.
-        [Learn more](https://platform.openai.com/docs/guides/realtime-model-capabilities#client-and-server-events-for-audio-in-webrtc).
+        [Learn more](https://platform.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc).
         """
         self._connection.send(
             cast(RealtimeClientEventParam, strip_not_given({"type": "output_audio_buffer.clear", "event_id": event_id}))
@@ -1072,7 +1072,7 @@ async def clear(self, *, event_id: str | NotGiven = NOT_GIVEN) -> None:
         stop generating audio and emit a `output_audio_buffer.cleared` event. This
         event should be preceded by a `response.cancel` client event to stop the
         generation of the current response.
-        [Learn more](https://platform.openai.com/docs/guides/realtime-model-capabilities#client-and-server-events-for-audio-in-webrtc).
+        [Learn more](https://platform.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc).
         """
         await self._connection.send(
             cast(RealtimeClientEventParam, strip_not_given({"type": "output_audio_buffer.clear", "event_id": event_id}))
diff --git a/src/openai/resources/chat/completions/completions.py b/src/openai/resources/chat/completions/completions.py
@@ -323,8 +323,8 @@ def create(
 
               We generally recommend altering this or `temperature` but not both.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           web_search_options: This tool searches the web for relevant results to use in a response. Learn more
@@ -592,8 +592,8 @@ def create(
 
               We generally recommend altering this or `temperature` but not both.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           web_search_options: This tool searches the web for relevant results to use in a response. Learn more
@@ -861,8 +861,8 @@ def create(
 
               We generally recommend altering this or `temperature` but not both.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           web_search_options: This tool searches the web for relevant results to use in a response. Learn more
@@ -1426,8 +1426,8 @@ async def create(
 
               We generally recommend altering this or `temperature` but not both.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           web_search_options: This tool searches the web for relevant results to use in a response. Learn more
@@ -1695,8 +1695,8 @@ async def create(
 
               We generally recommend altering this or `temperature` but not both.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           web_search_options: This tool searches the web for relevant results to use in a response. Learn more
@@ -1964,8 +1964,8 @@ async def create(
 
               We generally recommend altering this or `temperature` but not both.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           web_search_options: This tool searches the web for relevant results to use in a response. Learn more
diff --git a/src/openai/resources/containers/files/files.py b/src/openai/resources/containers/files/files.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from typing import Mapping, cast
 from typing_extensions import Literal
 
 import httpx
@@ -16,7 +17,7 @@
     AsyncContentWithStreamingResponse,
 )
 from ...._types import NOT_GIVEN, Body, Query, Headers, NoneType, NotGiven, FileTypes
-from ...._utils import maybe_transform, async_maybe_transform
+from ...._utils import extract_files, maybe_transform, deepcopy_minimal, async_maybe_transform
 from ...._compat import cached_property
 from ...._resource import SyncAPIResource, AsyncAPIResource
 from ...._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
@@ -88,15 +89,21 @@ def create(
         """
         if not container_id:
             raise ValueError(f"Expected a non-empty value for `container_id` but received {container_id!r}")
+        body = deepcopy_minimal(
+            {
+                "file": file,
+                "file_id": file_id,
+            }
+        )
+        files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
+        # It should be noted that the actual Content-Type header that will be
+        # sent to the server will contain a `boundary` parameter, e.g.
+        # multipart/form-data; boundary=---abc--
+        extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
         return self._post(
             f"/containers/{container_id}/files",
-            body=maybe_transform(
-                {
-                    "file": file,
-                    "file_id": file_id,
-                },
-                file_create_params.FileCreateParams,
-            ),
+            body=maybe_transform(body, file_create_params.FileCreateParams),
+            files=files,
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
@@ -295,15 +302,21 @@ async def create(
         """
         if not container_id:
             raise ValueError(f"Expected a non-empty value for `container_id` but received {container_id!r}")
+        body = deepcopy_minimal(
+            {
+                "file": file,
+                "file_id": file_id,
+            }
+        )
+        files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
+        # It should be noted that the actual Content-Type header that will be
+        # sent to the server will contain a `boundary` parameter, e.g.
+        # multipart/form-data; boundary=---abc--
+        extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
         return await self._post(
             f"/containers/{container_id}/files",
-            body=await async_maybe_transform(
-                {
-                    "file": file,
-                    "file_id": file_id,
-                },
-                file_create_params.FileCreateParams,
-            ),
+            body=await async_maybe_transform(body, file_create_params.FileCreateParams),
+            files=files,
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
diff --git a/src/openai/resources/responses/input_items.py b/src/openai/resources/responses/input_items.py
@@ -72,7 +72,7 @@ def list(
           limit: A limit on the number of objects to be returned. Limit can range between 1 and
               100, and the default is 20.
 
-          order: The order to return the input items in. Default is `asc`.
+          order: The order to return the input items in. Default is `desc`.
 
               - `asc`: Return the input items in ascending order.
               - `desc`: Return the input items in descending order.
@@ -160,7 +160,7 @@ def list(
           limit: A limit on the number of objects to be returned. Limit can range between 1 and
               100, and the default is 20.
 
-          order: The order to return the input items in. Default is `asc`.
+          order: The order to return the input items in. Default is `desc`.
 
               - `asc`: Return the input items in ascending order.
               - `desc`: Return the input items in descending order.
diff --git a/src/openai/resources/responses/responses.py b/src/openai/resources/responses/responses.py
@@ -250,8 +250,8 @@ def create(
               - `disabled` (default): If a model response will exceed the context window size
                 for a model, the request will fail with a 400 error.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           extra_headers: Send extra headers
@@ -443,8 +443,8 @@ def create(
               - `disabled` (default): If a model response will exceed the context window size
                 for a model, the request will fail with a 400 error.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           extra_headers: Send extra headers
@@ -636,8 +636,8 @@ def create(
               - `disabled` (default): If a model response will exceed the context window size
                 for a model, the request will fail with a 400 error.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           extra_headers: Send extra headers
@@ -1353,8 +1353,8 @@ async def create(
               - `disabled` (default): If a model response will exceed the context window size
                 for a model, the request will fail with a 400 error.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           extra_headers: Send extra headers
@@ -1546,8 +1546,8 @@ async def create(
               - `disabled` (default): If a model response will exceed the context window size
                 for a model, the request will fail with a 400 error.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           extra_headers: Send extra headers
@@ -1739,8 +1739,8 @@ async def create(
               - `disabled` (default): If a model response will exceed the context window size
                 for a model, the request will fail with a 400 error.
 
-          user: A unique identifier representing your end-user, which can help OpenAI to monitor
-              and detect abuse.
+          user: A stable identifier for your end-users. Used to boost cache hit rates by better
+              bucketing similar requests and to help OpenAI detect and prevent abuse.
               [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
 
           extra_headers: Send extra headers
diff --git a/src/openai/types/chat/completion_create_params.py b/src/openai/types/chat/completion_create_params.py
@@ -292,9 +292,10 @@ class CompletionCreateParamsBase(TypedDict, total=False):
     """
 
     user: str
-    """
-    A unique identifier representing your end-user, which can help OpenAI to monitor
-    and detect abuse.
+    """A stable identifier for your end-users.
+
+    Used to boost cache hit rates by better bucketing similar requests and to help
+    OpenAI detect and prevent abuse.
     [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
     """
 
diff --git a/src/openai/types/responses/__init__.py b/src/openai/types/responses/__init__.py
@@ -97,7 +97,6 @@
 from .response_audio_transcript_done_event import ResponseAudioTranscriptDoneEvent as ResponseAudioTranscriptDoneEvent
 from .response_file_search_tool_call_param import ResponseFileSearchToolCallParam as ResponseFileSearchToolCallParam
 from .response_mcp_list_tools_failed_event import ResponseMcpListToolsFailedEvent as ResponseMcpListToolsFailedEvent
-from .response_text_annotation_delta_event import ResponseTextAnnotationDeltaEvent as ResponseTextAnnotationDeltaEvent
 from .response_audio_transcript_delta_event import (
     ResponseAudioTranscriptDeltaEvent as ResponseAudioTranscriptDeltaEvent,
 )
diff --git a/src/openai/types/responses/input_item_list_params.py b/src/openai/types/responses/input_item_list_params.py
@@ -30,7 +30,7 @@ class InputItemListParams(TypedDict, total=False):
     """
 
     order: Literal["asc", "desc"]
-    """The order to return the input items in. Default is `asc`.
+    """The order to return the input items in. Default is `desc`.
 
     - `asc`: Return the input items in ascending order.
     - `desc`: Return the input items in descending order.
diff --git a/src/openai/types/responses/response.py b/src/openai/types/responses/response.py
@@ -209,9 +209,10 @@ class Response(BaseModel):
     """
 
     user: Optional[str] = None
-    """
-    A unique identifier representing your end-user, which can help OpenAI to monitor
-    and detect abuse.
+    """A stable identifier for your end-users.
+
+    Used to boost cache hit rates by better bucketing similar requests and to help
+    OpenAI detect and prevent abuse.
     [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
     """
 
diff --git a/src/openai/types/responses/response_create_params.py b/src/openai/types/responses/response_create_params.py
@@ -199,9 +199,10 @@ class ResponseCreateParamsBase(TypedDict, total=False):
     """
 
     user: str
-    """
-    A unique identifier representing your end-user, which can help OpenAI to monitor
-    and detect abuse.
+    """A stable identifier for your end-users.
+
+    Used to boost cache hit rates by better bucketing similar requests and to help
+    OpenAI detect and prevent abuse.
     [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
     """
 
diff --git a/src/openai/types/responses/response_stream_event.py b/src/openai/types/responses/response_stream_event.py
@@ -28,7 +28,6 @@
 from .response_mcp_call_in_progress_event import ResponseMcpCallInProgressEvent
 from .response_audio_transcript_done_event import ResponseAudioTranscriptDoneEvent
 from .response_mcp_list_tools_failed_event import ResponseMcpListToolsFailedEvent
-from .response_text_annotation_delta_event import ResponseTextAnnotationDeltaEvent
 from .response_audio_transcript_delta_event import ResponseAudioTranscriptDeltaEvent
 from .response_reasoning_summary_done_event import ResponseReasoningSummaryDoneEvent
 from .response_mcp_call_arguments_done_event import ResponseMcpCallArgumentsDoneEvent
@@ -93,7 +92,6 @@
         ResponseReasoningSummaryTextDoneEvent,
         ResponseRefusalDeltaEvent,
         ResponseRefusalDoneEvent,
-        ResponseTextAnnotationDeltaEvent,
         ResponseTextDeltaEvent,
         ResponseTextDoneEvent,
         ResponseWebSearchCallCompletedEvent,
diff --git a/src/openai/types/responses/response_text_annotation_delta_event.py b/src/openai/types/responses/response_text_annotation_delta_event.py
diff --git a/src/openai/types/responses/response_web_search_call_completed_event.py b/src/openai/types/responses/response_web_search_call_completed_event.py
diff --git a/src/openai/types/responses/response_web_search_call_in_progress_event.py b/src/openai/types/responses/response_web_search_call_in_progress_event.py
diff --git a/src/openai/types/responses/response_web_search_call_searching_event.py b/src/openai/types/responses/response_web_search_call_searching_event.py
diff --git a/src/openai/types/responses/tool.py b/src/openai/types/responses/tool.py
diff --git a/src/openai/types/responses/tool_param.py b/src/openai/types/responses/tool_param.py

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+#!/usr/bin/env -S rye run python`
`1`	`2`	`from typing import List`
`2`	`3`
`3`	`4`	`import rich`
Original file line number	Diff line number	Diff line change
`@@ -97,7 +97,6 @@`
`97`	`97`	`from .response_audio_transcript_done_event import ResponseAudioTranscriptDoneEvent as ResponseAudioTranscriptDoneEvent`
`98`	`98`	`from .response_file_search_tool_call_param import ResponseFileSearchToolCallParam as ResponseFileSearchToolCallParam`
`99`	`99`	`from .response_mcp_list_tools_failed_event import ResponseMcpListToolsFailedEvent as ResponseMcpListToolsFailedEvent`
`100`		`-from .response_text_annotation_delta_event import ResponseTextAnnotationDeltaEvent as ResponseTextAnnotationDeltaEvent`
`101`	`100`	`from .response_audio_transcript_delta_event import (`
`102`	`101`	`ResponseAudioTranscriptDeltaEvent as ResponseAudioTranscriptDeltaEvent,`
`103`	`102`	`)`