diff --git a/en/java/resources/beta/subresources/responses/index.md b/en/java/resources/beta/subresources/responses/index.md index 38a04caa..d0f6eace 100644 --- a/en/java/resources/beta/subresources/responses/index.md +++ b/en/java/resources/beta/subresources/responses/index.md @@ -6,7 +6,13 @@ **post** `/responses?beta=true` -Create a model response +Creates a model response. Provide [text](https://platform.openai.com/docs/guides/text) or +[image](https://platform.openai.com/docs/guides/images) inputs to generate [text](https://platform.openai.com/docs/guides/text) +or [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have the model call +your own [custom code](https://platform.openai.com/docs/guides/function-calling) or use built-in +[tools](https://platform.openai.com/docs/guides/tools) like [web search](https://platform.openai.com/docs/guides/tools-web-search) +or [file search](https://platform.openai.com/docs/guides/tools-file-search) to use your own data +as input for the model's response. ### Parameters @@ -240,6 +246,8 @@ Create a model response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -495,6 +503,8 @@ Create a model response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -1631,7 +1641,11 @@ Create a model response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -1688,7 +1702,11 @@ Create a model response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -4747,6 +4765,8 @@ Create a model response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -5002,6 +5022,8 @@ Create a model response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -6138,7 +6160,11 @@ Create a model response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -6195,7 +6221,11 @@ Create a model response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -10953,7 +10983,7 @@ public final class Main { **get** `/responses/{response_id}?beta=true` -Get a model response +Retrieves a model response with the given ID. ### Parameters @@ -11234,6 +11264,8 @@ Get a model response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -11489,6 +11521,8 @@ Get a model response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -12625,7 +12659,11 @@ Get a model response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -12682,7 +12720,11 @@ Get a model response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -17440,7 +17482,7 @@ public final class Main { **delete** `/responses/{response_id}?beta=true` -Delete a model response +Deletes a model response with the given ID. ### Parameters @@ -17478,7 +17520,9 @@ public final class Main { **post** `/responses/{response_id}/cancel?beta=true` -Cancel a response +Cancels a model response with the given ID. Only responses created with +the `background` parameter set to `true` can be cancelled. +[Learn more](https://platform.openai.com/docs/guides/background). ### Parameters @@ -17724,6 +17768,8 @@ Cancel a response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -17979,6 +18025,8 @@ Cancel a response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -19115,7 +19163,11 @@ Cancel a response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -19172,7 +19224,11 @@ Cancel a response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -23930,7 +23986,9 @@ public final class Main { **post** `/responses/compact?beta=true` -Compact a response +Compact a conversation. Returns a compacted response object. + +Learn when and how to compact long-running conversations in the [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced). ### Parameters @@ -24290,6 +24348,8 @@ Compact a response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -24545,6 +24605,8 @@ Compact a response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -25681,7 +25743,11 @@ Compact a response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -25738,7 +25804,11 @@ Compact a response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -28088,6 +28158,8 @@ Compact a response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -29423,7 +29495,11 @@ Compact a response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -29480,7 +29556,11 @@ Compact a response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -31731,6 +31811,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -33066,7 +33148,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -33123,7 +33209,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -35678,6 +35768,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -35751,7 +35843,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -35808,7 +35904,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -36530,6 +36630,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -36785,6 +36887,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -37921,7 +38025,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -37978,7 +38086,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -43363,6 +43475,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -43618,6 +43732,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -44754,7 +44870,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -44811,7 +44931,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -50673,6 +50797,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -50928,6 +51054,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -52064,7 +52192,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -52121,7 +52253,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -57376,6 +57512,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -57631,6 +57769,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -58767,7 +58907,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -58824,7 +58968,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -64880,6 +65028,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -65135,6 +65285,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -66271,7 +66423,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -66328,7 +66484,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -71173,6 +71333,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -71428,6 +71590,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -72564,7 +72728,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -72621,7 +72789,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -77195,338 +77367,43 @@ public final class Main { The canonical name of the agent that produced this item. -### Beta Response Input Audio - -- `class BetaResponseInputAudio:` - - An audio input to the model. - - - `InputAudio inputAudio` - - - `String data` - - Base64-encoded audio data. - - - `Format format` - - The format of the audio data. Currently supported formats are `mp3` and - `wav`. - - - `MP3("mp3")` - - - `WAV("wav")` - - - `JsonValue; type "input_audio"constant` - - The type of the input item. Always `input_audio`. - - - `INPUT_AUDIO("input_audio")` - -### Beta Response Input Content - -- `class BetaResponseInputContent: A class that can be one of several variants.union` - - A text input to the model. - - - `class BetaResponseInputText:` - - A text input to the model. - - - `String text` - - The text input to the model. - - - `JsonValue; type "input_text"constant` - - The type of the input item. Always `input_text`. - - - `INPUT_TEXT("input_text")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `Detail detail` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `LOW("low")` - - - `HIGH("high")` - - - `AUTO("auto")` - - - `ORIGINAL("original")` - - - `JsonValue; type "input_image"constant` - - The type of the input item. Always `input_image`. - - - `INPUT_IMAGE("input_image")` - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional imageUrl` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `JsonValue; type "input_file"constant` - - The type of the input item. Always `input_file`. - - - `INPUT_FILE("input_file")` - - - `Optional detail` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. +### Beta Response Inject Created Event - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` +- `class BetaResponseInjectCreatedEvent:` - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - -### Beta Response Input File - -- `class BetaResponseInputFile:` - - A file input to the model. - - - `JsonValue; type "input_file"constant` - - The type of the input item. Always `input_file`. - - - `INPUT_FILE("input_file")` - - - `Optional detail` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - -### Beta Response Input File Content - -- `class BetaResponseInputFileContent:` - - A file input to the model. - - - `JsonValue; type "input_file"constant` - - The type of the input item. Always `input_file`. - - - `INPUT_FILE("input_file")` - - - `Optional detail` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` + Emitted when all injected input items were validated and committed to the + active response. - The base64-encoded data of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - -### Beta Response Input Image - -- `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `Detail detail` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `LOW("low")` - - - `HIGH("high")` - - - `AUTO("auto")` - - - `ORIGINAL("original")` - - - `JsonValue; type "input_image"constant` - - The type of the input item. Always `input_image`. - - - `INPUT_IMAGE("input_image")` - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional imageUrl` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - -### Beta Response Input Image Content - -- `class BetaResponseInputImageContent:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `JsonValue; type "input_image"constant` - - The type of the input item. Always `input_image`. - - - `INPUT_IMAGE("input_image")` - - - `Optional detail` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `LOW("low")` - - - `HIGH("high")` - - - `AUTO("auto")` + - `String responseId` - - `ORIGINAL("original")` + The ID of the response that accepted the input. - - `Optional fileId` + - `long sequenceNumber` - The ID of the file to be sent to the model. + The sequence number for this event. - - `Optional imageUrl` + - `JsonValue; type "response.inject.created"constant` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The event discriminator. Always `response.inject.created`. - - `Optional promptCacheBreakpoint` + - `RESPONSE_INJECT_CREATED("response.inject.created")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional streamId` - - `JsonValue; mode "explicit"constant` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - The breakpoint mode. Always `explicit`. +### Beta Response Inject Event - - `EXPLICIT("explicit")` +- `class BetaResponseInjectEvent:` -### Beta Response Input Item + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. -- `class BetaResponseInputItem: A class that can be one of several variants.union` + - `List input` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + Input items to inject into the active response. - `class BetaEasyInputMessage:` @@ -77676,6 +77553,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -77931,6 +77810,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -79067,7 +78948,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -79124,7 +79009,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -81206,18 +81095,60 @@ public final class Main { The canonical name of the agent that produced this item. -### Beta Response Input Message Item + - `String responseId` -- `class BetaResponseInputMessageItem:` + The ID of the active response that should receive the input. - - `String id` + - `JsonValue; type "response.inject"constant` - The unique ID of the message input. + The event discriminator. Always `response.inject`. - - `List content` + - `RESPONSE_INJECT("response.inject")` - A list of one or many input items to the model, containing different content - types. +### Beta Response Inject Failed Event + +- `class BetaResponseInjectFailedEvent:` + + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. + + - `Error error` + + Information about why the input was not committed. + + - `Code code` + + A machine-readable error code. + + - `RESPONSE_ALREADY_COMPLETED("response_already_completed")` + + - `RESPONSE_NOT_FOUND("response_not_found")` + + - `String message` + + A human-readable description of the error. + + - `List input` + + The raw input items that were not committed. + + - `class BetaEasyInputMessage:` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `Content content` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String` + + - `List` - `class BetaResponseInputText:` @@ -81331,102 +81262,34 @@ public final class Main { - `Role role` - The role of the message input. One of `user`, `system`, or `developer`. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - `USER("user")` + - `ASSISTANT("assistant")` + - `SYSTEM("system")` - `DEVELOPER("developer")` - - `JsonValue; type "message"constant` - - The type of the message input. Always set to `message`. - - - `MESSAGE("message")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional status` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - -### Beta Response Input Text - -- `class BetaResponseInputText:` - - A text input to the model. - - - `String text` - - The text input to the model. - - - `JsonValue; type "input_text"constant` - - The type of the input item. Always `input_text`. - - - `INPUT_TEXT("input_text")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - -### Beta Response Input Text Content - -- `class BetaResponseInputTextContent:` - - A text input to the model. - - - `String text` - - The text input to the model. - - - `JsonValue; type "input_text"constant` - - The type of the input item. Always `input_text`. - - - `INPUT_TEXT("input_text")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. + - `Optional phase` - - `EXPLICIT("explicit")` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. -### Beta Response Item + - `COMMENTARY("commentary")` -- `class BetaResponseItem: A class that can be one of several variants.union` + - `FINAL_ANSWER("final_answer")` - Content item used to generate a response. + - `Optional type` - - `class BetaResponseInputMessageItem:` + The type of the message input. Always `message`. - - `String id` + - `MESSAGE("message")` - The unique ID of the message input. + - `Message` - `List content` @@ -81437,112 +81300,14 @@ public final class Main { A text input to the model. - - `String text` - - The text input to the model. - - - `JsonValue; type "input_text"constant` - - The type of the input item. Always `input_text`. - - - `INPUT_TEXT("input_text")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - `class BetaResponseInputImage:` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Detail detail` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `LOW("low")` - - - `HIGH("high")` - - - `AUTO("auto")` - - - `ORIGINAL("original")` - - - `JsonValue; type "input_image"constant` - - The type of the input item. Always `input_image`. - - - `INPUT_IMAGE("input_image")` - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional imageUrl` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - `class BetaResponseInputFile:` A file input to the model. - - `JsonValue; type "input_file"constant` - - The type of the input item. Always `input_file`. - - - `INPUT_FILE("input_file")` - - - `Optional detail` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - `Role role` The role of the message input. One of `user`, `system`, or `developer`. @@ -81553,12 +81318,6 @@ public final class Main { - `DEVELOPER("developer")` - - `JsonValue; type "message"constant` - - The type of the message input. Always set to `message`. - - - `MESSAGE("message")` - - `Optional agent` The agent that produced this item. @@ -81578,6 +81337,12 @@ public final class Main { - `INCOMPLETE("incomplete")` + - `Optional type` + + The type of the message input. Always set to `message`. + + - `MESSAGE("message")` + - `class BetaResponseOutputMessage:` An output message from the model. @@ -81773,6 +81538,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -82103,11 +81870,7 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem:` - - - `String id` - - The unique ID of the computer call tool output. + - `ComputerCallOutput` - `String callId` @@ -82132,29 +81895,19 @@ public final class Main { The URL of the screenshot image. - - `Status status` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `FAILED("failed")` - - - `IN_PROGRESS("in_progress")` - - `JsonValue; type "computer_call_output"constant` The type of the computer tool call output. Always `computer_call_output`. - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `Optional id` + + The ID of the computer tool call output. + - `Optional> acknowledgedSafetyChecks` - The safety checks reported by the API that have been acknowledged by the - developer. + The safety checks reported by the API that have been acknowledged by the developer. - `String id` @@ -82176,9 +81929,15 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional status` - The identifier of the actor that created the item. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` - `class BetaResponseFunctionWebSearch:` @@ -82284,16 +82043,66 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCallItem:` + - `class BetaResponseFunctionToolCall:` A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `String id` + - `String arguments` + + A JSON string of the arguments to pass to the function. + + - `String callId` + + The unique ID of the function tool call generated by the model. + + - `String name` + + The name of the function to run. + + - `JsonValue; type "function_call"constant` + + The type of the function tool call. Always `function_call`. + + - `FUNCTION_CALL("function_call")` + + - `Optional id` The unique ID of the function tool call. - - `Status status` + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the function to run. + + - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -82304,15 +82113,7 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `class BetaResponseFunctionToolCallOutputItem:` - - - `String id` - - The unique ID of the function call tool output. + - `FunctionCallOutput` - `String callId` @@ -82320,189 +82121,191 @@ public final class Main { - `Output output` - The output from the function call generated by your code. - Can be a string or an list of output content. + Text, image, or file output of the function tool call. - `String` - - `List` + - `List` - - `class BetaResponseInputText:` + - `class BetaResponseInputTextContent:` A text input to the model. - - `class BetaResponseInputImage:` + - `String text` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The text input to the model. - - `class BetaResponseInputFile:` + - `JsonValue; type "input_text"constant` - A file input to the model. + The type of the input item. Always `input_text`. - - `Status status` + - `INPUT_TEXT("input_text")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional promptCacheBreakpoint` - - `IN_PROGRESS("in_progress")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `COMPLETED("completed")` + - `JsonValue; mode "explicit"constant` - - `INCOMPLETE("incomplete")` + The breakpoint mode. Always `explicit`. - - `JsonValue; type "function_call_output"constant` + - `EXPLICIT("explicit")` - The type of the function tool call output. Always `function_call_output`. + - `class BetaResponseInputImageContent:` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `Optional agent` + - `JsonValue; type "input_image"constant` - The agent that produced this item. + The type of the input item. Always `input_image`. - - `String agentName` + - `INPUT_IMAGE("input_image")` - The canonical name of the agent that produced this item. + - `Optional detail` - - `Optional caller` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The execution context that produced this tool call. + - `LOW("low")` - - `JsonValue;` + - `HIGH("high")` - - `JsonValue; type "direct"constant` + - `AUTO("auto")` - The caller type. Always `direct`. + - `ORIGINAL("original")` - - `DIRECT("direct")` + - `Optional fileId` - - `class Program:` + The ID of the file to be sent to the model. - - `String callerId` + - `Optional imageUrl` - The call ID of the program item that produced this tool call. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `JsonValue; type "program"constant` + - `Optional promptCacheBreakpoint` - The caller type. Always `program`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `PROGRAM("program")` + - `JsonValue; mode "explicit"constant` - - `Optional createdBy` + The breakpoint mode. Always `explicit`. - The identifier of the actor that created the item. + - `EXPLICIT("explicit")` - - `AgentMessage` + - `class BetaResponseInputFileContent:` - - `String id` + A file input to the model. - The unique ID of the agent message. + - `JsonValue; type "input_file"constant` - - `String author` + The type of the input item. Always `input_file`. - The sending agent identity. + - `INPUT_FILE("input_file")` - - `List content` + - `Optional detail` - Encrypted content sent between agents. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class BetaResponseInputText:` + - `AUTO("auto")` - A text input to the model. + - `LOW("low")` - - `class BetaResponseOutputText:` + - `HIGH("high")` - A text output from the model. + - `Optional fileData` - - `class Text:` + The base64-encoded data of the file to be sent to the model. - A text content. + - `Optional fileId` - - `String text` + The ID of the file to be sent to the model. - - `JsonValue; type "text"constant` + - `Optional fileUrl` - - `TEXT("text")` + The URL of the file to be sent to the model. - - `class SummaryText:` + - `Optional filename` - A summary text from the model. + The name of the file to be sent to the model. - - `String text` + - `Optional promptCacheBreakpoint` - A summary of the reasoning output from the model so far. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "summary_text"constant` + - `JsonValue; mode "explicit"constant` - The type of the object. Always `summary_text`. + The breakpoint mode. Always `explicit`. - - `SUMMARY_TEXT("summary_text")` + - `EXPLICIT("explicit")` - - `class ReasoningText:` + - `JsonValue; type "function_call_output"constant` - Reasoning text from the model. + The type of the function tool call output. Always `function_call_output`. - - `String text` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - The reasoning text from the model. + - `Optional id` - - `JsonValue; type "reasoning_text"constant` + The unique ID of the function tool call output. Populated when this item is returned via API. - The type of the reasoning text. Always `reasoning_text`. + - `Optional agent` - - `REASONING_TEXT("reasoning_text")` + The agent that produced this item. - - `class BetaResponseOutputRefusal:` + - `String agentName` - A refusal from the model. + The canonical name of the agent that produced this item. - - `class BetaResponseInputImage:` + - `Optional caller` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The execution context that produced this tool call. - - `class ComputerScreenshot:` + - `JsonValue;` - A screenshot of a computer. + - `JsonValue; type "direct"constant` - - `Detail detail` + The caller type. Always `direct`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `DIRECT("direct")` - - `LOW("low")` + - `class Program:` - - `HIGH("high")` + - `String callerId` - - `AUTO("auto")` + The call ID of the program item that produced this tool call. - - `ORIGINAL("original")` + - `JsonValue; type "program"constant` - - `Optional fileId` + The caller type. Always `program`. - The identifier of an uploaded file that contains the screenshot. + - `PROGRAM("program")` - - `Optional imageUrl` + - `Optional status` - The URL of the screenshot image. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `JsonValue; type "computer_screenshot"constant` + - `IN_PROGRESS("in_progress")` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `COMPLETED("completed")` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `INCOMPLETE("incomplete")` - - `Optional promptCacheBreakpoint` + - `AgentMessage` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String author` - - `JsonValue; mode "explicit"constant` + The sending agent identity. - The breakpoint mode. Always `explicit`. + - `List content` - - `EXPLICIT("explicit")` + Plaintext, image, or encrypted content sent between agents. - - `class BetaResponseInputFile:` + - `class BetaResponseInputTextContent:` - A file input to the model. + A text input to the model. + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `class EncryptedContent:` @@ -82524,10 +82327,14 @@ public final class Main { - `JsonValue; type "agent_message"constant` - The type of the item. Always `agent_message`. + The item type. Always `agent_message`. - `AGENT_MESSAGE("agent_message")` + - `Optional id` + + The unique ID of this agent message item. + - `Optional agent` The agent that produced this item. @@ -82538,13 +82345,9 @@ public final class Main { - `MultiAgentCall` - - `String id` - - The unique ID of the multi-agent call item. - - `Action action` - The multi-agent action to execute. + The multi-agent action that was executed. - `SPAWN_AGENT("spawn_agent")` @@ -82560,7 +82363,7 @@ public final class Main { - `String arguments` - The JSON string of arguments generated for the action. + The action arguments as a JSON string. - `String callId` @@ -82568,10 +82371,14 @@ public final class Main { - `JsonValue; type "multi_agent_call"constant` - The type of the multi-agent call. Always `multi_agent_call`. + The item type. Always `multi_agent_call`. - `MULTI_AGENT_CALL("multi_agent_call")` + - `Optional id` + + The unique ID of this multi-agent call. + - `Optional agent` The agent that produced this item. @@ -82582,10 +82389,6 @@ public final class Main { - `MultiAgentCallOutput` - - `String id` - - The unique ID of the multi-agent call output item. - - `Action action` The multi-agent action that produced this result. @@ -82606,75 +82409,105 @@ public final class Main { The unique ID of the multi-agent call. - - `List output` + - `List output` Text output returned by the multi-agent action. - - `List annotations` - - The annotations of the text output. - - `String text` - The text output from the model. + The text content. - `JsonValue; type "output_text"constant` - The type of the output text. Always `output_text`. + The content type. Always `output_text`. - - `Optional> logprobs` + - `OUTPUT_TEXT("output_text")` - - `JsonValue; type "multi_agent_call_output"constant` + - `Optional annotations` - The type of the multi-agent result. Always `multi_agent_call_output`. + Citations associated with the text content. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `List` - - `Optional agent` + - `String fileId` - The agent that produced this item. + The ID of the file. - - `String agentName` + - `String filename` - The canonical name of the agent that produced this item. + The filename of the file cited. - - `class BetaResponseToolSearchCall:` + - `long index` - - `String id` + The index of the file in the list of files. - The unique ID of the tool search call item. + - `JsonValue; type "file_citation"constant` - - `JsonValue arguments` + The citation type. Always `file_citation`. - Arguments used for the tool search call. + - `FILE_CITATION("file_citation")` - - `Optional callId` + - `List` - The unique ID of the tool search call generated by the model. + - `long endIndex` - - `Execution execution` + The index of the last character of the citation in the message. - Whether tool search was executed by the server or by the client. + - `long startIndex` - - `SERVER("server")` + The index of the first character of the citation in the message. - - `CLIENT("client")` + - `String title` - - `Status status` + The title of the cited resource. - The status of the tool search call item that was recorded. + - `JsonValue; type "url_citation"constant` - - `IN_PROGRESS("in_progress")` + The citation type. Always `url_citation`. - - `COMPLETED("completed")` + - `URL_CITATION("url_citation")` - - `INCOMPLETE("incomplete")` + - `String url` - - `JsonValue; type "tool_search_call"constant` + The URL of the cited resource. - The type of the item. Always `tool_search_call`. + - `List` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `String containerId` + + The ID of the container. + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `String fileId` + + The ID of the container file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The citation type. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `JsonValue; type "multi_agent_call_output"constant` + + The item type. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional id` + + The unique ID of this multi-agent call output. - `Optional agent` @@ -82684,21 +82517,35 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `ToolSearchCall` - The identifier of the actor that created the item. + - `JsonValue arguments` - - `class BetaResponseToolSearchOutputItem:` + The arguments supplied to the tool search call. - - `String id` + - `JsonValue; type "tool_search_call"constant` - The unique ID of the tool search output item. + The item type. Always `tool_search_call`. + + - `TOOL_SEARCH_CALL("tool_search_call")` + + - `Optional id` + + The unique ID of this tool search call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. - `Optional callId` The unique ID of the tool search call generated by the model. - - `Execution execution` + - `Optional execution` Whether tool search was executed by the server or by the client. @@ -82706,9 +82553,9 @@ public final class Main { - `CLIENT("client")` - - `Status status` + - `Optional status` - The status of the tool search output item that was recorded. + The status of the tool search call. - `IN_PROGRESS("in_progress")` @@ -82716,9 +82563,11 @@ public final class Main { - `INCOMPLETE("incomplete")` + - `class BetaResponseToolSearchOutputItemParam:` + - `List tools` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool:` @@ -82827,7 +82676,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -82884,7 +82737,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -83781,10 +83638,14 @@ public final class Main { - `JsonValue; type "tool_search_output"constant` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `Optional id` + + The unique ID of this tool search output. + - `Optional agent` The agent that produced this item. @@ -83793,39 +83654,39 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional callId` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `AdditionalTools` + - `Optional execution` - - `String id` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `SERVER("server")` - - `Role role` + - `CLIENT("client")` - The role that provided the additional tools. + - `Optional status` - - `UNKNOWN("unknown")` + The status of the tool search output. - - `USER("user")` + - `IN_PROGRESS("in_progress")` - - `ASSISTANT("assistant")` + - `COMPLETED("completed")` - - `SYSTEM("system")` + - `INCOMPLETE("incomplete")` - - `CRITIC("critic")` + - `AdditionalTools` - - `DISCRIMINATOR("discriminator")` + - `JsonValue; role "developer"constant` - - `DEVELOPER("developer")` + The role that provided the additional tools. Only `developer` is supported. - - `TOOL("tool")` + - `DEVELOPER("developer")` - `List tools` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `class BetaFunctionTool:` @@ -83884,10 +83745,14 @@ public final class Main { - `JsonValue; type "additional_tools"constant` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `ADDITIONAL_TOOLS("additional_tools")` + - `Optional id` + + The unique ID of this additional tools item. + - `Optional agent` The agent that produced this item. @@ -83965,85 +83830,13 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `Program` - - - `String id` - - The unique ID of the program item. - - - `String callId` - - The stable call ID of the program item. - - - `String code` - - The JavaScript source executed by programmatic tool calling. - - - `String fingerprint` - - Opaque program replay fingerprint that must be round-tripped. - - - `JsonValue; type "program"constant` - - The type of the item. Always `program`. - - - `PROGRAM("program")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `ProgramOutput` - - - `String id` - - The unique ID of the program output item. - - - `String callId` - - The call ID of the program item. - - - `String result` - - The result produced by the program item. - - - `Status status` - - The terminal status of the program output item. - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `JsonValue; type "program_output"constant` - - The type of the item. Always `program_output`. - - - `PROGRAM_OUTPUT("program_output")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCompactionItem:` + - `class BetaResponseCompactionItemParam:` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `String id` - - The unique ID of the compaction item. - - `String encryptedContent` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `JsonValue; type "compaction"constant` @@ -84051,6 +83844,10 @@ public final class Main { - `COMPACTION("compaction")` + - `Optional id` + + The ID of the compaction item. + - `Optional agent` The agent that produced this item. @@ -84059,10 +83856,6 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - `ImageGenerationCall` - `String id` @@ -84274,13 +84067,7 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `class BetaResponseFunctionShellToolCall:` - - A tool call that executes one or more shell commands in a managed environment. - - - `String id` - - The unique ID of the shell tool call. Populated when this item is returned via API. + - `ShellCall` - `Action action` @@ -84288,60 +84075,30 @@ public final class Main { - `List commands` + Ordered shell commands for the execution environment to run. + - `Optional maxOutputLength` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `Optional timeoutMs` - Optional timeout in milliseconds for the commands. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `String callId` The unique ID of the shell tool call generated by the model. - - `Optional environment` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment:` - - Represents the use of a local environment to perform shell actions. - - - `JsonValue; type "local"constant` - - The environment type. Always `local`. - - - `LOCAL("local")` - - - `class BetaResponseContainerReference:` - - Represents a container created with /v1/containers. - - - `String containerId` - - - `JsonValue; type "container_reference"constant` - - The environment type. Always `container_reference`. - - - `CONTAINER_REFERENCE("container_reference")` - - - `Status status` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - `JsonValue; type "shell_call"constant` The type of the item. Always `shell_call`. - `SHELL_CALL("shell_call")` + - `Optional id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -84358,6 +84115,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -84368,35 +84127,41 @@ public final class Main { - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - - `Optional createdBy` + - `Optional environment` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput:` + - `class BetaLocalEnvironment:` - The output of a shell tool call that was emitted. + - `class BetaContainerReference:` - - `String id` + - `Optional status` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `String callId` + - `IN_PROGRESS("in_progress")` - The unique ID of the shell tool call generated by the model. + - `COMPLETED("completed")` - - `Optional maxOutputLength` + - `INCOMPLETE("incomplete")` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `ShellCallOutput` - - `List output` + - `String callId` - An array of shell call output contents + The unique ID of the shell tool call generated by the model. + + - `List output` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `Outcome outcome` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The exit or timeout outcome associated with this shell call. - `JsonValue;` @@ -84412,7 +84177,7 @@ public final class Main { - `long exitCode` - Exit code from the shell process. + The exit code returned by the shell process. - `JsonValue; type "exit"constant` @@ -84422,32 +84187,22 @@ public final class Main { - `String stderr` - The standard error output that was captured. + Captured stderr output for the shell call. - `String stdout` - The standard output that was captured. - - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `Status status` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` + Captured stdout output for the shell call. - `JsonValue; type "shell_call_output"constant` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -84464,6 +84219,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -84474,19 +84231,25 @@ public final class Main { - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - - `Optional createdBy` + - `Optional maxOutputLength` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall:` + - `Optional status` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `String id` + - `IN_PROGRESS("in_progress")` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `ApplyPatchCall` - `String callId` @@ -84494,55 +84257,55 @@ public final class Main { - `Operation operation` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `class CreateFile:` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `String diff` - Diff to apply. + Unified diff content to apply when creating the file. - `String path` - Path of the file to create. + Path of the file to create relative to the workspace root. - `JsonValue; type "create_file"constant` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `CREATE_FILE("create_file")` - `class DeleteFile:` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `String path` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `JsonValue; type "delete_file"constant` - Delete the specified file. + The operation type. Always `delete_file`. - `DELETE_FILE("delete_file")` - `class UpdateFile:` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `String diff` - Diff to apply. + Unified diff content to apply to the existing file. - `String path` - Path of the file to update. + Path of the file to update relative to the workspace root. - `JsonValue; type "update_file"constant` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `UPDATE_FILE("update_file")` @@ -84560,6 +84323,10 @@ public final class Main { - `APPLY_PATCH_CALL("apply_patch_call")` + - `Optional id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -84576,6 +84343,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -84586,19 +84355,11 @@ public final class Main { - `JsonValue; type "program"constant` - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput:` - - The output emitted by an apply patch tool call. + The caller type. Always `program`. - - `String id` + - `PROGRAM("program")` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `ApplyPatchCallOutput` - `String callId` @@ -84618,6 +84379,10 @@ public final class Main { - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `Optional id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -84634,6 +84399,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -84644,15 +84411,7917 @@ public final class Main { - `JsonValue; type "program"constant` - - `PROGRAM("program")` - - - `Optional createdBy` + The caller type. Always `program`. - The ID of the entity that created this tool call output. + - `PROGRAM("program")` - `Optional output` - Optional textual output returned by the apply patch tool. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools` + + - `String id` + + The unique ID of the list. + + - `String serverLabel` + + The label of the MCP server. + + - `List tools` + + The tools available on the server. + + - `JsonValue inputSchema` + + The JSON schema describing the tool's input. + + - `String name` + + The name of the tool. + + - `Optional annotations` + + Additional annotations about the tool. + + - `Optional description` + + The description of the tool. + + - `JsonValue; type "mcp_list_tools"constant` + + The type of the item. Always `mcp_list_tools`. + + - `MCP_LIST_TOOLS("mcp_list_tools")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional error` + + Error message if the server could not list tools. + + - `McpApprovalRequest` + + - `String id` + + The unique ID of the approval request. + + - `String arguments` + + A JSON string of arguments for the tool. + + - `String name` + + The name of the tool to run. + + - `String serverLabel` + + The label of the MCP server making the request. + + - `JsonValue; type "mcp_approval_request"constant` + + The type of the item. Always `mcp_approval_request`. + + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `McpApprovalResponse` + + - `String approvalRequestId` + + The ID of the approval request being answered. + + - `boolean approve` + + Whether the request was approved. + + - `JsonValue; type "mcp_approval_response"constant` + + The type of the item. Always `mcp_approval_response`. + + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + + - `Optional id` + + The unique ID of the approval response + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional reason` + + Optional reason for the decision. + + - `McpCall` + + - `String id` + + The unique ID of the tool call. + + - `String arguments` + + A JSON string of the arguments passed to the tool. + + - `String name` + + The name of the tool that was run. + + - `String serverLabel` + + The label of the MCP server running the tool. + + - `JsonValue; type "mcp_call"constant` + + The type of the item. Always `mcp_call`. + + - `MCP_CALL("mcp_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional approvalRequestId` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `Optional error` + + The error from the tool call, if any. + + - `Optional output` + + The output from the tool call. + + - `Optional status` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `CALLING("calling")` + + - `FAILED("failed")` + + - `class BetaResponseCustomToolCallOutput:` + + The output of a custom tool call from your code, being sent back to the model. + + - `String callId` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `Output output` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "custom_tool_call_output"constant` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + + - `Optional id` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `class BetaResponseCustomToolCall:` + + A call to a custom tool created by the model. + + - `String callId` + + An identifier used to map this custom tool call to a tool call output. + + - `String input` + + The input for the custom tool call generated by the model. + + - `String name` + + The name of the custom tool being called. + + - `JsonValue; type "custom_tool_call"constant` + + The type of the custom tool call. Always `custom_tool_call`. + + - `CUSTOM_TOOL_CALL("custom_tool_call")` + + - `Optional id` + + The unique ID of the custom tool call in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the custom tool being called. + + - `CompactionTrigger` + + - `JsonValue; type "compaction_trigger"constant` + + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ItemReference` + + - `String id` + + The ID of the item to reference. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional type` + + The type of item to reference. Always `item_reference`. + + - `ITEM_REFERENCE("item_reference")` + + - `Program` + + - `String id` + + The unique ID of this program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The item type. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of this program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The item type. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `String responseId` + + The ID of the response that rejected the input. + + - `long sequenceNumber` + + The sequence number for this event. + + - `JsonValue; type "response.inject.failed"constant` + + The event discriminator. Always `response.inject.failed`. + + - `RESPONSE_INJECT_FAILED("response.inject.failed")` + + - `Optional streamId` + + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. + +### Beta Response Input Audio + +- `class BetaResponseInputAudio:` + + An audio input to the model. + + - `InputAudio inputAudio` + + - `String data` + + Base64-encoded audio data. + + - `Format format` + + The format of the audio data. Currently supported formats are `mp3` and + `wav`. + + - `MP3("mp3")` + + - `WAV("wav")` + + - `JsonValue; type "input_audio"constant` + + The type of the input item. Always `input_audio`. + + - `INPUT_AUDIO("input_audio")` + +### Beta Response Input Content + +- `class BetaResponseInputContent: A class that can be one of several variants.union` + + A text input to the model. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `Detail detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + +### Beta Response Input File + +- `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + +### Beta Response Input File Content + +- `class BetaResponseInputFileContent:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The base64-encoded data of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + +### Beta Response Input Image + +- `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `Detail detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + +### Beta Response Input Image Content + +- `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + +### Beta Response Input Item + +- `class BetaResponseInputItem: A class that can be one of several variants.union` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `class BetaEasyInputMessage:` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `Content content` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `Detail detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `Role role` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `USER("user")` + + - `ASSISTANT("assistant")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `Optional phase` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `COMMENTARY("commentary")` + + - `FINAL_ANSWER("final_answer")` + + - `Optional type` + + The type of the message input. Always `message`. + + - `MESSAGE("message")` + + - `Message` + + - `List content` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Role role` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `USER("user")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `Optional type` + + The type of the message input. Always set to `message`. + + - `MESSAGE("message")` + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `String id` + + The unique ID of the output message. + + - `List content` + + The content of the output message. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `List annotations` + + The annotations of the text output. + + - `class FileCitation:` + + A citation to a file. + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the file cited. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_citation"constant` + + The type of the file citation. Always `file_citation`. + + - `FILE_CITATION("file_citation")` + + - `class UrlCitation:` + + A citation for a web resource used to generate a model response. + + - `long endIndex` + + The index of the last character of the URL citation in the message. + + - `long startIndex` + + The index of the first character of the URL citation in the message. + + - `String title` + + The title of the web resource. + + - `JsonValue; type "url_citation"constant` + + The type of the URL citation. Always `url_citation`. + + - `URL_CITATION("url_citation")` + + - `String url` + + The URL of the web resource. + + - `class ContainerFileCitation:` + + A citation for a container file used to generate a model response. + + - `String containerId` + + The ID of the container file. + + - `long endIndex` + + The index of the last character of the container file citation in the message. + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the container file citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The type of the container file citation. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `class FilePath:` + + A path to a file. + + - `String fileId` + + The ID of the file. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_path"constant` + + The type of the file path. Always `file_path`. + + - `FILE_PATH("file_path")` + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional> logprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `List topLogprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `class BetaResponseOutputRefusal:` + + A refusal from the model. + + - `String refusal` + + The refusal explanation from the model. + + - `JsonValue; type "refusal"constant` + + The type of the refusal. Always `refusal`. + + - `REFUSAL("refusal")` + + - `JsonValue; role "assistant"constant` + + The role of the output message. Always `assistant`. + + - `ASSISTANT("assistant")` + + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "message"constant` + + The type of the output message. Always `message`. + + - `MESSAGE("message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional phase` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `COMMENTARY("commentary")` + + - `FINAL_ANSWER("final_answer")` + + - `class BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `String id` + + The unique ID of the file search tool call. + + - `List queries` + + The queries used to search for files. + + - `Status status` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `IN_PROGRESS("in_progress")` + + - `SEARCHING("searching")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FAILED("failed")` + + - `JsonValue; type "file_search_call"constant` + + The type of the file search tool call. Always `file_search_call`. + + - `FILE_SEARCH_CALL("file_search_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> results` + + The results of the file search tool call. + + - `Optional attributes` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `String` + + - `double` + + - `boolean` + + - `Optional fileId` + + The unique ID of the file. + + - `Optional filename` + + The name of the file. + + - `Optional score` + + The relevance score of the file - a value between 0 and 1. + + - `Optional text` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `String id` + + The unique ID of the computer call. + + - `String callId` + + An identifier used when responding to the tool call with output. + + - `List pendingSafetyChecks` + + The pending safety checks for the computer call. + + - `String id` + + The ID of the pending safety check. + + - `Optional code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Status status` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `Type type` + + The type of the computer call. Always `computer_call`. + + - `COMPUTER_CALL("computer_call")` + + - `Optional action` + + A click action. + + - `Click` + + - `Button button` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `LEFT("left")` + + - `RIGHT("right")` + + - `WHEEL("wheel")` + + - `BACK("back")` + + - `FORWARD("forward")` + + - `JsonValue; type "click"constant` + + Specifies the event type. For a click action, this property is always `click`. + + - `CLICK("click")` + + - `long x` + + The x-coordinate where the click occurred. + + - `long y` + + The y-coordinate where the click occurred. + + - `Optional> keys` + + The keys being held while clicking. + + - `DoubleClick` + + - `Optional> keys` + + The keys being held while double-clicking. + + - `JsonValue; type "double_click"constant` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `DOUBLE_CLICK("double_click")` + + - `long x` + + The x-coordinate where the double click occurred. + + - `long y` + + The y-coordinate where the double click occurred. + + - `Drag` + + - `List path` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `long x` + + The x-coordinate. + + - `long y` + + The y-coordinate. + + - `JsonValue; type "drag"constant` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `DRAG("drag")` + + - `Optional> keys` + + The keys being held while dragging the mouse. + + - `Keypress` + + - `List keys` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `JsonValue; type "keypress"constant` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `KEYPRESS("keypress")` + + - `Move` + + - `JsonValue; type "move"constant` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `MOVE("move")` + + - `long x` + + The x-coordinate to move to. + + - `long y` + + The y-coordinate to move to. + + - `Optional> keys` + + The keys being held while moving the mouse. + + - `JsonValue;` + + - `JsonValue; type "screenshot"constant` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `SCREENSHOT("screenshot")` + + - `Scroll` + + - `long scrollX` + + The horizontal scroll distance. + + - `long scrollY` + + The vertical scroll distance. + + - `JsonValue; type "scroll"constant` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `SCROLL("scroll")` + + - `long x` + + The x-coordinate where the scroll occurred. + + - `long y` + + The y-coordinate where the scroll occurred. + + - `Optional> keys` + + The keys being held while scrolling. + + - `Type` + + - `String text` + + The text to type. + + - `JsonValue; type "type"constant` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `TYPE("type")` + + - `JsonValue;` + + - `JsonValue; type "wait"constant` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `WAIT("wait")` + + - `Optional> actions` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click` + + - `DoubleClick` + + - `Drag` + + - `Keypress` + + - `Move` + + - `JsonValue;` + + - `Scroll` + + - `Type` + + - `JsonValue;` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ComputerCallOutput` + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot output` + + A computer screenshot image used with the computer use tool. + + - `JsonValue; type "computer_screenshot"constant` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `COMPUTER_SCREENSHOT("computer_screenshot")` + + - `Optional fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional imageUrl` + + The URL of the screenshot image. + + - `JsonValue; type "computer_call_output"constant` + + The type of the computer tool call output. Always `computer_call_output`. + + - `COMPUTER_CALL_OUTPUT("computer_call_output")` + + - `Optional id` + + The ID of the computer tool call output. + + - `Optional> acknowledgedSafetyChecks` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `String id` + + The ID of the pending safety check. + + - `Optional code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `String id` + + The unique ID of the web search tool call. + + - `Action action` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `class Search:` + + Action type "search" - Performs a web search query. + + - `JsonValue; type "search"constant` + + The action type. + + - `SEARCH("search")` + + - `Optional> queries` + + The search queries. + + - `Optional query` + + The search query. + + - `Optional> sources` + + The sources used in the search. + + - `JsonValue; type "url"constant` + + The type of source. Always `url`. + + - `URL("url")` + + - `String url` + + The URL of the source. + + - `class OpenPage:` + + Action type "open_page" - Opens a specific URL from search results. + + - `JsonValue; type "open_page"constant` + + The action type. + + - `OPEN_PAGE("open_page")` + + - `Optional url` + + The URL opened by the model. + + - `class FindInPage:` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `String pattern` + + The pattern or text to search for within the page. + + - `JsonValue; type "find_in_page"constant` + + The action type. + + - `FIND_IN_PAGE("find_in_page")` + + - `String url` + + The URL of the page searched for the pattern. + + - `Status status` + + The status of the web search tool call. + + - `IN_PROGRESS("in_progress")` + + - `SEARCHING("searching")` + + - `COMPLETED("completed")` + + - `FAILED("failed")` + + - `JsonValue; type "web_search_call"constant` + + The type of the web search tool call. Always `web_search_call`. + + - `WEB_SEARCH_CALL("web_search_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `String arguments` + + A JSON string of the arguments to pass to the function. + + - `String callId` + + The unique ID of the function tool call generated by the model. + + - `String name` + + The name of the function to run. + + - `JsonValue; type "function_call"constant` + + The type of the function tool call. Always `function_call`. + + - `FUNCTION_CALL("function_call")` + + - `Optional id` + + The unique ID of the function tool call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the function to run. + + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FunctionCallOutput` + + - `String callId` + + The unique ID of the function tool call generated by the model. + + - `Output output` + + Text, image, or file output of the function tool call. + + - `String` + + - `List` + + - `class BetaResponseInputTextContent:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFileContent:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The base64-encoded data of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `JsonValue; type "function_call_output"constant` + + The type of the function tool call output. Always `function_call_output`. + + - `FUNCTION_CALL_OUTPUT("function_call_output")` + + - `Optional id` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `AgentMessage` + + - `String author` + + The sending agent identity. + + - `List content` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent:` + + A text input to the model. + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The item type. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional id` + + The unique ID of this agent message item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` + + - `Action action` + + The multi-agent action that was executed. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The action arguments as a JSON string. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The item type. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional id` + + The unique ID of this multi-agent call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `String text` + + The text content. + + - `JsonValue; type "output_text"constant` + + The content type. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional annotations` + + Citations associated with the text content. + + - `List` + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the file cited. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_citation"constant` + + The citation type. Always `file_citation`. + + - `FILE_CITATION("file_citation")` + + - `List` + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `String title` + + The title of the cited resource. + + - `JsonValue; type "url_citation"constant` + + The citation type. Always `url_citation`. + + - `URL_CITATION("url_citation")` + + - `String url` + + The URL of the cited resource. + + - `List` + + - `String containerId` + + The ID of the container. + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `String fileId` + + The ID of the container file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The citation type. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `JsonValue; type "multi_agent_call_output"constant` + + The item type. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional id` + + The unique ID of this multi-agent call output. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ToolSearchCall` + + - `JsonValue arguments` + + The arguments supplied to the tool search call. + + - `JsonValue; type "tool_search_call"constant` + + The item type. Always `tool_search_call`. + + - `TOOL_SEARCH_CALL("tool_search_call")` + + - `Optional id` + + The unique ID of this tool search call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Optional execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search call. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseToolSearchOutputItemParam:` + + - `List tools` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `String name` + + The name of the function to call. + + - `Optional parameters` + + A JSON schema object describing the parameters of the function. + + - `Optional strict` + + Whether strict parameter validation is enforced for this function tool. + + - `JsonValue; type "function"constant` + + The type of the function tool. Always `function`. + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function is deferred and loaded via tool search. + + - `Optional description` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `Optional outputSchema` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `JsonValue; type "file_search"constant` + + The type of the file search tool. Always `file_search`. + + - `FILE_SEARCH("file_search")` + + - `List vectorStoreIds` + + The IDs of the vector stores to search. + + - `Optional filters` + + A filter to apply. + + - `class ComparisonFilter:` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `String key` + + The key to compare against the value. + + - `Type type` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `EQ("eq")` + + - `NE("ne")` + + - `GT("gt")` + + - `GTE("gte")` + + - `LT("lt")` + + - `LTE("lte")` + + - `IN("in")` + + - `NIN("nin")` + + - `Value value` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String` + + - `double` + + - `boolean` + + - `List` + + - `String` + + - `double` + + - `class CompoundFilter:` + + Combine multiple filters using `and` or `or`. + + - `List filters` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `class ComparisonFilter:` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `String key` + + The key to compare against the value. + + - `Type type` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `EQ("eq")` + + - `NE("ne")` + + - `GT("gt")` + + - `GTE("gte")` + + - `LT("lt")` + + - `LTE("lte")` + + - `IN("in")` + + - `NIN("nin")` + + - `Value value` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String` + + - `double` + + - `boolean` + + - `List` + + - `String` + + - `double` + + - `JsonValue` + + - `Type type` + + Type of operation: `and` or `or`. + + - `AND("and")` + + - `OR("or")` + + - `Optional maxNumResults` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `Optional rankingOptions` + + Ranking options for search. + + - `Optional hybridSearch` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `double embeddingWeight` + + The weight of the embedding in the reciprocal ranking fusion. + + - `double textWeight` + + The weight of the text in the reciprocal ranking fusion. + + - `Optional ranker` + + The ranker to use for the file search. + + - `AUTO("auto")` + + - `DEFAULT_2024_11_15("default-2024-11-15")` + + - `Optional scoreThreshold` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `JsonValue; type "computer"constant` + + The type of the computer tool. Always `computer`. + + - `COMPUTER("computer")` + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `long displayHeight` + + The height of the computer display. + + - `long displayWidth` + + The width of the computer display. + + - `Environment environment` + + The type of computer environment to control. + + - `WINDOWS("windows")` + + - `MAC("mac")` + + - `LINUX("linux")` + + - `UBUNTU("ubuntu")` + + - `BROWSER("browser")` + + - `JsonValue; type "computer_use_preview"constant` + + The type of the computer use tool. Always `computer_use_preview`. + + - `COMPUTER_USE_PREVIEW("computer_use_preview")` + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type type` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `WEB_SEARCH("web_search")` + + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + + - `Optional filters` + + Filters for the search. + + - `Optional> allowedDomains` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `Optional searchContextSize` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `Optional userLocation` + + The approximate location of the user. + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `Optional type` + + The type of location approximation. Always `approximate`. + + - `APPROXIMATE("approximate")` + + - `Mcp` + + - `String serverLabel` + + A label for this MCP server, used to identify it in tool calls. + + - `JsonValue; type "mcp"constant` + + The type of the MCP tool. Always `mcp`. + + - `MCP("mcp")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional allowedTools` + + List of allowed tool names or a filter object. + + - `List` + + - `class McpToolFilter:` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional authorization` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `Optional connectorId` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `CONNECTOR_DROPBOX("connector_dropbox")` + + - `CONNECTOR_GMAIL("connector_gmail")` + + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + + - `Optional deferLoading` + + Whether this MCP tool is deferred and discovered via tool search. + + - `Optional headers` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `Optional requireApproval` + + Specify which of the MCP server's tools require approval. + + - `class McpToolApprovalFilter:` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `Optional always` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional never` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `enum McpToolApprovalSetting:` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `ALWAYS("always")` + + - `NEVER("never")` + + - `Optional serverDescription` + + Optional description of the MCP server, used to provide more context. + + - `Optional serverUrl` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `Optional tunnelId` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `CodeInterpreter` + + - `Container container` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `String` + + - `class CodeInterpreterToolAuto:` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `JsonValue; type "auto"constant` + + Always `auto`. + + - `AUTO("auto")` + + - `Optional> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the code interpreter container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `JsonValue; type "disabled"constant` + + Disable outbound network access. Always `disabled`. + + - `DISABLED("disabled")` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `List allowedDomains` + + A list of allowed domains when type is `allowlist`. + + - `JsonValue; type "allowlist"constant` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `ALLOWLIST("allowlist")` + + - `Optional> domainSecrets` + + Optional domain-scoped secrets for allowlisted domains. + + - `String domain` + + The domain associated with the secret. + + - `String name` + + The name of the secret to inject for the domain. + + - `String value` + + The secret value to inject for the domain. + + - `JsonValue; type "code_interpreter"constant` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `CODE_INTERPRETER("code_interpreter")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The type of the tool. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `ImageGeneration` + + - `JsonValue; type "image_generation"constant` + + The type of the image generation tool. Always `image_generation`. + + - `IMAGE_GENERATION("image_generation")` + + - `Optional action` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `GENERATE("generate")` + + - `EDIT("edit")` + + - `AUTO("auto")` + + - `Optional background` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `TRANSPARENT("transparent")` + + - `OPAQUE("opaque")` + + - `AUTO("auto")` + + - `Optional inputFidelity` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `HIGH("high")` + + - `LOW("low")` + + - `Optional inputImageMask` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `Optional fileId` + + File ID for the mask image. + + - `Optional imageUrl` + + Base64-encoded mask image. + + - `Optional model` + + The image generation model to use. Default: `gpt-image-1`. + + - `GPT_IMAGE_1("gpt-image-1")` + + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + + - `GPT_IMAGE_2("gpt-image-2")` + + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + + - `GPT_IMAGE_1_5("gpt-image-1.5")` + + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + + - `Optional moderation` + + Moderation level for the generated image. Default: `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `Optional outputCompression` + + Compression level for the output image. Default: 100. + + - `Optional outputFormat` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `PNG("png")` + + - `WEBP("webp")` + + - `JPEG("jpeg")` + + - `Optional partialImages` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `Optional quality` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `Optional size` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `_1024X1024("1024x1024")` + + - `_1024X1536("1024x1536")` + + - `_1536X1024("1536x1024")` + + - `AUTO("auto")` + + - `JsonValue;` + + - `JsonValue; type "local_shell"constant` + + The type of the local shell tool. Always `local_shell`. + + - `LOCAL_SHELL("local_shell")` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `JsonValue; type "shell"constant` + + The type of the shell tool. Always `shell`. + + - `SHELL("shell")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional environment` + + - `class BetaContainerAuto:` + + - `JsonValue; type "container_auto"constant` + + Automatically creates a container for this request + + - `CONTAINER_AUTO("container_auto")` + + - `Optional> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `Optional> skills` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference:` + + - `String skillId` + + The ID of the referenced skill. + + - `JsonValue; type "skill_reference"constant` + + References a skill created with the /v1/skills endpoint. + + - `SKILL_REFERENCE("skill_reference")` + + - `Optional version` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill:` + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `BetaInlineSkillSource source` + + Inline skill payload + + - `String data` + + Base64-encoded skill zip bundle. + + - `JsonValue; mediaType "application/zip"constant` + + The media type of the inline skill payload. Must be `application/zip`. + + - `APPLICATION_ZIP("application/zip")` + + - `JsonValue; type "base64"constant` + + The type of the inline skill source. Must be `base64`. + + - `BASE64("base64")` + + - `JsonValue; type "inline"constant` + + Defines an inline skill for this request. + + - `INLINE("inline")` + + - `class BetaLocalEnvironment:` + + - `JsonValue; type "local"constant` + + Use a local computer environment. + + - `LOCAL("local")` + + - `Optional> skills` + + An optional list of skills. + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `String path` + + The path to the directory containing the skill. + + - `class BetaContainerReference:` + + - `String containerId` + + The ID of the referenced container. + + - `JsonValue; type "container_reference"constant` + + References a container created with the /v1/containers endpoint + + - `CONTAINER_REFERENCE("container_reference")` + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `String name` + + The name of the custom tool, used to identify it in tool calls. + + - `JsonValue; type "custom"constant` + + The type of the custom tool. Always `custom`. + + - `CUSTOM("custom")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this tool should be deferred and discovered via tool search. + + - `Optional description` + + Optional description of the custom tool, used to provide more context. + + - `Optional format` + + The input format for the custom tool. Default is unconstrained text. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + Unconstrained text format. Always `text`. + + - `TEXT("text")` + + - `class Grammar:` + + A grammar defined by the user. + + - `String definition` + + The grammar definition. + + - `Syntax syntax` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `LARK("lark")` + + - `REGEX("regex")` + + - `JsonValue; type "grammar"constant` + + Grammar format. Always `grammar`. + + - `GRAMMAR("grammar")` + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `String description` + + A description of the namespace shown to the model. + + - `String name` + + The namespace name used in tool calls (for example, `crm`). + + - `List tools` + + The function/custom tools available inside this namespace. + + - `class Function:` + + - `String name` + + - `JsonValue; type "function"constant` + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function should be deferred and discovered via tool search. + + - `Optional description` + + - `Optional outputSchema` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `Optional parameters` + + - `Optional strict` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `JsonValue; type "namespace"constant` + + The type of the tool. Always `namespace`. + + - `NAMESPACE("namespace")` + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `JsonValue; type "tool_search"constant` + + The type of the tool. Always `tool_search`. + + - `TOOL_SEARCH("tool_search")` + + - `Optional description` + + Description shown to the model for a client-executed tool search tool. + + - `Optional execution` + + Whether tool search is executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional parameters` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type type` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `WEB_SEARCH_PREVIEW("web_search_preview")` + + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + + - `Optional> searchContentTypes` + + - `TEXT("text")` + + - `IMAGE("image")` + + - `Optional searchContextSize` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `Optional userLocation` + + The user's location. + + - `JsonValue; type "approximate"constant` + + The type of location approximation. Always `approximate`. + + - `APPROXIMATE("approximate")` + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "apply_patch"constant` + + The type of the tool. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue; type "tool_search_output"constant` + + The item type. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional id` + + The unique ID of this tool search output. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Optional execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search output. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `AdditionalTools` + + - `JsonValue; role "developer"constant` + + The role that provided the additional tools. Only `developer` is supported. + + - `DEVELOPER("developer")` + + - `List tools` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "additional_tools"constant` + + The item type. Always `additional_tools`. + + - `ADDITIONAL_TOOLS("additional_tools")` + + - `Optional id` + + The unique ID of this additional tools item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `String id` + + The unique identifier of the reasoning content. + + - `List summary` + + Reasoning summary content. + + - `String text` + + A summary of the reasoning output from the model so far. + + - `JsonValue; type "summary_text"constant` + + The type of the object. Always `summary_text`. + + - `SUMMARY_TEXT("summary_text")` + + - `JsonValue; type "reasoning"constant` + + The type of the object. Always `reasoning`. + + - `REASONING("reasoning")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> content` + + Reasoning text content. + + - `String text` + + The reasoning text from the model. + + - `JsonValue; type "reasoning_text"constant` + + The type of the reasoning text. Always `reasoning_text`. + + - `REASONING_TEXT("reasoning_text")` + + - `Optional encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseCompactionItemParam:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `String encryptedContent` + + The encrypted content of the compaction summary. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` + + - `Optional id` + + The ID of the compaction item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ImageGenerationCall` + + - `String id` + + The unique ID of the image generation call. + + - `Optional result` + + The generated image encoded in base64. + + - `Status status` + + The status of the image generation call. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `GENERATING("generating")` + + - `FAILED("failed")` + + - `JsonValue; type "image_generation_call"constant` + + The type of the image generation call. Always `image_generation_call`. + + - `IMAGE_GENERATION_CALL("image_generation_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall:` + + A tool call to run code. + + - `String id` + + The unique ID of the code interpreter tool call. + + - `Optional code` + + The code to run, or null if not available. + + - `String containerId` + + The ID of the container used to run the code. + + - `Optional> outputs` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class Logs:` + + The logs output from the code interpreter. + + - `String logs` + + The logs output from the code interpreter. + + - `JsonValue; type "logs"constant` + + The type of the output. Always `logs`. + + - `LOGS("logs")` + + - `class Image:` + + The image output from the code interpreter. + + - `JsonValue; type "image"constant` + + The type of the output. Always `image`. + + - `IMAGE("image")` + + - `String url` + + The URL of the image output from the code interpreter. + + - `Status status` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `INTERPRETING("interpreting")` + + - `FAILED("failed")` + + - `JsonValue; type "code_interpreter_call"constant` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `CODE_INTERPRETER_CALL("code_interpreter_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `LocalShellCall` + + - `String id` + + The unique ID of the local shell call. + + - `Action action` + + Execute a shell command on the server. + + - `List command` + + The command to run. + + - `Env env` + + Environment variables to set for the command. + + - `JsonValue; type "exec"constant` + + The type of the local shell action. Always `exec`. + + - `EXEC("exec")` + + - `Optional timeoutMs` + + Optional timeout in milliseconds for the command. + + - `Optional user` + + Optional user to run the command as. + + - `Optional workingDirectory` + + Optional working directory to run the command in. + + - `String callId` + + The unique ID of the local shell tool call generated by the model. + + - `Status status` + + The status of the local shell call. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "local_shell_call"constant` + + The type of the local shell call. Always `local_shell_call`. + + - `LOCAL_SHELL_CALL("local_shell_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `LocalShellCallOutput` + + - `String id` + + The unique ID of the local shell tool call generated by the model. + + - `String output` + + A JSON string of the output of the local shell tool call. + + - `JsonValue; type "local_shell_call_output"constant` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `ShellCall` + + - `Action action` + + The shell commands and limits that describe how to run the tool call. + + - `List commands` + + Ordered shell commands for the execution environment to run. + + - `Optional maxOutputLength` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `Optional timeoutMs` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `String callId` + + The unique ID of the shell tool call generated by the model. + + - `JsonValue; type "shell_call"constant` + + The type of the item. Always `shell_call`. + + - `SHELL_CALL("shell_call")` + + - `Optional id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional environment` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment:` + + - `class BetaContainerReference:` + + - `Optional status` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `ShellCallOutput` + + - `String callId` + + The unique ID of the shell tool call generated by the model. + + - `List output` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `Outcome outcome` + + The exit or timeout outcome associated with this shell call. + + - `JsonValue;` + + - `JsonValue; type "timeout"constant` + + The outcome type. Always `timeout`. + + - `TIMEOUT("timeout")` + + - `class Exit:` + + Indicates that the shell commands finished and returned an exit code. + + - `long exitCode` + + The exit code returned by the shell process. + + - `JsonValue; type "exit"constant` + + The outcome type. Always `exit`. + + - `EXIT("exit")` + + - `String stderr` + + Captured stderr output for the shell call. + + - `String stdout` + + Captured stdout output for the shell call. + + - `JsonValue; type "shell_call_output"constant` + + The type of the item. Always `shell_call_output`. + + - `SHELL_CALL_OUTPUT("shell_call_output")` + + - `Optional id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional maxOutputLength` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `Optional status` + + The status of the shell call output. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `ApplyPatchCall` + + - `String callId` + + The unique ID of the apply patch tool call generated by the model. + + - `Operation operation` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `class CreateFile:` + + Instruction for creating a new file via the apply_patch tool. + + - `String diff` + + Unified diff content to apply when creating the file. + + - `String path` + + Path of the file to create relative to the workspace root. + + - `JsonValue; type "create_file"constant` + + The operation type. Always `create_file`. + + - `CREATE_FILE("create_file")` + + - `class DeleteFile:` + + Instruction for deleting an existing file via the apply_patch tool. + + - `String path` + + Path of the file to delete relative to the workspace root. + + - `JsonValue; type "delete_file"constant` + + The operation type. Always `delete_file`. + + - `DELETE_FILE("delete_file")` + + - `class UpdateFile:` + + Instruction for updating an existing file via the apply_patch tool. + + - `String diff` + + Unified diff content to apply to the existing file. + + - `String path` + + Path of the file to update relative to the workspace root. + + - `JsonValue; type "update_file"constant` + + The operation type. Always `update_file`. + + - `UPDATE_FILE("update_file")` + + - `Status status` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `JsonValue; type "apply_patch_call"constant` + + The type of the item. Always `apply_patch_call`. + + - `APPLY_PATCH_CALL("apply_patch_call")` + + - `Optional id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `ApplyPatchCallOutput` + + - `String callId` + + The unique ID of the apply patch tool call generated by the model. + + - `Status status` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `COMPLETED("completed")` + + - `FAILED("failed")` + + - `JsonValue; type "apply_patch_call_output"constant` + + The type of the item. Always `apply_patch_call_output`. + + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + + - `Optional id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional output` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools` + + - `String id` + + The unique ID of the list. + + - `String serverLabel` + + The label of the MCP server. + + - `List tools` + + The tools available on the server. + + - `JsonValue inputSchema` + + The JSON schema describing the tool's input. + + - `String name` + + The name of the tool. + + - `Optional annotations` + + Additional annotations about the tool. + + - `Optional description` + + The description of the tool. + + - `JsonValue; type "mcp_list_tools"constant` + + The type of the item. Always `mcp_list_tools`. + + - `MCP_LIST_TOOLS("mcp_list_tools")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional error` + + Error message if the server could not list tools. + + - `McpApprovalRequest` + + - `String id` + + The unique ID of the approval request. + + - `String arguments` + + A JSON string of arguments for the tool. + + - `String name` + + The name of the tool to run. + + - `String serverLabel` + + The label of the MCP server making the request. + + - `JsonValue; type "mcp_approval_request"constant` + + The type of the item. Always `mcp_approval_request`. + + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `McpApprovalResponse` + + - `String approvalRequestId` + + The ID of the approval request being answered. + + - `boolean approve` + + Whether the request was approved. + + - `JsonValue; type "mcp_approval_response"constant` + + The type of the item. Always `mcp_approval_response`. + + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + + - `Optional id` + + The unique ID of the approval response + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional reason` + + Optional reason for the decision. + + - `McpCall` + + - `String id` + + The unique ID of the tool call. + + - `String arguments` + + A JSON string of the arguments passed to the tool. + + - `String name` + + The name of the tool that was run. + + - `String serverLabel` + + The label of the MCP server running the tool. + + - `JsonValue; type "mcp_call"constant` + + The type of the item. Always `mcp_call`. + + - `MCP_CALL("mcp_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional approvalRequestId` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `Optional error` + + The error from the tool call, if any. + + - `Optional output` + + The output from the tool call. + + - `Optional status` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `CALLING("calling")` + + - `FAILED("failed")` + + - `class BetaResponseCustomToolCallOutput:` + + The output of a custom tool call from your code, being sent back to the model. + + - `String callId` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `Output output` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "custom_tool_call_output"constant` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + + - `Optional id` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `class BetaResponseCustomToolCall:` + + A call to a custom tool created by the model. + + - `String callId` + + An identifier used to map this custom tool call to a tool call output. + + - `String input` + + The input for the custom tool call generated by the model. + + - `String name` + + The name of the custom tool being called. + + - `JsonValue; type "custom_tool_call"constant` + + The type of the custom tool call. Always `custom_tool_call`. + + - `CUSTOM_TOOL_CALL("custom_tool_call")` + + - `Optional id` + + The unique ID of the custom tool call in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the custom tool being called. + + - `CompactionTrigger` + + - `JsonValue; type "compaction_trigger"constant` + + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ItemReference` + + - `String id` + + The ID of the item to reference. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional type` + + The type of item to reference. Always `item_reference`. + + - `ITEM_REFERENCE("item_reference")` + + - `Program` + + - `String id` + + The unique ID of this program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The item type. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of this program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The item type. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + +### Beta Response Input Message Item + +- `class BetaResponseInputMessageItem:` + + - `String id` + + The unique ID of the message input. + + - `List content` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `Detail detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `Role role` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `USER("user")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `JsonValue; type "message"constant` + + The type of the message input. Always set to `message`. + + - `MESSAGE("message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + +### Beta Response Input Text + +- `class BetaResponseInputText:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + +### Beta Response Input Text Content + +- `class BetaResponseInputTextContent:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + +### Beta Response Item + +- `class BetaResponseItem: A class that can be one of several variants.union` + + Content item used to generate a response. + + - `class BetaResponseInputMessageItem:` + + - `String id` + + The unique ID of the message input. + + - `List content` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `Detail detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `Role role` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `USER("user")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `JsonValue; type "message"constant` + + The type of the message input. Always set to `message`. + + - `MESSAGE("message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `String id` + + The unique ID of the output message. + + - `List content` + + The content of the output message. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `List annotations` + + The annotations of the text output. + + - `class FileCitation:` + + A citation to a file. + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the file cited. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_citation"constant` + + The type of the file citation. Always `file_citation`. + + - `FILE_CITATION("file_citation")` + + - `class UrlCitation:` + + A citation for a web resource used to generate a model response. + + - `long endIndex` + + The index of the last character of the URL citation in the message. + + - `long startIndex` + + The index of the first character of the URL citation in the message. + + - `String title` + + The title of the web resource. + + - `JsonValue; type "url_citation"constant` + + The type of the URL citation. Always `url_citation`. + + - `URL_CITATION("url_citation")` + + - `String url` + + The URL of the web resource. + + - `class ContainerFileCitation:` + + A citation for a container file used to generate a model response. + + - `String containerId` + + The ID of the container file. + + - `long endIndex` + + The index of the last character of the container file citation in the message. + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the container file citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The type of the container file citation. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `class FilePath:` + + A path to a file. + + - `String fileId` + + The ID of the file. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_path"constant` + + The type of the file path. Always `file_path`. + + - `FILE_PATH("file_path")` + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional> logprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `List topLogprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `class BetaResponseOutputRefusal:` + + A refusal from the model. + + - `String refusal` + + The refusal explanation from the model. + + - `JsonValue; type "refusal"constant` + + The type of the refusal. Always `refusal`. + + - `REFUSAL("refusal")` + + - `JsonValue; role "assistant"constant` + + The role of the output message. Always `assistant`. + + - `ASSISTANT("assistant")` + + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "message"constant` + + The type of the output message. Always `message`. + + - `MESSAGE("message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional phase` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `COMMENTARY("commentary")` + + - `FINAL_ANSWER("final_answer")` + + - `class BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `String id` + + The unique ID of the file search tool call. + + - `List queries` + + The queries used to search for files. + + - `Status status` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `IN_PROGRESS("in_progress")` + + - `SEARCHING("searching")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FAILED("failed")` + + - `JsonValue; type "file_search_call"constant` + + The type of the file search tool call. Always `file_search_call`. + + - `FILE_SEARCH_CALL("file_search_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> results` + + The results of the file search tool call. + + - `Optional attributes` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `String` + + - `double` + + - `boolean` + + - `Optional fileId` + + The unique ID of the file. + + - `Optional filename` + + The name of the file. + + - `Optional score` + + The relevance score of the file - a value between 0 and 1. + + - `Optional text` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `String id` + + The unique ID of the computer call. + + - `String callId` + + An identifier used when responding to the tool call with output. + + - `List pendingSafetyChecks` + + The pending safety checks for the computer call. + + - `String id` + + The ID of the pending safety check. + + - `Optional code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Status status` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `Type type` + + The type of the computer call. Always `computer_call`. + + - `COMPUTER_CALL("computer_call")` + + - `Optional action` + + A click action. + + - `Click` + + - `Button button` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `LEFT("left")` + + - `RIGHT("right")` + + - `WHEEL("wheel")` + + - `BACK("back")` + + - `FORWARD("forward")` + + - `JsonValue; type "click"constant` + + Specifies the event type. For a click action, this property is always `click`. + + - `CLICK("click")` + + - `long x` + + The x-coordinate where the click occurred. + + - `long y` + + The y-coordinate where the click occurred. + + - `Optional> keys` + + The keys being held while clicking. + + - `DoubleClick` + + - `Optional> keys` + + The keys being held while double-clicking. + + - `JsonValue; type "double_click"constant` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `DOUBLE_CLICK("double_click")` + + - `long x` + + The x-coordinate where the double click occurred. + + - `long y` + + The y-coordinate where the double click occurred. + + - `Drag` + + - `List path` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `long x` + + The x-coordinate. + + - `long y` + + The y-coordinate. + + - `JsonValue; type "drag"constant` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `DRAG("drag")` + + - `Optional> keys` + + The keys being held while dragging the mouse. + + - `Keypress` + + - `List keys` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `JsonValue; type "keypress"constant` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `KEYPRESS("keypress")` + + - `Move` + + - `JsonValue; type "move"constant` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `MOVE("move")` + + - `long x` + + The x-coordinate to move to. + + - `long y` + + The y-coordinate to move to. + + - `Optional> keys` + + The keys being held while moving the mouse. + + - `JsonValue;` + + - `JsonValue; type "screenshot"constant` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `SCREENSHOT("screenshot")` + + - `Scroll` + + - `long scrollX` + + The horizontal scroll distance. + + - `long scrollY` + + The vertical scroll distance. + + - `JsonValue; type "scroll"constant` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `SCROLL("scroll")` + + - `long x` + + The x-coordinate where the scroll occurred. + + - `long y` + + The y-coordinate where the scroll occurred. + + - `Optional> keys` + + The keys being held while scrolling. + + - `Type` + + - `String text` + + The text to type. + + - `JsonValue; type "type"constant` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `TYPE("type")` + + - `JsonValue;` + + - `JsonValue; type "wait"constant` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `WAIT("wait")` + + - `Optional> actions` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click` + + - `DoubleClick` + + - `Drag` + + - `Keypress` + + - `Move` + + - `JsonValue;` + + - `Scroll` + + - `Type` + + - `JsonValue;` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseComputerToolCallOutputItem:` + + - `String id` + + The unique ID of the computer call tool output. + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot output` + + A computer screenshot image used with the computer use tool. + + - `JsonValue; type "computer_screenshot"constant` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `COMPUTER_SCREENSHOT("computer_screenshot")` + + - `Optional fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional imageUrl` + + The URL of the screenshot image. + + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FAILED("failed")` + + - `IN_PROGRESS("in_progress")` + + - `JsonValue; type "computer_call_output"constant` + + The type of the computer tool call output. Always `computer_call_output`. + + - `COMPUTER_CALL_OUTPUT("computer_call_output")` + + - `Optional> acknowledgedSafetyChecks` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `String id` + + The ID of the pending safety check. + + - `Optional code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `String id` + + The unique ID of the web search tool call. + + - `Action action` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `class Search:` + + Action type "search" - Performs a web search query. + + - `JsonValue; type "search"constant` + + The action type. + + - `SEARCH("search")` + + - `Optional> queries` + + The search queries. + + - `Optional query` + + The search query. + + - `Optional> sources` + + The sources used in the search. + + - `JsonValue; type "url"constant` + + The type of source. Always `url`. + + - `URL("url")` + + - `String url` + + The URL of the source. + + - `class OpenPage:` + + Action type "open_page" - Opens a specific URL from search results. + + - `JsonValue; type "open_page"constant` + + The action type. + + - `OPEN_PAGE("open_page")` + + - `Optional url` + + The URL opened by the model. + + - `class FindInPage:` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `String pattern` + + The pattern or text to search for within the page. + + - `JsonValue; type "find_in_page"constant` + + The action type. + + - `FIND_IN_PAGE("find_in_page")` + + - `String url` + + The URL of the page searched for the pattern. + + - `Status status` + + The status of the web search tool call. + + - `IN_PROGRESS("in_progress")` + + - `SEARCHING("searching")` + + - `COMPLETED("completed")` + + - `FAILED("failed")` + + - `JsonValue; type "web_search_call"constant` + + The type of the web search tool call. Always `web_search_call`. + + - `WEB_SEARCH_CALL("web_search_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCallItem:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `String id` + + The unique ID of the function tool call. + + - `Status status` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseFunctionToolCallOutputItem:` + + - `String id` + + The unique ID of the function call tool output. + + - `String callId` + + The unique ID of the function tool call generated by the model. + + - `Output output` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Status status` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "function_call_output"constant` + + The type of the function tool call output. Always `function_call_output`. + + - `FUNCTION_CALL_OUTPUT("function_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AgentMessage` + + - `String id` + + The unique ID of the agent message. + + - `String author` + + The sending agent identity. + + - `List content` + + Encrypted content sent between agents. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `class Text:` + + A text content. + + - `String text` + + - `JsonValue; type "text"constant` + + - `TEXT("text")` + + - `class SummaryText:` + + A summary text from the model. + + - `String text` + + A summary of the reasoning output from the model so far. + + - `JsonValue; type "summary_text"constant` + + The type of the object. Always `summary_text`. + + - `SUMMARY_TEXT("summary_text")` + + - `class ReasoningText:` + + Reasoning text from the model. + + - `String text` + + The reasoning text from the model. + + - `JsonValue; type "reasoning_text"constant` + + The type of the reasoning text. Always `reasoning_text`. + + - `REASONING_TEXT("reasoning_text")` + + - `class BetaResponseOutputRefusal:` + + A refusal from the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot:` + + A screenshot of a computer. + + - `Detail detail` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `Optional fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional imageUrl` + + The URL of the screenshot image. + + - `JsonValue; type "computer_screenshot"constant` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `COMPUTER_SCREENSHOT("computer_screenshot")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The type of the item. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` + + - `String id` + + The unique ID of the multi-agent call item. + + - `Action action` + + The multi-agent action to execute. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The JSON string of arguments generated for the action. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `String id` + + The unique ID of the multi-agent call output item. + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `List annotations` + + The annotations of the text output. + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `Optional> logprobs` + + - `JsonValue; type "multi_agent_call_output"constant` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall:` + + - `String id` + + The unique ID of the tool search call item. + + - `JsonValue arguments` + + Arguments used for the tool search call. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search call item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "tool_search_call"constant` + + The type of the item. Always `tool_search_call`. + + - `TOOL_SEARCH_CALL("tool_search_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem:` + + - `String id` + + The unique ID of the tool search output item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search output item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `List tools` + + The loaded tool definitions returned by tool search. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `String name` + + The name of the function to call. + + - `Optional parameters` + + A JSON schema object describing the parameters of the function. + + - `Optional strict` + + Whether strict parameter validation is enforced for this function tool. + + - `JsonValue; type "function"constant` + + The type of the function tool. Always `function`. + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function is deferred and loaded via tool search. + + - `Optional description` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `Optional outputSchema` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `JsonValue; type "file_search"constant` + + The type of the file search tool. Always `file_search`. + + - `FILE_SEARCH("file_search")` + + - `List vectorStoreIds` + + The IDs of the vector stores to search. + + - `Optional filters` + + A filter to apply. + + - `class ComparisonFilter:` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `String key` + + The key to compare against the value. + + - `Type type` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `EQ("eq")` + + - `NE("ne")` + + - `GT("gt")` + + - `GTE("gte")` + + - `LT("lt")` + + - `LTE("lte")` + + - `IN("in")` + + - `NIN("nin")` + + - `Value value` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String` + + - `double` + + - `boolean` + + - `List` + + - `String` + + - `double` + + - `class CompoundFilter:` + + Combine multiple filters using `and` or `or`. + + - `List filters` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `class ComparisonFilter:` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `String key` + + The key to compare against the value. + + - `Type type` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `EQ("eq")` + + - `NE("ne")` + + - `GT("gt")` + + - `GTE("gte")` + + - `LT("lt")` + + - `LTE("lte")` + + - `IN("in")` + + - `NIN("nin")` + + - `Value value` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String` + + - `double` + + - `boolean` + + - `List` + + - `String` + + - `double` + + - `JsonValue` + + - `Type type` + + Type of operation: `and` or `or`. + + - `AND("and")` + + - `OR("or")` + + - `Optional maxNumResults` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `Optional rankingOptions` + + Ranking options for search. + + - `Optional hybridSearch` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `double embeddingWeight` + + The weight of the embedding in the reciprocal ranking fusion. + + - `double textWeight` + + The weight of the text in the reciprocal ranking fusion. + + - `Optional ranker` + + The ranker to use for the file search. + + - `AUTO("auto")` + + - `DEFAULT_2024_11_15("default-2024-11-15")` + + - `Optional scoreThreshold` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `JsonValue; type "computer"constant` + + The type of the computer tool. Always `computer`. + + - `COMPUTER("computer")` + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `long displayHeight` + + The height of the computer display. + + - `long displayWidth` + + The width of the computer display. + + - `Environment environment` + + The type of computer environment to control. + + - `WINDOWS("windows")` + + - `MAC("mac")` + + - `LINUX("linux")` + + - `UBUNTU("ubuntu")` + + - `BROWSER("browser")` + + - `JsonValue; type "computer_use_preview"constant` + + The type of the computer use tool. Always `computer_use_preview`. + + - `COMPUTER_USE_PREVIEW("computer_use_preview")` + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type type` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `WEB_SEARCH("web_search")` + + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + + - `Optional filters` + + Filters for the search. + + - `Optional> allowedDomains` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `Optional searchContextSize` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `Optional userLocation` + + The approximate location of the user. + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `Optional type` + + The type of location approximation. Always `approximate`. + + - `APPROXIMATE("approximate")` + + - `Mcp` + + - `String serverLabel` + + A label for this MCP server, used to identify it in tool calls. + + - `JsonValue; type "mcp"constant` + + The type of the MCP tool. Always `mcp`. + + - `MCP("mcp")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional allowedTools` + + List of allowed tool names or a filter object. + + - `List` + + - `class McpToolFilter:` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional authorization` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `Optional connectorId` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `CONNECTOR_DROPBOX("connector_dropbox")` + + - `CONNECTOR_GMAIL("connector_gmail")` + + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + + - `Optional deferLoading` + + Whether this MCP tool is deferred and discovered via tool search. + + - `Optional headers` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `Optional requireApproval` + + Specify which of the MCP server's tools require approval. + + - `class McpToolApprovalFilter:` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `Optional always` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional never` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `enum McpToolApprovalSetting:` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `ALWAYS("always")` + + - `NEVER("never")` + + - `Optional serverDescription` + + Optional description of the MCP server, used to provide more context. + + - `Optional serverUrl` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `Optional tunnelId` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `CodeInterpreter` + + - `Container container` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `String` + + - `class CodeInterpreterToolAuto:` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `JsonValue; type "auto"constant` + + Always `auto`. + + - `AUTO("auto")` + + - `Optional> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the code interpreter container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `JsonValue; type "disabled"constant` + + Disable outbound network access. Always `disabled`. + + - `DISABLED("disabled")` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `List allowedDomains` + + A list of allowed domains when type is `allowlist`. + + - `JsonValue; type "allowlist"constant` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `ALLOWLIST("allowlist")` + + - `Optional> domainSecrets` + + Optional domain-scoped secrets for allowlisted domains. + + - `String domain` + + The domain associated with the secret. + + - `String name` + + The name of the secret to inject for the domain. + + - `String value` + + The secret value to inject for the domain. + + - `JsonValue; type "code_interpreter"constant` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `CODE_INTERPRETER("code_interpreter")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The type of the tool. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `ImageGeneration` + + - `JsonValue; type "image_generation"constant` + + The type of the image generation tool. Always `image_generation`. + + - `IMAGE_GENERATION("image_generation")` + + - `Optional action` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `GENERATE("generate")` + + - `EDIT("edit")` + + - `AUTO("auto")` + + - `Optional background` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `TRANSPARENT("transparent")` + + - `OPAQUE("opaque")` + + - `AUTO("auto")` + + - `Optional inputFidelity` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `HIGH("high")` + + - `LOW("low")` + + - `Optional inputImageMask` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `Optional fileId` + + File ID for the mask image. + + - `Optional imageUrl` + + Base64-encoded mask image. + + - `Optional model` + + The image generation model to use. Default: `gpt-image-1`. + + - `GPT_IMAGE_1("gpt-image-1")` + + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + + - `GPT_IMAGE_2("gpt-image-2")` + + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + + - `GPT_IMAGE_1_5("gpt-image-1.5")` + + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + + - `Optional moderation` + + Moderation level for the generated image. Default: `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `Optional outputCompression` + + Compression level for the output image. Default: 100. + + - `Optional outputFormat` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `PNG("png")` + + - `WEBP("webp")` + + - `JPEG("jpeg")` + + - `Optional partialImages` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `Optional quality` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `Optional size` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `_1024X1024("1024x1024")` + + - `_1024X1536("1024x1536")` + + - `_1536X1024("1536x1024")` + + - `AUTO("auto")` + + - `JsonValue;` + + - `JsonValue; type "local_shell"constant` + + The type of the local shell tool. Always `local_shell`. + + - `LOCAL_SHELL("local_shell")` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `JsonValue; type "shell"constant` + + The type of the shell tool. Always `shell`. + + - `SHELL("shell")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional environment` + + - `class BetaContainerAuto:` + + - `JsonValue; type "container_auto"constant` + + Automatically creates a container for this request + + - `CONTAINER_AUTO("container_auto")` + + - `Optional> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `Optional> skills` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference:` + + - `String skillId` + + The ID of the referenced skill. + + - `JsonValue; type "skill_reference"constant` + + References a skill created with the /v1/skills endpoint. + + - `SKILL_REFERENCE("skill_reference")` + + - `Optional version` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill:` + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `BetaInlineSkillSource source` + + Inline skill payload + + - `String data` + + Base64-encoded skill zip bundle. + + - `JsonValue; mediaType "application/zip"constant` + + The media type of the inline skill payload. Must be `application/zip`. + + - `APPLICATION_ZIP("application/zip")` + + - `JsonValue; type "base64"constant` + + The type of the inline skill source. Must be `base64`. + + - `BASE64("base64")` + + - `JsonValue; type "inline"constant` + + Defines an inline skill for this request. + + - `INLINE("inline")` + + - `class BetaLocalEnvironment:` + + - `JsonValue; type "local"constant` + + Use a local computer environment. + + - `LOCAL("local")` + + - `Optional> skills` + + An optional list of skills. + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `String path` + + The path to the directory containing the skill. + + - `class BetaContainerReference:` + + - `String containerId` + + The ID of the referenced container. + + - `JsonValue; type "container_reference"constant` + + References a container created with the /v1/containers endpoint + + - `CONTAINER_REFERENCE("container_reference")` + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `String name` + + The name of the custom tool, used to identify it in tool calls. + + - `JsonValue; type "custom"constant` + + The type of the custom tool. Always `custom`. + + - `CUSTOM("custom")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this tool should be deferred and discovered via tool search. + + - `Optional description` + + Optional description of the custom tool, used to provide more context. + + - `Optional format` + + The input format for the custom tool. Default is unconstrained text. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + Unconstrained text format. Always `text`. + + - `TEXT("text")` + + - `class Grammar:` + + A grammar defined by the user. + + - `String definition` + + The grammar definition. + + - `Syntax syntax` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `LARK("lark")` + + - `REGEX("regex")` + + - `JsonValue; type "grammar"constant` + + Grammar format. Always `grammar`. + + - `GRAMMAR("grammar")` + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `String description` + + A description of the namespace shown to the model. + + - `String name` + + The namespace name used in tool calls (for example, `crm`). + + - `List tools` + + The function/custom tools available inside this namespace. + + - `class Function:` + + - `String name` + + - `JsonValue; type "function"constant` + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function should be deferred and discovered via tool search. + + - `Optional description` + + - `Optional outputSchema` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `Optional parameters` + + - `Optional strict` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `JsonValue; type "namespace"constant` + + The type of the tool. Always `namespace`. + + - `NAMESPACE("namespace")` + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `JsonValue; type "tool_search"constant` + + The type of the tool. Always `tool_search`. + + - `TOOL_SEARCH("tool_search")` + + - `Optional description` + + Description shown to the model for a client-executed tool search tool. + + - `Optional execution` + + Whether tool search is executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional parameters` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type type` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `WEB_SEARCH_PREVIEW("web_search_preview")` + + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + + - `Optional> searchContentTypes` + + - `TEXT("text")` + + - `IMAGE("image")` + + - `Optional searchContextSize` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `Optional userLocation` + + The user's location. + + - `JsonValue; type "approximate"constant` + + The type of location approximation. Always `approximate`. + + - `APPROXIMATE("approximate")` + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "apply_patch"constant` + + The type of the tool. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue; type "tool_search_output"constant` + + The type of the item. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AdditionalTools` + + - `String id` + + The unique ID of the additional tools item. + + - `Role role` + + The role that provided the additional tools. + + - `UNKNOWN("unknown")` + + - `USER("user")` + + - `ASSISTANT("assistant")` + + - `SYSTEM("system")` + + - `CRITIC("critic")` + + - `DISCRIMINATOR("discriminator")` + + - `DEVELOPER("developer")` + + - `TOOL("tool")` + + - `List tools` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "additional_tools"constant` + + The type of the item. Always `additional_tools`. + + - `ADDITIONAL_TOOLS("additional_tools")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `String id` + + The unique identifier of the reasoning content. + + - `List summary` + + Reasoning summary content. + + - `String text` + + A summary of the reasoning output from the model so far. + + - `JsonValue; type "summary_text"constant` + + The type of the object. Always `summary_text`. + + - `SUMMARY_TEXT("summary_text")` + + - `JsonValue; type "reasoning"constant` + + The type of the object. Always `reasoning`. + + - `REASONING("reasoning")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> content` + + Reasoning text content. + + - `String text` + + The reasoning text from the model. + + - `JsonValue; type "reasoning_text"constant` + + The type of the reasoning text. Always `reasoning_text`. + + - `REASONING_TEXT("reasoning_text")` + + - `Optional encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `Program` + + - `String id` + + The unique ID of the program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The type of the item. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of the program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output item. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The type of the item. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `String id` + + The unique ID of the compaction item. + + - `String encryptedContent` + + The encrypted content that was produced by compaction. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `ImageGenerationCall` + + - `String id` + + The unique ID of the image generation call. + + - `Optional result` + + The generated image encoded in base64. + + - `Status status` + + The status of the image generation call. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `GENERATING("generating")` + + - `FAILED("failed")` + + - `JsonValue; type "image_generation_call"constant` + + The type of the image generation call. Always `image_generation_call`. + + - `IMAGE_GENERATION_CALL("image_generation_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall:` + + A tool call to run code. + + - `String id` + + The unique ID of the code interpreter tool call. + + - `Optional code` + + The code to run, or null if not available. + + - `String containerId` + + The ID of the container used to run the code. + + - `Optional> outputs` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class Logs:` + + The logs output from the code interpreter. + + - `String logs` + + The logs output from the code interpreter. + + - `JsonValue; type "logs"constant` + + The type of the output. Always `logs`. + + - `LOGS("logs")` + + - `class Image:` + + The image output from the code interpreter. + + - `JsonValue; type "image"constant` + + The type of the output. Always `image`. + + - `IMAGE("image")` + + - `String url` + + The URL of the image output from the code interpreter. + + - `Status status` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `INTERPRETING("interpreting")` + + - `FAILED("failed")` + + - `JsonValue; type "code_interpreter_call"constant` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `CODE_INTERPRETER_CALL("code_interpreter_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `LocalShellCall` + + - `String id` + + The unique ID of the local shell call. + + - `Action action` + + Execute a shell command on the server. + + - `List command` + + The command to run. + + - `Env env` + + Environment variables to set for the command. + + - `JsonValue; type "exec"constant` + + The type of the local shell action. Always `exec`. + + - `EXEC("exec")` + + - `Optional timeoutMs` + + Optional timeout in milliseconds for the command. + + - `Optional user` + + Optional user to run the command as. + + - `Optional workingDirectory` + + Optional working directory to run the command in. + + - `String callId` + + The unique ID of the local shell tool call generated by the model. + + - `Status status` + + The status of the local shell call. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "local_shell_call"constant` + + The type of the local shell call. Always `local_shell_call`. + + - `LOCAL_SHELL_CALL("local_shell_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `LocalShellCallOutput` + + - `String id` + + The unique ID of the local shell tool call generated by the model. + + - `String output` + + A JSON string of the output of the local shell tool call. + + - `JsonValue; type "local_shell_call_output"constant` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseFunctionShellToolCall:` + + A tool call that executes one or more shell commands in a managed environment. + + - `String id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `Action action` + + The shell commands and limits that describe how to run the tool call. + + - `List commands` + + - `Optional maxOutputLength` + + Optional maximum number of characters to return from each command. + + - `Optional timeoutMs` + + Optional timeout in milliseconds for the commands. + + - `String callId` + + The unique ID of the shell tool call generated by the model. + + - `Optional environment` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment:` + + Represents the use of a local environment to perform shell actions. + + - `JsonValue; type "local"constant` + + The environment type. Always `local`. + + - `LOCAL("local")` + + - `class BetaResponseContainerReference:` + + Represents a container created with /v1/containers. + + - `String containerId` + + - `JsonValue; type "container_reference"constant` + + The environment type. Always `container_reference`. + + - `CONTAINER_REFERENCE("container_reference")` + + - `Status status` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call"constant` + + The type of the item. Always `shell_call`. + + - `SHELL_CALL("shell_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput:` + + The output of a shell tool call that was emitted. + + - `String id` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `String callId` + + The unique ID of the shell tool call generated by the model. + + - `Optional maxOutputLength` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `List output` + + An array of shell call output contents + + - `Outcome outcome` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `JsonValue;` + + - `JsonValue; type "timeout"constant` + + The outcome type. Always `timeout`. + + - `TIMEOUT("timeout")` + + - `class Exit:` + + Indicates that the shell commands finished and returned an exit code. + + - `long exitCode` + + Exit code from the shell process. + + - `JsonValue; type "exit"constant` + + The outcome type. Always `exit`. + + - `EXIT("exit")` + + - `String stderr` + + The standard error output that was captured. + + - `String stdout` + + The standard output that was captured. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `Status status` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call_output"constant` + + The type of the shell call output. Always `shell_call_output`. + + - `SHELL_CALL_OUTPUT("shell_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseApplyPatchToolCall:` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `String id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `String callId` + + The unique ID of the apply patch tool call generated by the model. + + - `Operation operation` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `class CreateFile:` + + Instruction describing how to create a file via the apply_patch tool. + + - `String diff` + + Diff to apply. + + - `String path` + + Path of the file to create. + + - `JsonValue; type "create_file"constant` + + Create a new file with the provided diff. + + - `CREATE_FILE("create_file")` + + - `class DeleteFile:` + + Instruction describing how to delete a file via the apply_patch tool. + + - `String path` + + Path of the file to delete. + + - `JsonValue; type "delete_file"constant` + + Delete the specified file. + + - `DELETE_FILE("delete_file")` + + - `class UpdateFile:` + + Instruction describing how to update a file via the apply_patch tool. + + - `String diff` + + Diff to apply. + + - `String path` + + Path of the file to update. + + - `JsonValue; type "update_file"constant` + + Update an existing file with the provided diff. + + - `UPDATE_FILE("update_file")` + + - `Status status` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `JsonValue; type "apply_patch_call"constant` + + The type of the item. Always `apply_patch_call`. + + - `APPLY_PATCH_CALL("apply_patch_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput:` + + The output emitted by an apply patch tool call. + + - `String id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `String callId` + + The unique ID of the apply patch tool call generated by the model. + + - `Status status` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `COMPLETED("completed")` + + - `FAILED("failed")` + + - `JsonValue; type "apply_patch_call_output"constant` + + The type of the item. Always `apply_patch_call_output`. + + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call output. + + - `Optional output` + + Optional textual output returned by the apply patch tool. - `McpListTools` @@ -85368,6 +93037,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -86703,7 +94374,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -86760,7 +94435,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -88850,6 +96529,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -90185,7 +97866,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -90242,7 +97927,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -92354,6 +100043,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -93689,7 +101380,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -93746,7 +101441,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -95850,825 +103549,831 @@ public final class Main { - `COMMENTARY("commentary")` -### Beta Response Output Refusal - -- `class BetaResponseOutputRefusal:` - - A refusal from the model. - - - `String refusal` - - The refusal explanation from the model. - - - `JsonValue; type "refusal"constant` - - The type of the refusal. Always `refusal`. - - - `REFUSAL("refusal")` - -### Beta Response Output Text - -- `class BetaResponseOutputText:` - - A text output from the model. - - - `List annotations` - - The annotations of the text output. - - - `class FileCitation:` - - A citation to a file. - - - `String fileId` - - The ID of the file. - - - `String filename` - - The filename of the file cited. - - - `long index` - - The index of the file in the list of files. - - - `JsonValue; type "file_citation"constant` - - The type of the file citation. Always `file_citation`. - - - `FILE_CITATION("file_citation")` - - - `class UrlCitation:` - - A citation for a web resource used to generate a model response. - - - `long endIndex` - - The index of the last character of the URL citation in the message. - - - `long startIndex` - - The index of the first character of the URL citation in the message. - - - `String title` - - The title of the web resource. - - - `JsonValue; type "url_citation"constant` - - The type of the URL citation. Always `url_citation`. - - - `URL_CITATION("url_citation")` - - - `String url` - - The URL of the web resource. - - - `class ContainerFileCitation:` - - A citation for a container file used to generate a model response. - - - `String containerId` - - The ID of the container file. - - - `long endIndex` - - The index of the last character of the container file citation in the message. - - - `String fileId` - - The ID of the file. - - - `String filename` - - The filename of the container file cited. - - - `long startIndex` - - The index of the first character of the container file citation in the message. - - - `JsonValue; type "container_file_citation"constant` - - The type of the container file citation. Always `container_file_citation`. - - - `CONTAINER_FILE_CITATION("container_file_citation")` - - - `class FilePath:` - - A path to a file. - - - `String fileId` - - The ID of the file. - - - `long index` - - The index of the file in the list of files. - - - `JsonValue; type "file_path"constant` - - The type of the file path. Always `file_path`. - - - `FILE_PATH("file_path")` - - - `String text` - - The text output from the model. - - - `JsonValue; type "output_text"constant` - - The type of the output text. Always `output_text`. - - - `OUTPUT_TEXT("output_text")` - - - `Optional> logprobs` - - - `String token` - - - `List bytes` - - - `double logprob` - - - `List topLogprobs` - - - `String token` - - - `List bytes` - - - `double logprob` - -### Beta Response Output Text Annotation Added Event - -- `class BetaResponseOutputTextAnnotationAddedEvent:` - - Emitted when an annotation is added to output text content. - - - `JsonValue annotation` - - The annotation object being added. (See annotation schema for details.) - - - `long annotationIndex` - - The index of the annotation within the content part. - - - `long contentIndex` - - The index of the content part within the output item. - - - `String itemId` - - The unique identifier of the item to which the annotation is being added. - - - `long outputIndex` - - The index of the output item in the response's output array. - - - `long sequenceNumber` - - The sequence number of this event. - - - `JsonValue; type "response.output_text.annotation.added"constant` - - The type of the event. Always 'response.output_text.annotation.added'. - - - `RESPONSE_OUTPUT_TEXT_ANNOTATION_ADDED("response.output_text.annotation.added")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Prompt - -- `class BetaResponsePrompt:` - - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - - `String id` - - The unique identifier of the prompt template to use. - - - `Optional variables` - - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. - - - `String` - - - `class BetaResponseInputText:` - - A text input to the model. - - - `String text` - - The text input to the model. - - - `JsonValue; type "input_text"constant` - - The type of the input item. Always `input_text`. - - - `INPUT_TEXT("input_text")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `Detail detail` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `LOW("low")` - - - `HIGH("high")` - - - `AUTO("auto")` - - - `ORIGINAL("original")` - - - `JsonValue; type "input_image"constant` - - The type of the input item. Always `input_image`. - - - `INPUT_IMAGE("input_image")` - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional imageUrl` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `JsonValue; type "input_file"constant` - - The type of the input item. Always `input_file`. - - - `INPUT_FILE("input_file")` - - - `Optional detail` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `Optional version` - - Optional version of the prompt template. - -### Beta Response Queued Event - -- `class BetaResponseQueuedEvent:` - - Emitted when a response is queued and waiting to be processed. - - - `BetaResponse response` - - The full response object that is queued. - - - `String id` - - Unique identifier for this Response. - - - `double createdAt` - - Unix timestamp (in seconds) of when this Response was created. - - - `Optional error` - - An error object returned when the model fails to generate a Response. - - - `Code code` - - The error code for the response. - - - `SERVER_ERROR("server_error")` - - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - - `INVALID_PROMPT("invalid_prompt")` - - - `BIO_POLICY("bio_policy")` - - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - - - `INVALID_IMAGE("invalid_image")` - - - `INVALID_IMAGE_FORMAT("invalid_image_format")` - - - `INVALID_BASE64_IMAGE("invalid_base64_image")` - - - `INVALID_IMAGE_URL("invalid_image_url")` - - - `IMAGE_TOO_LARGE("image_too_large")` - - - `IMAGE_TOO_SMALL("image_too_small")` - - - `IMAGE_PARSE_ERROR("image_parse_error")` - - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - - - `INVALID_IMAGE_MODE("invalid_image_mode")` - - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - - - `EMPTY_IMAGE_FILE("empty_image_file")` - - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - - - `String message` - - A human-readable description of the error. - - - `Optional incompleteDetails` - - Details about why the response is incomplete. - - - `Optional reason` - - The reason why the response is incomplete. - - - `MAX_OUTPUT_TOKENS("max_output_tokens")` - - - `CONTENT_FILTER("content_filter")` - - - `Optional instructions` - - A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - - - `String` - - - `List` - - - `class BetaEasyInputMessage:` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `Content content` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `String` - - - `List` - - - `class BetaResponseInputText:` - - A text input to the model. - - - `String text` - - The text input to the model. - - - `JsonValue; type "input_text"constant` - - The type of the input item. Always `input_text`. - - - `INPUT_TEXT("input_text")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `Detail detail` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `LOW("low")` - - - `HIGH("high")` - - - `AUTO("auto")` - - - `ORIGINAL("original")` - - - `JsonValue; type "input_image"constant` - - The type of the input item. Always `input_image`. - - - `INPUT_IMAGE("input_image")` - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional imageUrl` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `JsonValue; type "input_file"constant` - - The type of the input item. Always `input_file`. - - - `INPUT_FILE("input_file")` - - - `Optional detail` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `Role role` - - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - - - `USER("user")` - - - `ASSISTANT("assistant")` - - - `SYSTEM("system")` - - - `DEVELOPER("developer")` - - - `Optional phase` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `COMMENTARY("commentary")` - - - `Optional type` - - The type of the message input. Always `message`. - - - `MESSAGE("message")` - - - `Message` - - - `List content` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText:` - - A text input to the model. - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `Role role` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `USER("user")` - - - `SYSTEM("system")` - - - `DEVELOPER("developer")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional status` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `Optional type` - - The type of the message input. Always set to `message`. - - - `MESSAGE("message")` - - - `class BetaResponseOutputMessage:` - - An output message from the model. - - - `String id` - - The unique ID of the output message. - - - `List content` - - The content of the output message. - - - `class BetaResponseOutputText:` - - A text output from the model. - - - `List annotations` - - The annotations of the text output. - - - `class FileCitation:` - - A citation to a file. - - - `String fileId` - - The ID of the file. - - - `String filename` - - The filename of the file cited. - - - `long index` - - The index of the file in the list of files. - - - `JsonValue; type "file_citation"constant` - - The type of the file citation. Always `file_citation`. - - - `FILE_CITATION("file_citation")` - - - `class UrlCitation:` - - A citation for a web resource used to generate a model response. - - - `long endIndex` - - The index of the last character of the URL citation in the message. - - - `long startIndex` - - The index of the first character of the URL citation in the message. - - - `String title` - - The title of the web resource. - - - `JsonValue; type "url_citation"constant` - - The type of the URL citation. Always `url_citation`. - - - `URL_CITATION("url_citation")` - - - `String url` - - The URL of the web resource. - - - `class ContainerFileCitation:` - - A citation for a container file used to generate a model response. - - - `String containerId` - - The ID of the container file. - - - `long endIndex` - - The index of the last character of the container file citation in the message. - - - `String fileId` - - The ID of the file. - - - `String filename` - - The filename of the container file cited. - - - `long startIndex` - - The index of the first character of the container file citation in the message. - - - `JsonValue; type "container_file_citation"constant` - - The type of the container file citation. Always `container_file_citation`. - - - `CONTAINER_FILE_CITATION("container_file_citation")` - - - `class FilePath:` - - A path to a file. - - - `String fileId` - - The ID of the file. - - - `long index` - - The index of the file in the list of files. - - - `JsonValue; type "file_path"constant` - - The type of the file path. Always `file_path`. - - - `FILE_PATH("file_path")` - - - `String text` - - The text output from the model. - - - `JsonValue; type "output_text"constant` - - The type of the output text. Always `output_text`. - - - `OUTPUT_TEXT("output_text")` - - - `Optional> logprobs` - - - `String token` - - - `List bytes` - - - `double logprob` - - - `List topLogprobs` - - - `String token` - - - `List bytes` - - - `double logprob` - - - `class BetaResponseOutputRefusal:` - - A refusal from the model. - - - `String refusal` - - The refusal explanation from the model. - - - `JsonValue; type "refusal"constant` - - The type of the refusal. Always `refusal`. - - - `REFUSAL("refusal")` - - - `JsonValue; role "assistant"constant` - - The role of the output message. Always `assistant`. - - - `ASSISTANT("assistant")` - - - `Status status` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `JsonValue; type "message"constant` - - The type of the output message. Always `message`. - - - `MESSAGE("message")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional phase` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + +### Beta Response Output Refusal + +- `class BetaResponseOutputRefusal:` + + A refusal from the model. + + - `String refusal` + + The refusal explanation from the model. + + - `JsonValue; type "refusal"constant` + + The type of the refusal. Always `refusal`. + + - `REFUSAL("refusal")` + +### Beta Response Output Text + +- `class BetaResponseOutputText:` + + A text output from the model. + + - `List annotations` + + The annotations of the text output. + + - `class FileCitation:` + + A citation to a file. + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the file cited. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_citation"constant` + + The type of the file citation. Always `file_citation`. + + - `FILE_CITATION("file_citation")` + + - `class UrlCitation:` + + A citation for a web resource used to generate a model response. + + - `long endIndex` + + The index of the last character of the URL citation in the message. + + - `long startIndex` + + The index of the first character of the URL citation in the message. + + - `String title` + + The title of the web resource. + + - `JsonValue; type "url_citation"constant` + + The type of the URL citation. Always `url_citation`. + + - `URL_CITATION("url_citation")` + + - `String url` + + The URL of the web resource. + + - `class ContainerFileCitation:` + + A citation for a container file used to generate a model response. + + - `String containerId` + + The ID of the container file. + + - `long endIndex` + + The index of the last character of the container file citation in the message. + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the container file citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The type of the container file citation. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `class FilePath:` + + A path to a file. + + - `String fileId` + + The ID of the file. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_path"constant` + + The type of the file path. Always `file_path`. + + - `FILE_PATH("file_path")` + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional> logprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `List topLogprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + +### Beta Response Output Text Annotation Added Event + +- `class BetaResponseOutputTextAnnotationAddedEvent:` + + Emitted when an annotation is added to output text content. + + - `JsonValue annotation` + + The annotation object being added. (See annotation schema for details.) + + - `long annotationIndex` + + The index of the annotation within the content part. + + - `long contentIndex` + + The index of the content part within the output item. + + - `String itemId` + + The unique identifier of the item to which the annotation is being added. + + - `long outputIndex` + + The index of the output item in the response's output array. + + - `long sequenceNumber` + + The sequence number of this event. + + - `JsonValue; type "response.output_text.annotation.added"constant` + + The type of the event. Always 'response.output_text.annotation.added'. + + - `RESPONSE_OUTPUT_TEXT_ANNOTATION_ADDED("response.output_text.annotation.added")` + + - `Optional agent` + + The agent that owns this multi-agent streaming event. + + - `String agentName` + + The canonical name of the agent that produced this item. + +### Beta Response Prompt + +- `class BetaResponsePrompt:` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `String id` + + The unique identifier of the prompt template to use. + + - `Optional variables` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `String` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `Detail detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `Optional version` + + Optional version of the prompt template. + +### Beta Response Queued Event + +- `class BetaResponseQueuedEvent:` + + Emitted when a response is queued and waiting to be processed. + + - `BetaResponse response` + + The full response object that is queued. + + - `String id` + + Unique identifier for this Response. + + - `double createdAt` + + Unix timestamp (in seconds) of when this Response was created. + + - `Optional error` + + An error object returned when the model fails to generate a Response. + + - `Code code` + + The error code for the response. + + - `SERVER_ERROR("server_error")` + + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + + - `INVALID_PROMPT("invalid_prompt")` + + - `BIO_POLICY("bio_policy")` + + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + + - `INVALID_IMAGE("invalid_image")` + + - `INVALID_IMAGE_FORMAT("invalid_image_format")` + + - `INVALID_BASE64_IMAGE("invalid_base64_image")` + + - `INVALID_IMAGE_URL("invalid_image_url")` + + - `IMAGE_TOO_LARGE("image_too_large")` + + - `IMAGE_TOO_SMALL("image_too_small")` + + - `IMAGE_PARSE_ERROR("image_parse_error")` + + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + + - `INVALID_IMAGE_MODE("invalid_image_mode")` + + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + + - `EMPTY_IMAGE_FILE("empty_image_file")` + + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + + - `String message` + + A human-readable description of the error. + + - `Optional incompleteDetails` + + Details about why the response is incomplete. + + - `Optional reason` + + The reason why the response is incomplete. + + - `MAX_OUTPUT_TOKENS("max_output_tokens")` + + - `CONTENT_FILTER("content_filter")` + + - `Optional instructions` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `String` + + - `List` + + - `class BetaEasyInputMessage:` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `Content content` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `String text` + + The text input to the model. + + - `JsonValue; type "input_text"constant` + + The type of the input item. Always `input_text`. + + - `INPUT_TEXT("input_text")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `Detail detail` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` + + - `Optional detail` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `Role role` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `USER("user")` + + - `ASSISTANT("assistant")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `Optional phase` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `COMMENTARY("commentary")` + + - `FINAL_ANSWER("final_answer")` + + - `Optional type` + + The type of the message input. Always `message`. + + - `MESSAGE("message")` + + - `Message` + + - `List content` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Role role` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `USER("user")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `Optional type` + + The type of the message input. Always set to `message`. + + - `MESSAGE("message")` + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `String id` + + The unique ID of the output message. + + - `List content` + + The content of the output message. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `List annotations` + + The annotations of the text output. + + - `class FileCitation:` + + A citation to a file. + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the file cited. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_citation"constant` + + The type of the file citation. Always `file_citation`. + + - `FILE_CITATION("file_citation")` + + - `class UrlCitation:` + + A citation for a web resource used to generate a model response. + + - `long endIndex` + + The index of the last character of the URL citation in the message. + + - `long startIndex` + + The index of the first character of the URL citation in the message. + + - `String title` + + The title of the web resource. + + - `JsonValue; type "url_citation"constant` + + The type of the URL citation. Always `url_citation`. + + - `URL_CITATION("url_citation")` + + - `String url` + + The URL of the web resource. + + - `class ContainerFileCitation:` + + A citation for a container file used to generate a model response. + + - `String containerId` + + The ID of the container file. + + - `long endIndex` + + The index of the last character of the container file citation in the message. + + - `String fileId` + + The ID of the file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the container file citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The type of the container file citation. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `class FilePath:` + + A path to a file. + + - `String fileId` + + The ID of the file. + + - `long index` + + The index of the file in the list of files. + + - `JsonValue; type "file_path"constant` + + The type of the file path. Always `file_path`. + + - `FILE_PATH("file_path")` + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional> logprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `List topLogprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `class BetaResponseOutputRefusal:` + + A refusal from the model. + + - `String refusal` + + The refusal explanation from the model. + + - `JsonValue; type "refusal"constant` + + The type of the refusal. Always `refusal`. + + - `REFUSAL("refusal")` + + - `JsonValue; role "assistant"constant` + + The role of the output message. Always `assistant`. + + - `ASSISTANT("assistant")` + + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "message"constant` + + The type of the output message. Always `message`. + + - `MESSAGE("message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional phase` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `COMMENTARY("commentary")` + + - `FINAL_ANSWER("final_answer")` - `class BetaResponseFileSearchToolCall:` @@ -97806,7 +105511,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -97863,7 +105572,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -103372,6 +111085,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -103627,6 +111342,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -104763,7 +112480,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -104820,7 +112541,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -111435,7 +119160,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -111492,7 +119221,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -112520,7 +120253,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -112577,7 +120314,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -113886,6 +121627,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -114141,6 +121884,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -115277,7 +123022,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -115334,7 +123083,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -118272,7 +126025,11 @@ public final class Main { A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `ResponseInject` + - `class BetaResponseInjectEvent:` + + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. - `List input` @@ -118889,6 +126646,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -119144,6 +126903,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -120280,7 +128041,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -120337,7 +128102,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -126543,7 +134312,10 @@ public final class Main { The canonical name of the agent that produced this item. - - `ResponseInjectCreated` + - `class BetaResponseInjectCreatedEvent:` + + Emitted when all injected input items were validated and committed to the + active response. - `String responseId` @@ -126564,7 +134336,11 @@ public final class Main { The multiplexed WebSocket stream that emitted the event. This field is present only when WebSocket multiplexing is enabled separately. - - `ResponseInjectFailed` + - `class BetaResponseInjectFailedEvent:` + + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - `Error error` @@ -126839,7 +134615,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -126896,7 +134676,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -128117,7 +135901,7 @@ public final class Main { **get** `/responses/{response_id}/input_items?beta=true` -List input items +Returns a list of input items for a given response. ### Parameters @@ -128527,6 +136311,8 @@ List input items - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -129581,7 +137367,11 @@ List input items - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -129638,7 +137428,11 @@ List input items - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -132040,6 +139834,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -133094,7 +140890,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -133151,7 +140951,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -135164,7 +142968,9 @@ public final class Main { **post** `/responses/input_tokens?beta=true` -Get input token counts +Returns input token counts of the request. + +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. ### Parameters @@ -135345,6 +143151,8 @@ Get input token counts - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -135600,6 +143408,8 @@ Get input token counts - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -136736,7 +144546,11 @@ Get input token counts - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -136793,7 +144607,11 @@ Get input token counts - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue`