Skip to content

Commit abe56f8

Browse files
stainless-app[bot]stainless-app[bot]
committed
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.
1 parent 94569a0 commit abe56f8

File tree

6 files changed

+185
-9
lines changed

6 files changed

+185
-9
lines changed

‎.stats.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
configured_endpoints: 118
2-
openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-410219ea680089f02bb55163c673919703f946c3d6ad7ff5d6f607121d5287d5.yml
3-
openapi_spec_hash: 2b3eee95d3f6796c7a61dfddf694a59a
4-
config_hash: 666d6bb4b564f0d9d431124b5d1a0665
2+
openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-49233088b5e73dbb96bf7af27be3d4547632e3db1c2b00f14184900613325bbc.yml
3+
openapi_spec_hash: b34f14b141d5019244112901c5c7c2d8
4+
config_hash: 94e9ba08201c3d1ca46e093e6a0138fa

‎api.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -614,6 +614,7 @@ Types:
614614
- <code><a href="./src/resources/batches.ts">Batch</a></code>
615615
- <code><a href="./src/resources/batches.ts">BatchError</a></code>
616616
- <code><a href="./src/resources/batches.ts">BatchRequestCounts</a></code>
617+
- <code><a href="./src/resources/batches.ts">BatchUsage</a></code>
617618

618619
Methods:
619620

@@ -688,6 +689,8 @@ Types:
688689
- <code><a href="./src/resources/responses/responses.ts">ResponseFormatTextJSONSchemaConfig</a></code>
689690
- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionCallArgumentsDeltaEvent</a></code>
690691
- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionCallArgumentsDoneEvent</a></code>
692+
- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionCallOutputItem</a></code>
693+
- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionCallOutputItemList</a></code>
691694
- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionToolCall</a></code>
692695
- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionToolCallItem</a></code>
693696
- <code><a href="./src/resources/responses/responses.ts">ResponseFunctionToolCallOutputItem</a></code>
@@ -703,11 +706,14 @@ Types:
703706
- <code><a href="./src/resources/responses/responses.ts">ResponseInputAudio</a></code>
704707
- <code><a href="./src/resources/responses/responses.ts">ResponseInputContent</a></code>
705708
- <code><a href="./src/resources/responses/responses.ts">ResponseInputFile</a></code>
709+
- <code><a href="./src/resources/responses/responses.ts">ResponseInputFileContent</a></code>
706710
- <code><a href="./src/resources/responses/responses.ts">ResponseInputImage</a></code>
711+
- <code><a href="./src/resources/responses/responses.ts">ResponseInputImageContent</a></code>
707712
- <code><a href="./src/resources/responses/responses.ts">ResponseInputItem</a></code>
708713
- <code><a href="./src/resources/responses/responses.ts">ResponseInputMessageContentList</a></code>
709714
- <code><a href="./src/resources/responses/responses.ts">ResponseInputMessageItem</a></code>
710715
- <code><a href="./src/resources/responses/responses.ts">ResponseInputText</a></code>
716+
- <code><a href="./src/resources/responses/responses.ts">ResponseInputTextContent</a></code>
711717
- <code><a href="./src/resources/responses/responses.ts">ResponseItem</a></code>
712718
- <code><a href="./src/resources/responses/responses.ts">ResponseMcpCallArgumentsDeltaEvent</a></code>
713719
- <code><a href="./src/resources/responses/responses.ts">ResponseMcpCallArgumentsDoneEvent</a></code>

