docs(api): enhance method descriptions across audio, chat, realtime, skills, uploads, videos

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 148
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-0db5326a0fb6a30ffad9242c72872c3388ef927e8a4549ddd20aec3420541209.yml
-openapi_spec_hash: 9523fe30739802e15c88f4e7aac44e7f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-c20486f46004d6be2d280d7792c64d47fcea3e5b7fbbb50d3ffc6241aba653df.yml
+openapi_spec_hash: bf1dbabc5a923d897309273183525c02
 config_hash: 948733484caf41e71093c6582dbc319c

src/openai/resources/audio/speech.py

@@ -67,6 +67,8 @@ def create(
         """
         Generates audio from the input text.
 
+        Returns the audio file content, or a stream of audio events.
+
         Args:
           input: The text to generate audio for. The maximum length is 4096 characters.
 
@@ -164,6 +166,8 @@ async def create(
         """
         Generates audio from the input text.
 
+        Returns the audio file content, or a stream of audio events.
+
         Args:
           input: The text to generate audio for. The maximum length is 4096 characters.
 

src/openai/resources/audio/transcriptions.py

@@ -85,6 +85,9 @@ def create(
         """
         Transcribes audio into the input language.
 
+        Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
+        format, or a stream of transcript events.
+
         Args:
           file:
               The audio file object (not file name) to transcribe, in one of these formats:
@@ -235,6 +238,9 @@ def create(
         """
         Transcribes audio into the input language.
 
+        Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
+        format, or a stream of transcript events.
+
         Args:
           file:
               The audio file object (not file name) to transcribe, in one of these formats:
@@ -343,6 +349,9 @@ def create(
         """
         Transcribes audio into the input language.
 
+        Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
+        format, or a stream of transcript events.
+
         Args:
           file:
               The audio file object (not file name) to transcribe, in one of these formats:
@@ -533,6 +542,9 @@ async def create(
         """
         Transcribes audio into the input language.
 
+        Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
+        format, or a stream of transcript events.
+
         Args:
           file:
               The audio file object (not file name) to transcribe, in one of these formats:
@@ -678,6 +690,9 @@ async def create(
         """
         Transcribes audio into the input language.
 
+        Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
+        format, or a stream of transcript events.
+
         Args:
           file:
               The audio file object (not file name) to transcribe, in one of these formats:
@@ -786,6 +801,9 @@ async def create(
         """
         Transcribes audio into the input language.
 
+        Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
+        format, or a stream of transcript events.
+
         Args:
           file:
               The audio file object (not file name) to transcribe, in one of these formats:

src/openai/resources/beta/chatkit/sessions.py

@@ -63,7 +63,7 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ChatSession:
         """
-        Create a ChatKit session
+        Create a ChatKit session.
 
         Args:
           user: A free-form string that identifies your end user; ensures this Session can
@@ -117,7 +117,9 @@ def cancel(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ChatSession:
         """
-        Cancel a ChatKit session
+        Cancel an active ChatKit session and return its most recent metadata.
+
+        Cancelling prevents new requests from using the issued client secret.
 
         Args:
           extra_headers: Send extra headers
@@ -176,7 +178,7 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ChatSession:
         """
-        Create a ChatKit session
+        Create a ChatKit session.
 
         Args:
           user: A free-form string that identifies your end user; ensures this Session can
@@ -230,7 +232,9 @@ async def cancel(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ChatSession:
         """
-        Cancel a ChatKit session
+        Cancel an active ChatKit session and return its most recent metadata.
+
+        Cancelling prevents new requests from using the issued client secret.
 
         Args:
           extra_headers: Send extra headers

src/openai/resources/beta/chatkit/threads.py

@@ -55,7 +55,7 @@ def retrieve(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ChatKitThread:
         """
-        Retrieve a ChatKit thread
+        Retrieve a ChatKit thread by its identifier.
 
         Args:
           extra_headers: Send extra headers
@@ -93,7 +93,7 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SyncConversationCursorPage[ChatKitThread]:
         """
-        List ChatKit threads
+        List ChatKit threads with optional pagination and user filters.
 
         Args:
           after: List items created after this thread item ID. Defaults to null for the first
@@ -152,7 +152,7 @@ def delete(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ThreadDeleteResponse:
         """
-        Delete a ChatKit thread
+        Delete a ChatKit thread along with its items and stored attachments.
 
         Args:
           extra_headers: Send extra headers
@@ -190,7 +190,7 @@ def list_items(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SyncConversationCursorPage[Data]:
         """
-        List ChatKit thread items
+        List items that belong to a ChatKit thread.
 
         Args:
           after: List items created after this thread item ID. Defaults to null for the first
@@ -268,7 +268,7 @@ async def retrieve(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ChatKitThread:
         """
-        Retrieve a ChatKit thread
+        Retrieve a ChatKit thread by its identifier.
 
         Args:
           extra_headers: Send extra headers
@@ -306,7 +306,7 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AsyncPaginator[ChatKitThread, AsyncConversationCursorPage[ChatKitThread]]:
         """
-        List ChatKit threads
+        List ChatKit threads with optional pagination and user filters.
 
         Args:
           after: List items created after this thread item ID. Defaults to null for the first
@@ -365,7 +365,7 @@ async def delete(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ThreadDeleteResponse:
         """
-        Delete a ChatKit thread
+        Delete a ChatKit thread along with its items and stored attachments.
 
         Args:
           extra_headers: Send extra headers
@@ -403,7 +403,7 @@ def list_items(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AsyncPaginator[Data, AsyncConversationCursorPage[Data]]:
         """
-        List ChatKit thread items
+        List items that belong to a ChatKit thread.
 
         Args:
           after: List items created after this thread item ID. Defaults to null for the first

src/openai/resources/chat/completions/completions.py

@@ -301,6 +301,9 @@ def create(
         unsupported parameters in reasoning models,
         [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
 
+        Returns a chat completion object, or a streamed sequence of chat completion
+        chunk objects if the request is streamed.
+
         Args:
           messages: A list of messages comprising the conversation so far. Depending on the
               [model](https://platform.openai.com/docs/models) you use, different message
@@ -603,6 +606,9 @@ def create(
         unsupported parameters in reasoning models,
         [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
 
+        Returns a chat completion object, or a streamed sequence of chat completion
+        chunk objects if the request is streamed.
+
         Args:
           messages: A list of messages comprising the conversation so far. Depending on the
               [model](https://platform.openai.com/docs/models) you use, different message
@@ -905,6 +911,9 @@ def create(
         unsupported parameters in reasoning models,
         [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
 
+        Returns a chat completion object, or a streamed sequence of chat completion
+        chunk objects if the request is streamed.
+
         Args:
           messages: A list of messages comprising the conversation so far. Depending on the
               [model](https://platform.openai.com/docs/models) you use, different message
@@ -1785,6 +1794,9 @@ async def create(
         unsupported parameters in reasoning models,
         [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
 
+        Returns a chat completion object, or a streamed sequence of chat completion
+        chunk objects if the request is streamed.
+
         Args:
           messages: A list of messages comprising the conversation so far. Depending on the
               [model](https://platform.openai.com/docs/models) you use, different message
@@ -2087,6 +2099,9 @@ async def create(
         unsupported parameters in reasoning models,
         [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
 
+        Returns a chat completion object, or a streamed sequence of chat completion
+        chunk objects if the request is streamed.
+
         Args:
           messages: A list of messages comprising the conversation so far. Depending on the
               [model](https://platform.openai.com/docs/models) you use, different message
@@ -2389,6 +2404,9 @@ async def create(
         unsupported parameters in reasoning models,
         [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
 
+        Returns a chat completion object, or a streamed sequence of chat completion
+        chunk objects if the request is streamed.
+
         Args:
           messages: A list of messages comprising the conversation so far. Depending on the
               [model](https://platform.openai.com/docs/models) you use, different message

src/openai/resources/completions.py

@@ -76,6 +76,9 @@ def create(
         """
         Creates a completion for the provided prompt and parameters.
 
+        Returns a completion object, or a sequence of completion objects if the request
+        is streamed.
+
         Args:
           model: ID of the model to use. You can use the
               [List models](https://platform.openai.com/docs/api-reference/models/list) API to
@@ -231,6 +234,9 @@ def create(
         """
         Creates a completion for the provided prompt and parameters.
 
+        Returns a completion object, or a sequence of completion objects if the request
+        is streamed.
+
         Args:
           model: ID of the model to use. You can use the
               [List models](https://platform.openai.com/docs/api-reference/models/list) API to
@@ -386,6 +392,9 @@ def create(
         """
         Creates a completion for the provided prompt and parameters.
 
+        Returns a completion object, or a sequence of completion objects if the request
+        is streamed.
+
         Args:
           model: ID of the model to use. You can use the
               [List models](https://platform.openai.com/docs/api-reference/models/list) API to
@@ -626,6 +635,9 @@ async def create(
         """
         Creates a completion for the provided prompt and parameters.
 
+        Returns a completion object, or a sequence of completion objects if the request
+        is streamed.
+
         Args:
           model: ID of the model to use. You can use the
               [List models](https://platform.openai.com/docs/api-reference/models/list) API to
@@ -781,6 +793,9 @@ async def create(
         """
         Creates a completion for the provided prompt and parameters.
 
+        Returns a completion object, or a sequence of completion objects if the request
+        is streamed.
+
         Args:
           model: ID of the model to use. You can use the
               [List models](https://platform.openai.com/docs/api-reference/models/list) API to
@@ -936,6 +951,9 @@ async def create(
         """
         Creates a completion for the provided prompt and parameters.
 
+        Returns a completion object, or a sequence of completion objects if the request
+        is streamed.
+
         Args:
           model: ID of the model to use. You can use the
               [List models](https://platform.openai.com/docs/api-reference/models/list) API to

src/openai/resources/realtime/client_secrets.py

@@ -52,6 +52,20 @@ def create(
         """
         Create a Realtime client secret with an associated session configuration.
 
+        Client secrets are short-lived tokens that can be passed to a client app, such
+        as a web frontend or mobile client, which grants access to the Realtime API
+        without leaking your main API key. You can configure a custom TTL for each
+        client secret.
+
+        You can also attach session configuration options to the client secret, which
+        will be applied to any sessions created using that client secret, but these can
+        also be overridden by the client connection.
+
+        [Learn more about authentication with client secrets over WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc).
+
+        Returns the created client secret and the effective session object. The client
+        secret is a string that looks like `ek_1234`.
+
         Args:
           expires_after: Configuration for the client secret expiration. Expiration refers to the time
               after which a client secret will no longer be valid for creating sessions. The
@@ -120,6 +134,20 @@ async def create(
         """
         Create a Realtime client secret with an associated session configuration.
 
+        Client secrets are short-lived tokens that can be passed to a client app, such
+        as a web frontend or mobile client, which grants access to the Realtime API
+        without leaking your main API key. You can configure a custom TTL for each
+        client secret.
+
+        You can also attach session configuration options to the client secret, which
+        will be applied to any sessions created using that client secret, but these can
+        also be overridden by the client connection.
+
+        [Learn more about authentication with client secrets over WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc).
+
+        Returns the created client secret and the effective session object. The client
+        secret is a string that looks like `ek_1234`.
+
         Args:
           expires_after: Configuration for the client secret expiration. Expiration refers to the time
               after which a client secret will no longer be valid for creating sessions. The

src/openai/resources/responses/input_tokens.py

@@ -65,7 +65,10 @@ def count(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> InputTokenCountResponse:
         """
-        Get input token counts
+        Returns input token counts of the request.
+
+        Returns an object with `object` set to `response.input_tokens` and an
+        `input_tokens` count.
 
         Args:
           conversation: The conversation that this response belongs to. Items from this conversation are
@@ -188,7 +191,10 @@ async def count(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> InputTokenCountResponse:
         """
-        Get input token counts
+        Returns input token counts of the request.
+
+        Returns an object with `object` set to `response.input_tokens` and an
+        `input_tokens` count.
 
         Args:
           conversation: The conversation that this response belongs to. Items from this conversation are