feat(api): Support images and files for function call outputs in responses, BatchUsage

This release introduces a major version change to reflect a breaking modification in the `ResponseFunctionToolCallOutputItem` and `ResponseCustomToolCallOutput` schemas. Specifically, the `output` field, which previously accepted only a `string` value, has been expanded to support multiple structured types:

```
Before:  output: string
After:   output: string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>
```

This change allows custom tool calls to return images, files, and rich text content in addition to plain strings, aligning `ResponseCustomToolCallOutput` with the broader `ResponseInput` type system. Because this alters the type and shape of the field, it may break existing callsites that only accept strings.

BREAKING CHANGE: `ResponseFunctionToolCallOutputItem.output` and `ResponseCustomToolCallOutput.output` now return `string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>` instead of `string` only. This may break existing callsites that assume `output` is always a string.

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-410219ea680089f02bb55163c673919703f946c3d6ad7ff5d6f607121d5287d5.yml
-openapi_spec_hash: 2b3eee95d3f6796c7a61dfddf694a59a
-config_hash: 666d6bb4b564f0d9d431124b5d1a0665
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-49233088b5e73dbb96bf7af27be3d4547632e3db1c2b00f14184900613325bbc.yml
+openapi_spec_hash: b34f14b141d5019244112901c5c7c2d8
+config_hash: 94e9ba08201c3d1ca46e093e6a0138fa

api.md

@@ -614,6 +614,7 @@ Types:
 - <code><a href="./src/resources/batches.ts">Batch</a></code>
 - <code><a href="./src/resources/batches.ts">BatchError</a></code>
 - <code><a href="./src/resources/batches.ts">BatchRequestCounts</a></code>
+- <code><a href="./src/resources/batches.ts">BatchUsage</a></code>
 
 Methods:
 
@@ -688,6 +689,8 @@ Types:
 - <code><a href="./src/resources/responses/responses.ts">ResponseFormatTextJSONSchemaConfig</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseFunctionCallArgumentsDeltaEvent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseFunctionCallArgumentsDoneEvent</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionCallOutputItem</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionCallOutputItemList</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseFunctionToolCall</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseFunctionToolCallItem</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseFunctionToolCallOutputItem</a></code>
@@ -703,11 +706,14 @@ Types:
 - <code><a href="./src/resources/responses/responses.ts">ResponseInputAudio</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseInputContent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseInputFile</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ResponseInputFileContent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseInputImage</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ResponseInputImageContent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseInputItem</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseInputMessageContentList</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseInputMessageItem</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseInputText</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ResponseInputTextContent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseItem</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseMcpCallArgumentsDeltaEvent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseMcpCallArgumentsDoneEvent</a></code>

src/client.ts

@@ -32,6 +32,7 @@ import {
   BatchError,
   BatchListParams,
   BatchRequestCounts,
+  BatchUsage,
   Batches,
   BatchesPage,
 } from './resources/batches';
