chore(api): clarify decision creation documentation

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: d684fcff-6802-4c99-a1f1-ec3e82c7a28a
-openapi_spec_hash: 42a295728420d694142db3ea197e8f1f
-openapi_transformed_spec_hash: 304d87d07f28f979aba884e31b424b78
+generation_id: a1523ba4-d770-4ff9-8933-837cc3707cfa
+openapi_spec_hash: fee0755337406af815cfdd9ddf03596f
+openapi_transformed_spec_hash: d9ee998234624c9d785d29c147c01ac9
 config_hash: 9f2131d7bd073baa8cb2730facaadf5a
-codegen_sha: de14060f722d7cd38a5e22199d9d68a16e371a89
-codegen_hash: eb03ff0c5bf766391dc8cb118aea58f895100a596d387daadfa51de0d34f5e70
-public_codegen_sha: ddd9b0c3f18de5bf8d4ace4fba974d64beb699ab
+codegen_sha: 1d601c1fd0f61a6d8973626635617190f64b525b
+codegen_hash: ac20ca7be8add7fe5fc4261071ea0a647f2257a91f4f0424ee5b45000b6984e8
+public_codegen_sha: 4ef2ec3876cd2b3fb2925d75217f916520ae3110

api_reference/openapi.transformed.yml

@@ -30100,11 +30100,11 @@ paths:
       operationId: createDecision
       summary: Create a decision
       description: |-
-        Evaluate ordered classification and scoring questions against shared input. Answers are returned in question order.
+        Use this endpoint to ask classification or scoring questions about the same input. You’ll get the answers back in the order you asked the questions.
 
-        Supply input as a string or user messages containing text and inline images. Only user messages with `input_text` and `input_image` parts are supported; non-user roles, function calls, files, audio, and item references are not supported. Images require a data URL, not an external URL or file ID. At most 128 images are allowed across the request.
+        For text, you can pass a string. You can also send user messages containing `input_text` and `input_image` parts, with up to 128 images per request. Images must be data URLs; external URLs and file IDs aren’t accepted. Other message roles, function calls, files, audio, and item references aren’t supported.
 
-        Each question can return a refusal instead of a scored answer. A refusal has type `refusal` and the corresponding question name, or null if unnamed.
+        Sometimes a question returns a refusal instead of an answer. The result has type `refusal` and includes the question’s name, or `null` if you didn’t give it one.
       tags:
       - Decisions
       requestBody:

src/openai/resources/decisions.py

@@ -54,18 +54,17 @@ def create(
         extra_body: Body | None = None,
         timeout: float | httpx2.Timeout | None | NotGiven = not_given,
     ) -> Decision:
-        """Evaluate ordered classification and scoring questions against shared input.
-
-        Answers are returned in question order.
+        """
+        Use this endpoint to ask classification or scoring questions about the same
+        input. You’ll get the answers back in the order you asked the questions.
 
-        Supply input as a string or user messages containing text and inline images.
-        Only user messages with `input_text` and `input_image` parts are supported;
-        non-user roles, function calls, files, audio, and item references are not
-        supported. Images require a data URL, not an external URL or file ID. At most
-        128 images are allowed across the request.
+        For text, you can pass a string. You can also send user messages containing
+        `input_text` and `input_image` parts, with up to 128 images per request. Images
+        must be data URLs; external URLs and file IDs aren’t accepted. Other message
+        roles, function calls, files, audio, and item references aren’t supported.
 
-        Each question can return a refusal instead of a scored answer. A refusal has
-        type `refusal` and the corresponding question name, or null if unnamed.
+        Sometimes a question returns a refusal instead of an answer. The result has type
+        `refusal` and includes the question’s name, or `null` if you didn’t give it one.
 
         Args:
           input: The text or images to evaluate for every question. Provide a text string or user
@@ -140,18 +139,17 @@ async def create(
         extra_body: Body | None = None,
         timeout: float | httpx2.Timeout | None | NotGiven = not_given,
     ) -> Decision:
-        """Evaluate ordered classification and scoring questions against shared input.
-
-        Answers are returned in question order.
+        """
+        Use this endpoint to ask classification or scoring questions about the same
+        input. You’ll get the answers back in the order you asked the questions.
 
-        Supply input as a string or user messages containing text and inline images.
-        Only user messages with `input_text` and `input_image` parts are supported;
-        non-user roles, function calls, files, audio, and item references are not
-        supported. Images require a data URL, not an external URL or file ID. At most
-        128 images are allowed across the request.
+        For text, you can pass a string. You can also send user messages containing
+        `input_text` and `input_image` parts, with up to 128 images per request. Images
+        must be data URLs; external URLs and file IDs aren’t accepted. Other message
+        roles, function calls, files, audio, and item references aren’t supported.
 
-        Each question can return a refusal instead of a scored answer. A refusal has
-        type `refusal` and the corresponding question name, or null if unnamed.
+        Sometimes a question returns a refusal instead of an answer. The result has type
+        `refusal` and includes the question’s name, or `null` if you didn’t give it one.
 
         Args:
           input: The text or images to evaluate for every question. Provide a text string or user