feat(api): add response tool usage models (#4201)

## Summary

Adds optional hosted tool usage to stable and beta Responses, separately
from model token usage.

## Changes

- Read image tool token totals and input/output details from response
tool usage.
- Read billable web-search request counts and optional cached image/text
token details.
- Existing response fields and omission behavior remain unchanged.

Author: jbeckwith-oai

.castiron.stats.yml

@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: 45c2be6c-9b78-4bff-b88b-f437435ae397
-openapi_spec_hash: 7b8e0964b34b0cf993d2e2946e8eac7a
-openapi_transformed_spec_hash: 096782182a5f2b2d0d09fb4822e35e10
+generation_id: c181b60a-9c3f-4fab-adb0-ec99e1b9164b
+openapi_spec_hash: d86a987b0943f67209611629cfe2926f
+openapi_transformed_spec_hash: f98b6939664e5171dadad31a12ecf50a
 config_hash: 0e042fd083471fc089bcbfe7011a7d01
-codegen_sha: 2d3d72e9eb4ebaca41912b7d0ce1bc8733a90569
-codegen_hash: fec5e33e84cf8605506e7b95a1dd30735e4cffe16ec560150a65b669d4975ebd
+codegen_sha: e7d3eec72178efe4bd1c41d2923c5636e5f41500
+codegen_hash: 5808ff69b455e321be73db3a9c2640505dddd64b0418583f71301147baa3171d

api_reference/openapi.transformed.yml

@@ -64187,6 +64187,21 @@ components:
                 An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning).
               type: integer
             - type: 'null'
+          tool_usage:
+            $ref: '#/components/schemas/ResponseToolUsage'
+            description: |
+              Usage reported by hosted tools, separate from base model `usage`. The field
+              can be omitted when tool usage is unavailable. When present, tool families
+              with no recorded usage have zero counts.
+
+              `image_gen` sums available token counts across image generation calls.
+              Calls with missing or incomplete usage records may be skipped. Output
+              token details and cached input counts can be omitted. An omitted cache
+              count means cache usage is unknown.
+
+              `web_search.num_requests` counts billable searches. Discounted searches
+              and actions such as opening a page are excluded. Use billing records to
+              reconcile final charges.
         required:
         - access_programs
         - id
@@ -105084,6 +105099,21 @@ components:
                 An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning).
               type: integer
             - type: 'null'
+          tool_usage:
+            $ref: '#/components/schemas/BetaResponseToolUsage'
+            description: |
+              Usage reported by hosted tools, separate from base model `usage`. The field
+              can be omitted when tool usage is unavailable. When present, tool families
+              with no recorded usage have zero counts.
+
+              `image_gen` sums available token counts across image generation calls.
+              Calls with missing or incomplete usage records may be skipped. Output
+              token details and cached input counts can be omitted. An omitted cache
+              count means cache usage is unknown.
+
+              `web_search.num_requests` counts billable searches. Discounted searches
+              and actions such as opening a page are excluded. Use billing records to
+              reconcile final charges.
         required:
         - access_programs
         - id
@@ -110498,6 +110528,156 @@ components:
       - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent'
       discriminator:
         propertyName: type