@@ -1190,6 +1191,7 @@ export declare namespace OpenAI {
     type Batch as Batch,
     type BatchError as BatchError,
     type BatchRequestCounts as BatchRequestCounts,
+    type BatchUsage as BatchUsage,
     type BatchesPage as BatchesPage,
     type BatchCreateParams as BatchCreateParams,
     type BatchListParams as BatchListParams,

src/resources/batches.ts

@@ -143,6 +143,15 @@ export interface Batch {
    */
   metadata?: Shared.Metadata | null;
 
+  /**
+   * Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI offers a
+   * wide range of models with different capabilities, performance characteristics,
+   * and price points. Refer to the
+   * [model guide](https://platform.openai.com/docs/models) to browse and compare
+   * available models.
+   */
+  model?: string;
+
   /**
    * The ID of the file containing the outputs of successfully executed requests.
    */
@@ -152,6 +161,13 @@ export interface Batch {
    * The request counts for different statuses within the batch.
    */
   request_counts?: BatchRequestCounts;
+
+  /**
+   * Represents token usage details including input tokens, output tokens, a
+   * breakdown of output tokens, and the total tokens used. Only populated on batches
+   * created after September 7, 2025.
+   */
+  usage?: BatchUsage;
 }
 
 export namespace Batch {
@@ -207,6 +223,61 @@ export interface BatchRequestCounts {
   total: number;
 }
 
+/**
+ * Represents token usage details including input tokens, output tokens, a
+ * breakdown of output tokens, and the total tokens used. Only populated on batches
+ * created after September 7, 2025.
+ */
+export interface BatchUsage {
+  /**
+   * The number of input tokens.
+   */
+  input_tokens: number;
+
+  /**
+   * A detailed breakdown of the input tokens.
+   */
+  input_tokens_details: BatchUsage.InputTokensDetails;
+
+  /**
+   * The number of output tokens.
+   */
+  output_tokens: number;
+
+  /**
+   * A detailed breakdown of the output tokens.
+   */
+  output_tokens_details: BatchUsage.OutputTokensDetails;
+
+  /**
+   * The total number of tokens used.
+   */
+  total_tokens: number;
+}
+
+export namespace BatchUsage {
+  /**
+   * A detailed breakdown of the input tokens.
+   */
+  export interface InputTokensDetails {
+    /**
+     * The number of tokens that were retrieved from the cache.
+     * [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
+     */
+    cached_tokens: number;
+  }
+
+  /**
+   * A detailed breakdown of the output tokens.
+   */
+  export interface OutputTokensDetails {
+    /**
+     * The number of reasoning tokens.
+     */
+    reasoning_tokens: number;
+  }
+}
+
 export interface BatchCreateParams {
   /**
    * The time frame within which the batch should be processed. Currently only `24h`
@@ -280,6 +351,7 @@ export declare namespace Batches {
     type Batch as Batch,
     type BatchError as BatchError,
     type BatchRequestCounts as BatchRequestCounts,
+    type BatchUsage as BatchUsage,
     type BatchesPage as BatchesPage,
     type BatchCreateParams as BatchCreateParams,
     type BatchListParams as BatchListParams,

src/resources/index.ts

@@ -8,6 +8,7 @@ export {
   type Batch,
   type BatchError,
   type BatchRequestCounts,
+  type BatchUsage,
   type BatchCreateParams,
   type BatchListParams,
   type BatchesPage,

src/resources/responses/responses.ts

@@ -1536,9 +1536,10 @@ export interface ResponseCustomToolCallOutput {
   call_id: string;
 
   /**
-   * The output from the custom tool call generated by your code.
+   * The output from the custom tool call generated by your code. Can be a string or
+   * an list of output content.
    */
-  output: string;
+  output: string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>;
 
   /**
    * The type of the custom tool call output. Always `custom_tool_call_output`.
@@ -1878,6 +1879,11 @@ export interface ResponseFunctionCallArgumentsDoneEvent {
    */
   item_id: string;
 
+  /**
+   * The name of the function that was called.
+   */
+  name: string;
+
   /**
    * The index of the output item.
    */
@@ -1891,6 +1897,16 @@ export interface ResponseFunctionCallArgumentsDoneEvent {
   type: 'response.function_call_arguments.done';
 }
 
+/**
+ * A text input to the model.
+ */
+export type ResponseFunctionCallOutputItem =
+  | ResponseInputTextContent
+  | ResponseInputImageContent
+  | ResponseInputFileContent;
+
+export type ResponseFunctionCallOutputItemList = Array<ResponseFunctionCallOutputItem>;
+
 /**
  * A tool call to run a function. See the
  * [function calling guide](https://platform.openai.com/docs/guides/function-calling)
@@ -1953,9 +1969,10 @@ export interface ResponseFunctionToolCallOutputItem {
   call_id: string;
 
   /**
-   * A JSON string of the output of the function tool call.
+   * The output from the function call generated by your code. Can be a string or an
+   * list of output content.
    */
-  output: string;
+  output: string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>;
 
   /**
    * The type of the function tool call output. Always `function_call_output`.
@@ -2319,6 +2336,36 @@ export interface ResponseInputFile {
   filename?: string;
 }
 
+/**
+ * A file input to the model.
+ */
+export interface ResponseInputFileContent {
+  /**
+   * The type of the input item. Always `input_file`.
+   */
+  type: 'input_file';
+
+  /**
+   * The base64-encoded data of the file to be sent to the model.
+   */
+  file_data?: string | null;
+
+  /**
+   * The ID of the file to be sent to the model.
+   */
+  file_id?: string | null;
+
+  /**
+   * The URL of the file to be sent to the model.
+   */
+  file_url?: string | null;
+
+  /**
+   * The name of the file to be sent to the model.
+   */
+  filename?: string | null;
+}
+
 /**
  * An image input to the model. Learn about
  * [image inputs](https://platform.openai.com/docs/guides/vision).
@@ -2347,6 +2394,34 @@ export interface ResponseInputImage {
   image_url?: string | null;
 }
 
+/**
+ * An image input to the model. Learn about
+ * [image inputs](https://platform.openai.com/docs/guides/vision)
+ */
+export interface ResponseInputImageContent {
+  /**
+   * The type of the input item. Always `input_image`.
+   */
+  type: 'input_image';
+
+  /**
+   * The detail level of the image to be sent to the model. One of `high`, `low`, or
+   * `auto`. Defaults to `auto`.
+   */
+  detail?: 'low' | 'high' | 'auto' | null;
+
+  /**
+   * The ID of the file to be sent to the model.
+   */
+  file_id?: string | null;
+
+  /**
+   * The URL of the image to be sent to the model. A fully qualified URL or base64
+   * encoded image in a data URL.
+   */
+  image_url?: string | null;
+}
+
 /**
  * A message input to the model with a role indicating instruction following
  * hierarchy. Instructions given with the `developer` or `system` role take
@@ -2476,9 +2551,9 @@ export namespace ResponseInputItem {
     call_id: string;
 
     /**
-     * A JSON string of the output of the function tool call.
+     * Text, image, or file output of the function tool call.
      */
-    output: string;
+    output: string | ResponsesAPI.ResponseFunctionCallOutputItemList;
 
     /**
      * The type of the function tool call output. Always `function_call_output`.
@@ -2838,6 +2913,21 @@ export interface ResponseInputText {
   type: 'input_text';
 }
 
+/**
+ * A text input to the model.
+ */
+export interface ResponseInputTextContent {
+  /**
+   * The text input to the model.
+   */
+  text: string;
+
+  /**
+   * The type of the input item. Always `input_text`.
+   */
+  type: 'input_text';
+}
+
 /**
  * Content item used to generate a response.
  */
@@ -5684,6 +5774,8 @@ export declare namespace Responses {
     type ResponseFormatTextJSONSchemaConfig as ResponseFormatTextJSONSchemaConfig,
     type ResponseFunctionCallArgumentsDeltaEvent as ResponseFunctionCallArgumentsDeltaEvent,
     type ResponseFunctionCallArgumentsDoneEvent as ResponseFunctionCallArgumentsDoneEvent,
+    type ResponseFunctionCallOutputItem as ResponseFunctionCallOutputItem,
+    type ResponseFunctionCallOutputItemList as ResponseFunctionCallOutputItemList,
     type ResponseFunctionToolCall as ResponseFunctionToolCall,
     type ResponseFunctionToolCallItem as ResponseFunctionToolCallItem,
     type ResponseFunctionToolCallOutputItem as ResponseFunctionToolCallOutputItem,
@@ -5699,11 +5791,14 @@ export declare namespace Responses {
     type ResponseInputAudio as ResponseInputAudio,
     type ResponseInputContent as ResponseInputContent,
     type ResponseInputFile as ResponseInputFile,
+    type ResponseInputFileContent as ResponseInputFileContent,
     type ResponseInputImage as ResponseInputImage,
+    type ResponseInputImageContent as ResponseInputImageContent,
     type ResponseInputItem as ResponseInputItem,
     type ResponseInputMessageContentList as ResponseInputMessageContentList,
     type ResponseInputMessageItem as ResponseInputMessageItem,
     type ResponseInputText as ResponseInputText,
+    type ResponseInputTextContent as ResponseInputTextContent,
     type ResponseItem as ResponseItem,
     type ResponseMcpCallArgumentsDeltaEvent as ResponseMcpCallArgumentsDeltaEvent,
     type ResponseMcpCallArgumentsDoneEvent as ResponseMcpCallArgumentsDoneEvent,