release: 2.24.0 (#2890)

stainless-app[bot] · web-flow · commit 656e3cab4a18 · 2026-02-24T12:01:04.000-08:00
* chore(internal): refactor sse event parsing

* codegen metadata

* chore(internal): make `test_proxy_environment_variables` more resilient to env

* feat(api): add phase

* fix(api): phase docs

* fix(api): fix phase enum

* release: 2.24.0

---------

Co-authored-by: stainless-app[bot] &lt;142633134+stainless-app[bot]@users.noreply.github.com&gt;
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "2.23.0"
+  ".": "2.24.0"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 148
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-a0aa54a302fbd7fff4ed7ad8a8547587d37b63324fc4af652bfa685ee9f8da44.yml
-openapi_spec_hash: e45c5af19307cfc8b9baa4b8f8e865a0
-config_hash: 2cbce279be85ff86a2fabbc85d62b011
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-6bfe886b5ded0fe3bf37ca672698814e16e0836a093ceef65dac37ae44d1ad6b.yml
+openapi_spec_hash: 6b1344a59044318e824c8d1af96033c7
+config_hash: 7f49c38fa3abe9b7038ffe62262c4912
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,25 @@
 # Changelog
 
+## 2.24.0 (2026-02-24)
+
+Full Changelog: [v2.23.0...v2.24.0](https://github.com/openai/openai-python/compare/v2.23.0...v2.24.0)
+
+### Features
+
+* **api:** add phase ([391deb9](https://github.com/openai/openai-python/commit/391deb99f6a92e51bffb25efd8dfe367d144bb9d))
+
+
+### Bug Fixes
+
+* **api:** fix phase enum ([42ebf7c](https://github.com/openai/openai-python/commit/42ebf7c30b7e27a175c0d75fcf42c8dc858e56d6))
+* **api:** phase docs ([7ddc61c](https://github.com/openai/openai-python/commit/7ddc61cd0f7825d5e7f3a10daf809135511d8d20))
+
+
+### Chores
+
+* **internal:** make `test_proxy_environment_variables` more resilient to env ([65af8fd](https://github.com/openai/openai-python/commit/65af8fd8550e99236e3f4dcb035312441788157a))
+* **internal:** refactor sse event parsing ([2344600](https://github.com/openai/openai-python/commit/23446008f06fb474d8c75d14a1bce26f4c5b95d8))
+
 ## 2.23.0 (2026-02-24)
 
 Full Changelog: [v2.22.0...v2.23.0](https://github.com/openai/openai-python/compare/v2.22.0...v2.23.0)
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "openai"
-version = "2.23.0"
+version = "2.24.0"
 description = "The official Python library for the openai API"
 dynamic = ["readme"]
 license = "Apache-2.0"
diff --git a/src/openai/_base_client.py b/src/openai/_base_client.py
@@ -1984,6 +1984,7 @@ def make_request_options(
     idempotency_key: str | None = None,
     timeout: float | httpx.Timeout | None | NotGiven = not_given,
     post_parser: PostParser | NotGiven = not_given,
+    synthesize_event_and_data: bool | None = None,
 ) -> RequestOptions:
     """Create a dict of type RequestOptions without keys of NotGiven values."""
     options: RequestOptions = {}
@@ -2009,6 +2010,9 @@ def make_request_options(
         # internal
         options["post_parser"] = post_parser  # type: ignore
 
+    if synthesize_event_and_data is not None:
+        options["synthesize_event_and_data"] = synthesize_event_and_data
+
     return options
 
 
diff --git a/src/openai/_models.py b/src/openai/_models.py
@@ -845,6 +845,7 @@ class FinalRequestOptionsInput(TypedDict, total=False):
     json_data: Body
     extra_json: AnyMapping
     follow_redirects: bool
+    synthesize_event_and_data: bool
 
 
 @final
@@ -859,6 +860,7 @@ class FinalRequestOptions(pydantic.BaseModel):
     idempotency_key: Union[str, None] = None
     post_parser: Union[Callable[[Any], Any], NotGiven] = NotGiven()
     follow_redirects: Union[bool, None] = None
+    synthesize_event_and_data: Optional[bool] = None
 
     content: Union[bytes, bytearray, IO[bytes], Iterable[bytes], AsyncIterable[bytes], None] = None
     # It should be noted that we cannot use `json` here as that would override
diff --git a/src/openai/_streaming.py b/src/openai/_streaming.py
@@ -98,8 +98,13 @@ def __stream__(self) -> Iterator[_T]:
                             body=data["error"],
                         )
 
-                    yield process_data(data=data, cast_to=cast_to, response=response)
-
+                    yield process_data(
+                        data={"data": data, "event": sse.event}
+                        if self._options is not None and self._options.synthesize_event_and_data
+                        else data,
+                        cast_to=cast_to,
+                        response=response,
+                    )
         finally:
             # Ensure the response is closed even if the consumer doesn't read all data
             response.close()
@@ -203,8 +208,13 @@ async def __stream__(self) -> AsyncIterator[_T]:
                             body=data["error"],
                         )
 
-                    yield process_data(data=data, cast_to=cast_to, response=response)
-
+                    yield process_data(
+                        data={"data": data, "event": sse.event}
+                        if self._options is not None and self._options.synthesize_event_and_data
+                        else data,
+                        cast_to=cast_to,
+                        response=response,
+                    )
         finally:
             # Ensure the response is closed even if the consumer doesn't read all data
             await response.aclose()
diff --git a/src/openai/_types.py b/src/openai/_types.py
@@ -122,6 +122,7 @@ class RequestOptions(TypedDict, total=False):
     extra_json: AnyMapping
     idempotency_key: str
     follow_redirects: bool
+    synthesize_event_and_data: bool
 
 
 # Sentinel class used until PEP 0661 is accepted
diff --git a/src/openai/_version.py b/src/openai/_version.py
@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "openai"
-__version__ = "2.23.0"  # x-release-please-version
+__version__ = "2.24.0"  # x-release-please-version
diff --git a/src/openai/resources/beta/threads/runs/runs.py b/src/openai/resources/beta/threads/runs/runs.py
@@ -620,6 +620,7 @@ def create(
                 extra_body=extra_body,
                 timeout=timeout,
                 query=maybe_transform({"include": include}, run_create_params.RunCreateParams),
+                synthesize_event_and_data=True,
             ),
             cast_to=Run,
             stream=stream or False,
@@ -1368,7 +1369,11 @@ def submit_tool_outputs(
                 else run_submit_tool_outputs_params.RunSubmitToolOutputsParamsNonStreaming,
             ),
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                synthesize_event_and_data=True,
             ),
             cast_to=Run,
             stream=stream or False,
@@ -2075,6 +2080,7 @@ async def create(
                 extra_body=extra_body,
                 timeout=timeout,
                 query=await async_maybe_transform({"include": include}, run_create_params.RunCreateParams),
+                synthesize_event_and_data=True,
             ),
             cast_to=Run,
             stream=stream or False,
@@ -2822,7 +2828,11 @@ async def submit_tool_outputs(
                 else run_submit_tool_outputs_params.RunSubmitToolOutputsParamsNonStreaming,
             ),
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                synthesize_event_and_data=True,
             ),
             cast_to=Run,
             stream=stream or False,
diff --git a/src/openai/resources/beta/threads/threads.py b/src/openai/resources/beta/threads/threads.py
@@ -729,7 +729,11 @@ def create_and_run(
                 else thread_create_and_run_params.ThreadCreateAndRunParamsNonStreaming,
             ),
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                synthesize_event_and_data=True,
             ),
             cast_to=Run,
             stream=stream or False,
@@ -1587,7 +1591,11 @@ async def create_and_run(
                 else thread_create_and_run_params.ThreadCreateAndRunParamsNonStreaming,
             ),
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                synthesize_event_and_data=True,
             ),
             cast_to=Run,
             stream=stream or False,
diff --git a/src/openai/resources/responses/responses.py b/src/openai/resources/responses/responses.py
@@ -1660,6 +1660,7 @@ def compact(
         input: Union[str, Iterable[ResponseInputItemParam], None] | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         previous_response_id: Optional[str] | Omit = omit,
+        prompt_cache_key: Optional[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -1695,6 +1696,8 @@ def compact(
               [conversation state](https://platform.openai.com/docs/guides/conversation-state).
               Cannot be used in conjunction with `conversation`.
 
+          prompt_cache_key: A key to use when reading from or writing to the prompt cache.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -1711,6 +1714,7 @@ def compact(
                     "input": input,
                     "instructions": instructions,
                     "previous_response_id": previous_response_id,
+                    "prompt_cache_key": prompt_cache_key,
                 },
                 response_compact_params.ResponseCompactParams,
             ),
@@ -3321,6 +3325,7 @@ async def compact(
         input: Union[str, Iterable[ResponseInputItemParam], None] | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         previous_response_id: Optional[str] | Omit = omit,
+        prompt_cache_key: Optional[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -3356,6 +3361,8 @@ async def compact(
               [conversation state](https://platform.openai.com/docs/guides/conversation-state).
               Cannot be used in conjunction with `conversation`.
 
+          prompt_cache_key: A key to use when reading from or writing to the prompt cache.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -3372,6 +3379,7 @@ async def compact(
                     "input": input,
                     "instructions": instructions,
                     "previous_response_id": previous_response_id,
+                    "prompt_cache_key": prompt_cache_key,
                 },
                 response_compact_params.ResponseCompactParams,
             ),
diff --git a/src/openai/types/responses/easy_input_message.py b/src/openai/types/responses/easy_input_message.py
@@ -30,5 +30,14 @@ class EasyInputMessage(BaseModel):
     One of `user`, `assistant`, `system`, or `developer`.
     """
 
+    phase: Optional[Literal["commentary", "final_answer"]] = None
+    """The phase of an assistant message.
+
+    Use `commentary` for an intermediate assistant message and `final_answer` for
+    the final assistant message. For follow-up requests with models like
+    `gpt-5.3-codex` and later, preserve and resend phase on all assistant messages.
+    Omitting it can degrade performance. Not used for user messages.
+    """
+
     type: Optional[Literal["message"]] = None
     """The type of the message input. Always `message`."""
diff --git a/src/openai/types/responses/easy_input_message_param.py b/src/openai/types/responses/easy_input_message_param.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Union
+from typing import Union, Optional
 from typing_extensions import Literal, Required, TypedDict
 
 from .response_input_message_content_list_param import ResponseInputMessageContentListParam
@@ -31,5 +31,14 @@ class EasyInputMessageParam(TypedDict, total=False):
     One of `user`, `assistant`, `system`, or `developer`.
     """
 
+    phase: Optional[Literal["commentary", "final_answer"]]
+    """The phase of an assistant message.
+
+    Use `commentary` for an intermediate assistant message and `final_answer` for
+    the final assistant message. For follow-up requests with models like
+    `gpt-5.3-codex` and later, preserve and resend phase on all assistant messages.
+    Omitting it can degrade performance. Not used for user messages.
+    """
+
     type: Literal["message"]
     """The type of the message input. Always `message`."""
diff --git a/src/openai/types/responses/response_compact_params.py b/src/openai/types/responses/response_compact_params.py
@@ -131,3 +131,6 @@ class ResponseCompactParams(TypedDict, total=False):
     [conversation state](https://platform.openai.com/docs/guides/conversation-state).
     Cannot be used in conjunction with `conversation`.
     """
+
+    prompt_cache_key: Optional[str]
+    """A key to use when reading from or writing to the prompt cache."""
diff --git a/src/openai/types/responses/response_output_message.py b/src/openai/types/responses/response_output_message.py
@@ -1,6 +1,6 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import List, Union
+from typing import List, Union, Optional
 from typing_extensions import Literal, Annotated, TypeAlias
 
 from ..._utils import PropertyInfo
@@ -34,3 +34,12 @@ class ResponseOutputMessage(BaseModel):
 
     type: Literal["message"]
     """The type of the output message. Always `message`."""
+
+    phase: Optional[Literal["commentary", "final_answer"]] = None
+    """The phase of an assistant message.
+
+    Use `commentary` for an intermediate assistant message and `final_answer` for
+    the final assistant message. For follow-up requests with models like
+    `gpt-5.3-codex` and later, preserve and resend phase on all assistant messages.
+    Omitting it can degrade performance. Not used for user messages.
+    """
diff --git a/src/openai/types/responses/response_output_message_param.py b/src/openai/types/responses/response_output_message_param.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Union, Iterable
+from typing import Union, Iterable, Optional
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
 from .response_output_text_param import ResponseOutputTextParam
@@ -34,3 +34,12 @@ class ResponseOutputMessageParam(TypedDict, total=False):
 
     type: Required[Literal["message"]]
     """The type of the output message. Always `message`."""
+
+    phase: Optional[Literal["commentary", "final_answer"]]
+    """The phase of an assistant message.
+
+    Use `commentary` for an intermediate assistant message and `final_answer` for
+    the final assistant message. For follow-up requests with models like
+    `gpt-5.3-codex` and later, preserve and resend phase on all assistant messages.
+    Omitting it can degrade performance. Not used for user messages.
+    """
diff --git a/tests/api_resources/conversations/test_items.py b/tests/api_resources/conversations/test_items.py
@@ -44,6 +44,7 @@ def test_method_create_with_all_params(self, client: OpenAI) -> None:
                 {
                     "content": "string",
                     "role": "user",
+                    "phase": "commentary",
                     "type": "message",
                 }
             ],
@@ -285,6 +286,7 @@ async def test_method_create_with_all_params(self, async_client: AsyncOpenAI) ->
                 {
                     "content": "string",
                     "role": "user",
+                    "phase": "commentary",
                     "type": "message",
                 }
             ],
diff --git a/tests/api_resources/test_conversations.py b/tests/api_resources/test_conversations.py
@@ -32,6 +32,7 @@ def test_method_create_with_all_params(self, client: OpenAI) -> None:
                 {
                     "content": "string",
                     "role": "user",
+                    "phase": "commentary",
                     "type": "message",
                 }
             ],
@@ -195,6 +196,7 @@ async def test_method_create_with_all_params(self, async_client: AsyncOpenAI) ->
                 {
                     "content": "string",
                     "role": "user",
+                    "phase": "commentary",
                     "type": "message",
                 }
             ],
diff --git a/tests/api_resources/test_responses.py b/tests/api_resources/test_responses.py
@@ -385,6 +385,7 @@ def test_method_compact_with_all_params(self, client: OpenAI) -> None:
             input="string",
             instructions="instructions",
             previous_response_id="resp_123",
+            prompt_cache_key="prompt_cache_key",
         )
         assert_matches_type(CompactedResponse, response, path=["response"])
 
@@ -793,6 +794,7 @@ async def test_method_compact_with_all_params(self, async_client: AsyncOpenAI) -
             input="string",
             instructions="instructions",
             previous_response_id="resp_123",
+            prompt_cache_key="prompt_cache_key",
         )
         assert_matches_type(CompactedResponse, response, path=["response"])
 
diff --git a/tests/test_client.py b/tests/test_client.py

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- ".": "2.23.0"`
	`2`	`+ ".": "2.24.0"`
`3`	`3`	`}`