+    BetaCachedUsageDetails:
+      properties:
+        cached_text_tokens:
+          type: integer
+        cached_image_tokens:
+          type: integer
+      type: object
+      required:
+      - cached_text_tokens
+      - cached_image_tokens
+    BetaImageGenInputUsageDetails:
+      properties:
+        text_tokens:
+          type: integer
+          description: The number of text tokens in the input prompt.
+        image_tokens:
+          type: integer
+          description: The number of image tokens in the input prompt.
+      type: object
+      required:
+      - text_tokens
+      - image_tokens
+      title: Input usage details
+      description: The input tokens detailed information for the image generation.
+    BetaImageGenOutputTokensDetails:
+      properties:
+        image_tokens:
+          type: integer
+          description: The number of image output tokens generated by the model.
+        text_tokens:
+          type: integer
+          description: The number of text output tokens generated by the model.
+      type: object
+      required:
+      - image_tokens
+      - text_tokens
+      title: Image generation output token details
+      description: The output token details for the image generation.
+    BetaImageGenToolUsage:
+      properties:
+        input_tokens:
+          type: integer
+          description: The number of tokens (images and text) in the input prompt.
+        total_tokens:
+          type: integer
+          description: The total number of tokens (images and text) used for the image generation.
+        output_tokens:
+          type: integer
+          description: The number of output tokens generated by the model.
+        output_tokens_details:
+          $ref: '#/components/schemas/BetaImageGenOutputTokensDetails'
+        input_tokens_details:
+          $ref: '#/components/schemas/BetaImageGenInputUsageDetails'
+        cached_tokens:
+          type: integer
+        cached_tokens_details:
+          $ref: '#/components/schemas/BetaCachedUsageDetails'
+      type: object
+      required:
+      - input_tokens
+      - total_tokens
+      - output_tokens
+      - input_tokens_details
+      title: Image generation tool usage
+      description: Token usage for image generation tool calls in a response.
+    BetaResponseToolUsage:
+      properties:
+        image_gen:
+          $ref: '#/components/schemas/BetaImageGenToolUsage'
+          description: Aggregated usage statistics for image generation tool calls.
+        web_search:
+          $ref: '#/components/schemas/BetaWebSearchUsage'
+          description: Aggregated billable usage statistics for web search tool calls.
+      type: object
+      required:
+      - image_gen
+      - web_search
+      title: Response tool usage
+      description: Aggregated usage details for billable tools that ran while generating the response.
+    BetaWebSearchUsage:
+      properties:
+        num_requests:
+          type: integer
+          description: The number of billable web search requests issued.
+      type: object
+      required:
+      - num_requests
+      title: Web search usage
+      description: Usage details for web search requests that ran while generating the response.
+    CachedUsageDetails:
+      properties:
+        cached_text_tokens:
+          type: integer
+        cached_image_tokens:
+          type: integer
+      type: object
+      required:
+      - cached_text_tokens
+      - cached_image_tokens
+    ImageGenToolUsage:
+      properties:
+        input_tokens:
+          type: integer
+          description: The number of tokens (images and text) in the input prompt.
+        total_tokens:
+          type: integer
+          description: The total number of tokens (images and text) used for the image generation.
+        output_tokens:
+          type: integer
+          description: The number of output tokens generated by the model.
+        output_tokens_details:
+          $ref: '#/components/schemas/ImageGenOutputTokensDetails'
+        input_tokens_details:
+          $ref: '#/components/schemas/ImageGenInputUsageDetails'
+        cached_tokens:
+          type: integer
+        cached_tokens_details:
+          $ref: '#/components/schemas/CachedUsageDetails'
+      type: object
+      required:
+      - input_tokens
+      - total_tokens
+      - output_tokens
+      - input_tokens_details
+      title: Image generation tool usage
+      description: Token usage for image generation tool calls in a response.
+    ResponseToolUsage:
+      properties:
+        image_gen:
+          $ref: '#/components/schemas/ImageGenToolUsage'
+          description: Aggregated usage statistics for image generation tool calls.
+        web_search:
+          $ref: '#/components/schemas/WebSearchUsage'
+          description: Aggregated billable usage statistics for web search tool calls.
+      type: object
+      required:
+      - image_gen
+      - web_search
+      title: Response tool usage
+      description: Aggregated usage details for billable tools that ran while generating the response.
+    WebSearchUsage:
+      properties:
+        num_requests:
+          type: integer
+          description: The number of billable web search requests issued.
+      type: object
+      required:
+      - num_requests
+      title: Web search usage
+      description: Usage details for web search requests that ran while generating the response.
     SessionSpendControlResource:
       type: object
       properties:

scripts/castiron/generated-files.json

@@ -2407,7 +2407,7 @@
     },
     "src/openai/types/beta/beta_response.py": {
       "mode": "100644",
-      "sha256": "51b540b82d5eabd7aad037a89094abaa9e5ec4d3d4c2aa5226a69ee2dd62311d"
+      "sha256": "f9f8e9f29fc43a743592cd89636dfbe967fe189d47914e8c847a2a396d9af45c"
     },
     "src/openai/types/beta/beta_response_apply_patch_tool_call.py": {
       "mode": "100644",
@@ -6047,7 +6047,7 @@
     },
     "src/openai/types/responses/response.py": {
       "mode": "100644",
-      "sha256": "fad55bfc5e659ed5ab1bc04c85628c5ba09ac59180e21bdad7620abfc955cc14"
+      "sha256": "b7f94706e91b9e0c7e857b74c0ea2430ec4f3a8f645833e9490d33d57f6b8ee0"
     },
     "src/openai/types/responses/response_apply_patch_tool_call.py": {
       "mode": "100644",

src/openai/types/beta/beta_response.py

@@ -44,6 +44,12 @@
     "PromptCacheDiagnosticsUnavailable",
     "PromptCacheOptions",
     "Reasoning",
+    "ToolUsage",
+    "ToolUsageImageGen",
+    "ToolUsageImageGenInputTokensDetails",
+    "ToolUsageImageGenCachedTokensDetails",
+    "ToolUsageImageGenOutputTokensDetails",
+    "ToolUsageWebSearch",
 ]
 
 
