chore(api): docs and spec refactoring

stainless-app[bot] · stainless-app[bot] · commit 9bab5da1802c · 2025-09-15T19:52:19.000Z
diff --git a/.stats.yml b/.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
diff --git a/src/openai/resources/chat/completions/completions.py b/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.
 
diff --git a/src/openai/resources/conversations/conversations.py b/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
 
diff --git a/src/openai/types/audio/transcription_create_params.py b/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
diff --git a/src/openai/types/chat/chat_completion_assistant_message_param.py b/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).
     """
 
diff --git a/src/openai/types/chat/completion_list_params.py b/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
diff --git a/src/openai/types/conversations/conversation_create_params.py b/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.
     """
diff --git a/src/openai/types/evals/run_cancel_response.py b/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
diff --git a/src/openai/types/evals/run_create_params.py b/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]
diff --git a/src/openai/types/evals/run_create_response.py b/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
diff --git a/src/openai/types/evals/run_list_response.py b/src/openai/types/evals/run_list_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
diff --git a/src/openai/types/evals/run_retrieve_response.py b/src/openai/types/evals/run_retrieve_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
diff --git a/src/openai/types/realtime/realtime_response_create_params.py b/src/openai/types/realtime/realtime_response_create_params.py
@@ -83,8 +83,8 @@ class RealtimeResponseCreateParams(BaseModel):
     """
 
     prompt: Optional[ResponsePrompt] = None
-    """Reference to a prompt template and its variables.
-
+    """
+    Reference to a prompt template and its variables.
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
diff --git a/src/openai/types/realtime/realtime_response_create_params_param.py b/src/openai/types/realtime/realtime_response_create_params_param.py
@@ -84,8 +84,8 @@ class RealtimeResponseCreateParamsParam(TypedDict, total=False):
     """
 
     prompt: Optional[ResponsePromptParam]
-    """Reference to a prompt template and its variables.
-
+    """
+    Reference to a prompt template and its variables.
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
diff --git a/src/openai/types/realtime/realtime_session_create_request.py b/src/openai/types/realtime/realtime_session_create_request.py
@@ -76,8 +76,8 @@ class RealtimeSessionCreateRequest(BaseModel):
     """
 
     prompt: Optional[ResponsePrompt] = None
-    """Reference to a prompt template and its variables.
-
+    """
+    Reference to a prompt template and its variables.
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
diff --git a/src/openai/types/realtime/realtime_session_create_request_param.py b/src/openai/types/realtime/realtime_session_create_request_param.py
@@ -76,8 +76,8 @@ class RealtimeSessionCreateRequestParam(TypedDict, total=False):
     """
 
     prompt: Optional[ResponsePromptParam]
-    """Reference to a prompt template and its variables.
-
+    """
+    Reference to a prompt template and its variables.
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
diff --git a/src/openai/types/realtime/realtime_session_create_response.py b/src/openai/types/realtime/realtime_session_create_response.py
@@ -429,8 +429,8 @@ class RealtimeSessionCreateResponse(BaseModel):
     """
 
     prompt: Optional[ResponsePrompt] = None
-    """Reference to a prompt template and its variables.
-
+    """
+    Reference to a prompt template and its variables.
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
diff --git a/src/openai/types/responses/response.py b/src/openai/types/responses/response.py
@@ -180,8 +180,8 @@ class Response(BaseModel):
     """
 
     prompt: Optional[ResponsePrompt] = None
-    """Reference to a prompt template and its variables.
-
+    """
+    Reference to a prompt template and its variables.
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
diff --git a/src/openai/types/responses/response_code_interpreter_tool_call.py b/src/openai/types/responses/response_code_interpreter_tool_call.py
@@ -39,9 +39,9 @@ class ResponseCodeInterpreterToolCall(BaseModel):
     """The ID of the container used to run the code."""
 
     outputs: Optional[List[Output]] = None
-    """The outputs generated by the code interpreter, such as logs or images.
-
-    Can be null if no outputs are available.
+    """
+    The outputs generated by the code interpreter, such as logs or images. Can be
+    null if no outputs are available.
     """
 
     status: Literal["in_progress", "completed", "incomplete", "interpreting", "failed"]
diff --git a/src/openai/types/responses/response_code_interpreter_tool_call_param.py b/src/openai/types/responses/response_code_interpreter_tool_call_param.py
@@ -38,9 +38,9 @@ class ResponseCodeInterpreterToolCallParam(TypedDict, total=False):
     """The ID of the container used to run the code."""
 
     outputs: Required[Optional[Iterable[Output]]]
-    """The outputs generated by the code interpreter, such as logs or images.
-
-    Can be null if no outputs are available.
+    """
+    The outputs generated by the code interpreter, such as logs or images. Can be
+    null if no outputs are available.
     """
 
     status: Required[Literal["in_progress", "completed", "incomplete", "interpreting", "failed"]]
diff --git a/src/openai/types/responses/response_create_params.py b/src/openai/types/responses/response_create_params.py
@@ -134,8 +134,8 @@ class ResponseCreateParamsBase(TypedDict, total=False):
     """
 
     prompt: Optional[ResponsePromptParam]
-    """Reference to a prompt template and its variables.
-
+    """
+    Reference to a prompt template and its variables.
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
