chore(api): docs and spec refactoring

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-94b1e3cb0bdc616ff0c2f267c33dadd95f133b1f64e647aab6c64afb292b2793.yml
-openapi_spec_hash: 2395319ac9befd59b6536ae7f9564a05
-config_hash: 930dac3aa861344867e4ac84f037b5df
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-d30ff992a48873c1466c49f3c01f2ec8933faebff23424748f8d056065b1bcef.yml
+openapi_spec_hash: e933ec43b46f45c348adb78840e5808d
+config_hash: bf45940f0a7805b4ec2017eecdd36893

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

@@ -1300,10 +1300,12 @@ def list(
 
           limit: Number of Chat Completions to retrieve.
 
-          metadata:
-              A list of metadata keys to filter the Chat Completions by. Example:
+          metadata: Set of 16 key-value pairs that can be attached to an object. This can be useful
+              for storing additional information about the object in a structured format, and
+              querying for objects via API or the dashboard.
 
-              `metadata[key1]=value1&metadata[key2]=value2`
+              Keys are strings with a maximum length of 64 characters. Values are strings with
+              a maximum length of 512 characters.
 
           model: The model used to generate the Chat Completions.
 
@@ -2736,10 +2738,12 @@ def list(
 
           limit: Number of Chat Completions to retrieve.
 
-          metadata:
-              A list of metadata keys to filter the Chat Completions by. Example:
+          metadata: Set of 16 key-value pairs that can be attached to an object. This can be useful
+              for storing additional information about the object in a structured format, and
+              querying for objects via API or the dashboard.
 
-              `metadata[key1]=value1&metadata[key2]=value2`
+              Keys are strings with a maximum length of 64 characters. Values are strings with
+              a maximum length of 512 characters.
 
           model: The model used to generate the Chat Completions.
 

src/openai/resources/conversations/conversations.py

@@ -73,8 +73,12 @@ def create(
           items: Initial items to include in the conversation context. You may add up to 20 items
               at a time.
 
-          metadata: Set of 16 key-value pairs that can be attached to an object. Useful for storing
-              additional information about the object in a structured format.
+          metadata: Set of 16 key-value pairs that can be attached to an object. This can be useful
+              for storing additional information about the object in a structured format, and
+              querying for objects via API or the dashboard.
+
+              Keys are strings with a maximum length of 64 characters. Values are strings with
+              a maximum length of 512 characters.
 
           extra_headers: Send extra headers
 
@@ -250,8 +254,12 @@ async def create(
           items: Initial items to include in the conversation context. You may add up to 20 items
               at a time.
 
-          metadata: Set of 16 key-value pairs that can be attached to an object. Useful for storing
-              additional information about the object in a structured format.
+          metadata: Set of 16 key-value pairs that can be attached to an object. This can be useful
+              for storing additional information about the object in a structured format, and
+              querying for objects via API or the dashboard.
+
+              Keys are strings with a maximum length of 64 characters. Values are strings with
+              a maximum length of 512 characters.
 
           extra_headers: Send extra headers
 

src/openai/types/audio/transcription_create_params.py

@@ -43,12 +43,12 @@ class TranscriptionCreateParamsBase(TypedDict, total=False):
     """
 
     include: List[TranscriptionInclude]
-    """Additional information to include in the transcription response.
-
-    `logprobs` will return the log probabilities of the tokens in the response to
-    understand the model's confidence in the transcription. `logprobs` only works
-    with response_format set to `json` and only with the models `gpt-4o-transcribe`
-    and `gpt-4o-mini-transcribe`.
+    """
+    Additional information to include in the transcription response. `logprobs` will
+    return the log probabilities of the tokens in the response to understand the
+    model's confidence in the transcription. `logprobs` only works with
+    response_format set to `json` and only with the models `gpt-4o-transcribe` and
+    `gpt-4o-mini-transcribe`.
     """
 
     language: str

src/openai/types/chat/chat_completion_assistant_message_param.py

@@ -38,8 +38,8 @@ class ChatCompletionAssistantMessageParam(TypedDict, total=False):
     """The role of the messages author, in this case `assistant`."""
 
     audio: Optional[Audio]
-    """Data about a previous audio response from the model.
-
+    """
+    Data about a previous audio response from the model.
     [Learn more](https://platform.openai.com/docs/guides/audio).
     """
 

src/openai/types/chat/completion_list_params.py

@@ -18,9 +18,13 @@ class CompletionListParams(TypedDict, total=False):
     """Number of Chat Completions to retrieve."""
 
     metadata: Optional[Metadata]
-    """A list of metadata keys to filter the Chat Completions by. Example:
+    """Set of 16 key-value pairs that can be attached to an object.
 
-    `metadata[key1]=value1&metadata[key2]=value2`
+    This can be useful for storing additional information about the object in a
+    structured format, and querying for objects via API or the dashboard.
+
+    Keys are strings with a maximum length of 64 characters. Values are strings with
+    a maximum length of 512 characters.
     """
 
     model: str

src/openai/types/conversations/conversation_create_params.py

@@ -21,6 +21,9 @@ class ConversationCreateParams(TypedDict, total=False):
     metadata: Optional[Metadata]
     """Set of 16 key-value pairs that can be attached to an object.
 
-    Useful for storing additional information about the object in a structured
-    format.
+    This can be useful for storing additional information about the object in a
+    structured format, and querying for objects via API or the dashboard.
+
+    Keys are strings with a maximum length of 64 characters. Values are strings with
+    a maximum length of 512 characters.
     """

src/openai/types/evals/run_cancel_response.py

@@ -100,9 +100,12 @@ class DataSourceResponsesSourceResponses(BaseModel):
     """
 
     reasoning_effort: Optional[ReasoningEffort] = None
-    """Optional reasoning effort parameter.
-
-    This is a query parameter used to select responses.
+    """
+    Constrains effort on reasoning for
+    [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
+    supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
+    effort can result in faster responses and fewer tokens used on reasoning in a
+    response.
     """
 
     temperature: Optional[float] = None

src/openai/types/evals/run_create_params.py

@@ -113,9 +113,12 @@ class DataSourceCreateEvalResponsesRunDataSourceSourceResponses(TypedDict, total
     """
 
     reasoning_effort: Optional[ReasoningEffort]
-    """Optional reasoning effort parameter.
-
-    This is a query parameter used to select responses.
+    """
+    Constrains effort on reasoning for
+    [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
+    supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
+    effort can result in faster responses and fewer tokens used on reasoning in a
+    response.
     """
 
     temperature: Optional[float]

src/openai/types/evals/run_create_response.py

@@ -100,9 +100,12 @@ class DataSourceResponsesSourceResponses(BaseModel):
     """
 
     reasoning_effort: Optional[ReasoningEffort] = None
-    """Optional reasoning effort parameter.
-
-    This is a query parameter used to select responses.
+    """
+    Constrains effort on reasoning for
+    [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
+    supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
+    effort can result in faster responses and fewer tokens used on reasoning in a
+    response.
     """
 
     temperature: Optional[float] = None