@@ -313,6 +319,86 @@ class Reasoning(BaseModel):
     """
 
 
+class ToolUsageImageGenInputTokensDetails(BaseModel):
+    """The input tokens detailed information for the image generation."""
+
+    image_tokens: int
+    """The number of image tokens in the input prompt."""
+
+    text_tokens: int
+    """The number of text tokens in the input prompt."""
+
+
+class ToolUsageImageGenCachedTokensDetails(BaseModel):
+    cached_image_tokens: int
+
+    cached_text_tokens: int
+
+
+class ToolUsageImageGenOutputTokensDetails(BaseModel):
+    """The output token details for the image generation."""
+
+    image_tokens: int
+    """The number of image output tokens generated by the model."""
+
+    text_tokens: int
+    """The number of text output tokens generated by the model."""
+
+
+class ToolUsageImageGen(BaseModel):
+    """Aggregated usage statistics for image generation tool calls."""
+
+    input_tokens: int
+    """The number of tokens (images and text) in the input prompt."""
+
+    input_tokens_details: ToolUsageImageGenInputTokensDetails
+    """The input tokens detailed information for the image generation."""
+
+    output_tokens: int
+    """The number of output tokens generated by the model."""
+
+    total_tokens: int
+    """The total number of tokens (images and text) used for the image generation."""
+
+    cached_tokens: Optional[int] = None
+
+    cached_tokens_details: Optional[ToolUsageImageGenCachedTokensDetails] = None
+
+    output_tokens_details: Optional[ToolUsageImageGenOutputTokensDetails] = None
+    """The output token details for the image generation."""
+
+
+class ToolUsageWebSearch(BaseModel):
+    """Aggregated billable usage statistics for web search tool calls."""
+
+    num_requests: int
+    """The number of billable web search requests issued."""
+
+
+class ToolUsage(BaseModel):
+    """Usage reported by hosted tools, separate from base model `usage`.
+
+    The field
+    can be omitted when tool usage is unavailable. When present, tool families
+    with no recorded usage have zero counts.
+
+    `image_gen` sums available token counts across image generation calls.
+    Calls with missing or incomplete usage records may be skipped. Output
+    token details and cached input counts can be omitted. An omitted cache
+    count means cache usage is unknown.
+
+    `web_search.num_requests` counts billable searches. Discounted searches
+    and actions such as opening a page are excluded. Use billing records to
+    reconcile final charges.
+    """
+
+    image_gen: ToolUsageImageGen
+    """Aggregated usage statistics for image generation tool calls."""
+
+    web_search: ToolUsageWebSearch
+    """Aggregated billable usage statistics for web search tool calls."""
+
+
 class BetaResponse(BaseModel):
     id: str
     """Unique identifier for this Response."""
@@ -761,6 +847,22 @@ class BetaResponse(BaseModel):
     - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)
     """
 
+    tool_usage: Optional[ToolUsage] = None
+    """Usage reported by hosted tools, separate from base model `usage`.
+
+    The field can be omitted when tool usage is unavailable. When present, tool
+    families with no recorded usage have zero counts.
+
+    `image_gen` sums available token counts across image generation calls. Calls
+    with missing or incomplete usage records may be skipped. Output token details
+    and cached input counts can be omitted. An omitted cache count means cache usage
+    is unknown.
+
+    `web_search.num_requests` counts billable searches. Discounted searches and
+    actions such as opening a page are excluded. Use billing records to reconcile
+    final charges.
+    """
+
     top_logprobs: Optional[int] = None
     """
     An integer between 0 and 20 specifying the maximum number of most likely tokens