From 06fddc2852e79b5730d03316dfe1df60e8d7bb04 Mon Sep 17 00:00:00 2001 From: Justin Beckwith Date: Wed, 28 Oct 2026 17:53:48 +0000 Subject: [PATCH] feat(api): add response tool usage models Castiron-Internal-PR: https://github.com/openai/openai-python-internal/pull/370 Castiron-Source-SHA: a8e3aeb6d14653046c1b7dbcfcba3569140267b3 Castiron-Public-Base-SHA: 77fd116d2326bc828bb23d4fd7960142972293a4 --- .castiron.stats.yml | 10 +- api_reference/openapi.transformed.yml | 180 +++++++++++++++++++++++++ scripts/castiron/generated-files.json | 4 +- src/openai/types/beta/beta_response.py | 102 ++++++++++++++ src/openai/types/responses/response.py | 102 ++++++++++++++ 5 files changed, 391 insertions(+), 7 deletions(-) diff --git a/.castiron.stats.yml b/.castiron.stats.yml index db9f7ad128..058f52d7e9 100644 --- a/.castiron.stats.yml +++ b/.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 diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml index b21f631c57..5662ced2ba 100644 --- a/api_reference/openapi.transformed.yml +++ b/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: diff --git a/scripts/castiron/generated-files.json b/scripts/castiron/generated-files.json index 2df97f3a26..f8524546c7 100644 --- a/scripts/castiron/generated-files.json +++ b/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", diff --git a/src/openai/types/beta/beta_response.py b/src/openai/types/beta/beta_response.py index e197f1ee6b..9fc420d1ab 100644 --- a/src/openai/types/beta/beta_response.py +++ b/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 diff --git a/src/openai/types/responses/response.py b/src/openai/types/responses/response.py index 3ec1fd01f5..9457f7ffc2 100644 --- a/src/openai/types/responses/response.py +++ b/src/openai/types/responses/response.py @@ -46,6 +46,12 @@ "PromptCacheDiagnosticsComparisonResponseNotFound", "PromptCacheDiagnosticsUnavailable", "PromptCacheOptions", + "ToolUsage", + "ToolUsageImageGen", + "ToolUsageImageGenInputTokensDetails", + "ToolUsageImageGenCachedTokensDetails", + "ToolUsageImageGenOutputTokensDetails", + "ToolUsageWebSearch", ] @@ -263,6 +269,86 @@ class PromptCacheOptions(BaseModel): """The response ID supplied as the prompt cache diagnostics comparison.""" +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 Response(BaseModel): id: str """Unique identifier for this Response.""" @@ -520,6 +606,22 @@ class Response(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