‎src/client.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ import {
3232
BatchError,
3333
BatchListParams,
3434
BatchRequestCounts,
35+
BatchUsage,
3536
Batches,
3637
BatchesPage,
3738
} from './resources/batches';
@@ -1190,6 +1191,7 @@ export declare namespace OpenAI {
11901191
type Batch as Batch,
11911192
type BatchError as BatchError,
11921193
type BatchRequestCounts as BatchRequestCounts,
1194+
type BatchUsage as BatchUsage,
11931195
type BatchesPage as BatchesPage,
11941196
type BatchCreateParams as BatchCreateParams,
11951197
type BatchListParams as BatchListParams,

‎src/resources/batches.ts‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,15 @@ export interface Batch {
143143
*/
144144
metadata?: Shared.Metadata | null;
145145

146+
/**
147+
* Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI offers a
148+
* wide range of models with different capabilities, performance characteristics,
149+
* and price points. Refer to the
150+
* [model guide](https://platform.openai.com/docs/models) to browse and compare
151+
* available models.
152+
*/
153+
model?: string;
154+
146155
/**
147156
* The ID of the file containing the outputs of successfully executed requests.
148157
*/
@@ -152,6 +161,13 @@ export interface Batch {
152161
* The request counts for different statuses within the batch.
153162
*/
154163
request_counts?: BatchRequestCounts;
164+
165+
/**
166+
* Represents token usage details including input tokens, output tokens, a
167+
* breakdown of output tokens, and the total tokens used. Only populated on batches
168+
* created after September 7, 2025.
169+
*/
170+
usage?: BatchUsage;
155171
}
156172

157173
export namespace Batch {
@@ -207,6 +223,61 @@ export interface BatchRequestCounts {
207223
total: number;
208224
}
209225

226+
/**
227+
* Represents token usage details including input tokens, output tokens, a
228+
* breakdown of output tokens, and the total tokens used. Only populated on batches
229+
* created after September 7, 2025.
230+
*/
231+
export interface BatchUsage {
232+
/**
233+
* The number of input tokens.
234+
*/
235+
input_tokens: number;
236+
237+
/**
238+
* A detailed breakdown of the input tokens.
239+
*/
240+
input_tokens_details: BatchUsage.InputTokensDetails;
241+
242+
/**
243+
* The number of output tokens.
244+
*/
245+
output_tokens: number;
246+
247+
/**
248+
* A detailed breakdown of the output tokens.
249+
*/
250+
output_tokens_details: BatchUsage.OutputTokensDetails;
251+
252+
/**
253+
* The total number of tokens used.
254+
*/
255+
total_tokens: number;
256+
}
257+
258+
export namespace BatchUsage {
259+
/**
260+
* A detailed breakdown of the input tokens.
261+
*/
262+
export interface InputTokensDetails {
263+
/**
264+
* The number of tokens that were retrieved from the cache.
265+
* [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
266+
*/
267+
cached_tokens: number;
268+
}
269+
270+
/**
271+
* A detailed breakdown of the output tokens.
272+
*/
273+
export interface OutputTokensDetails {
274+
/**
275+
* The number of reasoning tokens.
276+
*/
277+
reasoning_tokens: number;
278+
}
279+
}
280+
210281
export interface BatchCreateParams {
211282
/**
212283
* The time frame within which the batch should be processed. Currently only `24h`
@@ -280,6 +351,7 @@ export declare namespace Batches {
280351
type Batch as Batch,
281352
type BatchError as BatchError,
282353
type BatchRequestCounts as BatchRequestCounts,
354+
type BatchUsage as BatchUsage,
283355
type BatchesPage as BatchesPage,
284356
type BatchCreateParams as BatchCreateParams,
285357
type BatchListParams as BatchListParams,

‎src/resources/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ export {
88
type Batch,
99
type BatchError,
1010
type BatchRequestCounts,
11+
type BatchUsage,
1112
type BatchCreateParams,
1213
type BatchListParams,
1314
type BatchesPage,

‎src/resources/responses/responses.ts‎

Lines changed: 101 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1536,9 +1536,10 @@ export interface ResponseCustomToolCallOutput {
15361536
call_id: string;
15371537

15381538
/**
1539-
* The output from the custom tool call generated by your code.
1539+
* The output from the custom tool call generated by your code. Can be a string or
1540+
* an list of output content.
15401541
*/
1541-
output: string;
1542+
output: string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>;
15421543

15431544
/**
15441545
* The type of the custom tool call output. Always `custom_tool_call_output`.
@@ -1878,6 +1879,11 @@ export interface ResponseFunctionCallArgumentsDoneEvent {
18781879
*/
18791880
item_id: string;
18801881

1882+
/**
1883+
* The name of the function that was called.
1884+
*/
1885+
name: string;
1886+
18811887
/**
18821888
* The index of the output item.
18831889
*/
@@ -1891,6 +1897,16 @@ export interface ResponseFunctionCallArgumentsDoneEvent {
18911897
type: 'response.function_call_arguments.done';
18921898
}
18931899

1900+
/**
1901+
* A text input to the model.
1902+
*/
1903+
export type ResponseFunctionCallOutputItem =
1904+
| ResponseInputTextContent
1905+
| ResponseInputImageContent
1906+
| ResponseInputFileContent;
1907+
1908+
export type ResponseFunctionCallOutputItemList = Array<ResponseFunctionCallOutputItem>;
1909+
18941910
/**
18951911
* A tool call to run a function. See the
18961912
* [function calling guide](https://platform.openai.com/docs/guides/function-calling)
@@ -1953,9 +1969,10 @@ export interface ResponseFunctionToolCallOutputItem {
19531969
call_id: string;
19541970

19551971
/**
1956-
* A JSON string of the output of the function tool call.
1972+
* The output from the function call generated by your code. Can be a string or an
1973+
* list of output content.
19571974
*/
1958-
output: string;
1975+
output: string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>;
19591976

19601977
/**
19611978
* The type of the function tool call output. Always `function_call_output`.
@@ -2319,6 +2336,36 @@ export interface ResponseInputFile {
23192336
filename?: string;
23202337
}
23212338

2339+
/**
2340+
* A file input to the model.
2341+
*/
2342+
export interface ResponseInputFileContent {
2343+
/**
2344+
* The type of the input item. Always `input_file`.
2345+
*/
2346+
type: 'input_file';
2347+
2348+
/**
2349+
* The base64-encoded data of the file to be sent to the model.
2350+
*/
2351+
file_data?: string | null;
2352+
2353+
/**
2354+
* The ID of the file to be sent to the model.
2355+
*/
2356+
file_id?: string | null;
2357+
2358+
/**
2359+
* The URL of the file to be sent to the model.
2360+
*/
2361+
file_url?: string | null;
2362+
2363+
/**
2364+
* The name of the file to be sent to the model.
2365+
*/
2366+
filename?: string | null;
2367+
}
2368+
23222369
/**
23232370
* An image input to the model. Learn about
23242371
* [image inputs](https://platform.openai.com/docs/guides/vision).
@@ -2347,6 +2394,34 @@ export interface ResponseInputImage {
23472394
image_url?: string | null;
23482395
}
23492396

2397+
/**
2398+
* An image input to the model. Learn about
2399+
* [image inputs](https://platform.openai.com/docs/guides/vision)
2400+
*/
2401+
export interface ResponseInputImageContent {
2402+
/**
2403+
* The type of the input item. Always `input_image`.
2404+
*/
2405+
type: 'input_image';
2406+
2407+
/**
2408+
* The detail level of the image to be sent to the model. One of `high`, `low`, or
2409+
* `auto`. Defaults to `auto`.
2410+
*/
2411+
detail?: 'low' | 'high' | 'auto' | null;
2412+
2413+
/**
2414+
* The ID of the file to be sent to the model.
2415+
*/
2416+
file_id?: string | null;
2417+
2418+
/**
2419+
* The URL of the image to be sent to the model. A fully qualified URL or base64
2420+
* encoded image in a data URL.
2421+
*/
2422+
image_url?: string | null;
2423+
}
2424+
23502425
/**
23512426
* A message input to the model with a role indicating instruction following
23522427
* hierarchy. Instructions given with the `developer` or `system` role take
@@ -2476,9 +2551,9 @@ export namespace ResponseInputItem {
24762551
call_id: string;
24772552

24782553
/**
2479-
* A JSON string of the output of the function tool call.
2554+
* Text, image, or file output of the function tool call.
24802555
*/
2481-
output: string;
2556+
output: string | ResponsesAPI.ResponseFunctionCallOutputItemList;
24822557

24832558
/**
24842559
* The type of the function tool call output. Always `function_call_output`.
@@ -2838,6 +2913,21 @@ export interface ResponseInputText {
28382913
type: 'input_text';
28392914
}
28402915

2916+
/**
2917+
* A text input to the model.
2918+
*/
2919+
export interface ResponseInputTextContent {
2920+
/**
2921+
* The text input to the model.
2922+
*/
2923+
text: string;
2924+
2925+
/**
2926+
* The type of the input item. Always `input_text`.
2927+
*/
2928+
type: 'input_text';
2929+
}
2930+
28412931
/**
28422932
* Content item used to generate a response.
28432933
*/
@@ -5684,6 +5774,8 @@ export declare namespace Responses {
56845774
type ResponseFormatTextJSONSchemaConfig as ResponseFormatTextJSONSchemaConfig,
56855775
type ResponseFunctionCallArgumentsDeltaEvent as ResponseFunctionCallArgumentsDeltaEvent,
56865776
type ResponseFunctionCallArgumentsDoneEvent as ResponseFunctionCallArgumentsDoneEvent,
5777+
type ResponseFunctionCallOutputItem as ResponseFunctionCallOutputItem,
5778+
type ResponseFunctionCallOutputItemList as ResponseFunctionCallOutputItemList,
56875779
type ResponseFunctionToolCall as ResponseFunctionToolCall,
56885780
type ResponseFunctionToolCallItem as ResponseFunctionToolCallItem,
56895781
type ResponseFunctionToolCallOutputItem as ResponseFunctionToolCallOutputItem,
@@ -5699,11 +5791,14 @@ export declare namespace Responses {
56995791
type ResponseInputAudio as ResponseInputAudio,
57005792
type ResponseInputContent as ResponseInputContent,
57015793
type ResponseInputFile as ResponseInputFile,
5794+
type ResponseInputFileContent as ResponseInputFileContent,
57025795
type ResponseInputImage as ResponseInputImage,
5796+
type ResponseInputImageContent as ResponseInputImageContent,
57035797
type ResponseInputItem as ResponseInputItem,
57045798
type ResponseInputMessageContentList as ResponseInputMessageContentList,
57055799
type ResponseInputMessageItem as ResponseInputMessageItem,
57065800
type ResponseInputText as ResponseInputText,
5801+
type ResponseInputTextContent as ResponseInputTextContent,
57075802
type ResponseItem as ResponseItem,
57085803
type ResponseMcpCallArgumentsDeltaEvent as ResponseMcpCallArgumentsDeltaEvent,
57095804
type ResponseMcpCallArgumentsDoneEvent as ResponseMcpCallArgumentsDoneEvent,

0 commit comments

Comments
 (0)