java/resources/responses/methods/retrieve/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

1## Get a model response

2 

3`Response responses().retrieve(ResponseRetrieveParamsparams = ResponseRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

4 

5**get** `/responses/{response_id}`

6 

7Retrieves a model response with the given ID.

8 

9### Parameters

10 

11- `ResponseRetrieveParams params`

12 

13 - `Optional<String> responseId`

14 

15 - `Optional<List<ResponseIncludable>> include`

16 

17 Additional fields to include in the response. See the `include`

18 parameter for Response creation above for more information.

19 

20 - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")`

21 

22 - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")`

23 

24 - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")`

25 

26 - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")`

27 

28 - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")`

29 

30 - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")`

31 

32 - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")`

33 

34 - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")`

35 

36 - `Optional<Boolean> includeObfuscation`

37 

38 When true, stream obfuscation will be enabled. Stream obfuscation adds

39 random characters to an `obfuscation` field on streaming delta events

40 to normalize payload sizes as a mitigation to certain side-channel

41 attacks. These obfuscation fields are included by default, but add a

42 small amount of overhead to the data stream. You can set

43 `include_obfuscation` to false to optimize for bandwidth if you trust

44 the network links between your application and the OpenAI API.

45 

46 - `Optional<Long> startingAfter`

47 

48 The sequence number of the event after which to start streaming.

49 

50### Returns

51 

52- `class Response:`

53 

54 - `String id`

55 

56 Unique identifier for this Response.

57 

58 - `double createdAt`

59 

60 Unix timestamp (in seconds) of when this Response was created.

61 

62 - `Optional<ResponseError> error`

63 

64 An error object returned when the model fails to generate a Response.

65 

66 - `Code code`

67 

68 The error code for the response.

69 

70 - `SERVER_ERROR("server_error")`

71 

72 - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")`

73 

74 - `INVALID_PROMPT("invalid_prompt")`

75 

76 - `VECTOR_STORE_TIMEOUT("vector_store_timeout")`

77 

78 - `INVALID_IMAGE("invalid_image")`

79 

80 - `INVALID_IMAGE_FORMAT("invalid_image_format")`

81 

82 - `INVALID_BASE64_IMAGE("invalid_base64_image")`

83 

84 - `INVALID_IMAGE_URL("invalid_image_url")`

85 

86 - `IMAGE_TOO_LARGE("image_too_large")`

87 

88 - `IMAGE_TOO_SMALL("image_too_small")`

89 

90 - `IMAGE_PARSE_ERROR("image_parse_error")`

91 

92 - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")`

93 

94 - `INVALID_IMAGE_MODE("invalid_image_mode")`

95 

96 - `IMAGE_FILE_TOO_LARGE("image_file_too_large")`

97 

98 - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")`

99 

100 - `EMPTY_IMAGE_FILE("empty_image_file")`

101 

102 - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")`

103 

104 - `IMAGE_FILE_NOT_FOUND("image_file_not_found")`

105 

106 - `String message`

107 

108 A human-readable description of the error.

109 

110 - `Optional<IncompleteDetails> incompleteDetails`

111 

112 Details about why the response is incomplete.

113 

114 - `Optional<Reason> reason`

115 

116 The reason why the response is incomplete.

117 

118 - `MAX_OUTPUT_TOKENS("max_output_tokens")`

119 

120 - `CONTENT_FILTER("content_filter")`

121 

122 - `Optional<Instructions> instructions`

123 

124 A system (or developer) message inserted into the model's context.

125 

126 When using along with `previous_response_id`, the instructions from a previous

127 response will not be carried over to the next response. This makes it simple

128 to swap out system (or developer) messages in new responses.

129 

130 - `String`

131 

132 - `List<ResponseInputItem>`

133 

134 - `class EasyInputMessage:`

135 

136 A message input to the model with a role indicating instruction following

137 hierarchy. Instructions given with the `developer` or `system` role take

138 precedence over instructions given with the `user` role. Messages with the

139 `assistant` role are presumed to have been generated by the model in previous

140 interactions.

141 

142 - `Content content`

143 

144 Text, image, or audio input to the model, used to generate a response.

145 Can also contain previous assistant responses.

146 

147 - `String`

148 

149 - `List<ResponseInputContent>`

150 

151 - `class ResponseInputText:`

152 

153 A text input to the model.

154 

155 - `String text`

156 

157 The text input to the model.

158 

159 - `JsonValue; type "input_text"constant`

160 

161 The type of the input item. Always `input_text`.

162 

163 - `INPUT_TEXT("input_text")`

164 

165 - `class ResponseInputImage:`

166 

167 An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision).

168 

169 - `Detail detail`

170 

171 The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.

172 

173 - `LOW("low")`

174 

175 - `HIGH("high")`

176 

177 - `AUTO("auto")`

178 

179 - `ORIGINAL("original")`

180 

181 - `JsonValue; type "input_image"constant`

182 

183 The type of the input item. Always `input_image`.

184 

185 - `INPUT_IMAGE("input_image")`

186 

187 - `Optional<String> fileId`

188 

189 The ID of the file to be sent to the model.

190 

191 - `Optional<String> imageUrl`

192 

193 The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

194 

195 - `class ResponseInputFile:`

196 

197 A file input to the model.

198 

199 - `JsonValue; type "input_file"constant`

200 

201 The type of the input item. Always `input_file`.

202 

203 - `INPUT_FILE("input_file")`

204 

205 - `Optional<Detail> detail`

206 

207 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

208 

209 - `LOW("low")`

210 

211 - `HIGH("high")`

212 

213 - `Optional<String> fileData`

214 

215 The content of the file to be sent to the model.

216 

217 - `Optional<String> fileId`

218 

219 The ID of the file to be sent to the model.

220 

221 - `Optional<String> fileUrl`

222 

223 The URL of the file to be sent to the model.

224 

225 - `Optional<String> filename`

226 

227 The name of the file to be sent to the model.

228 

229 - `Role role`

230 

231 The role of the message input. One of `user`, `assistant`, `system`, or

232 `developer`.

233 

234 - `USER("user")`

235 

236 - `ASSISTANT("assistant")`

237 

238 - `SYSTEM("system")`

239 

240 - `DEVELOPER("developer")`

241 

242 - `Optional<Phase> phase`

243 

244 Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`).

245 For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend

246 phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

247 

248 - `COMMENTARY("commentary")`

249 

250 - `FINAL_ANSWER("final_answer")`

251 

252 - `Optional<Type> type`

253 

254 The type of the message input. Always `message`.

255 

256 - `MESSAGE("message")`

257 

258 - `Message`

259 

260 - `List<ResponseInputContent> content`

261 

262 A list of one or many input items to the model, containing different content

263 types.

264 

265 - `class ResponseInputText:`

266 

267 A text input to the model.

268 

269 - `class ResponseInputImage:`

270 

271 An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision).

272 

273 - `class ResponseInputFile:`

274 

275 A file input to the model.

276 

277 - `Role role`

278 

279 The role of the message input. One of `user`, `system`, or `developer`.

280 

281 - `USER("user")`

282 

283 - `SYSTEM("system")`

284 

285 - `DEVELOPER("developer")`

286 

287 - `Optional<Status> status`

288 

289 The status of item. One of `in_progress`, `completed`, or

290 `incomplete`. Populated when items are returned via API.

291 

292 - `IN_PROGRESS("in_progress")`

293 

294 - `COMPLETED("completed")`

295 

296 - `INCOMPLETE("incomplete")`

297 

298 - `Optional<Type> type`

299 

300 The type of the message input. Always set to `message`.

301 

302 - `MESSAGE("message")`

303 

304 - `class ResponseOutputMessage:`

305 

306 An output message from the model.

307 

308 - `String id`

309 

310 The unique ID of the output message.

311 

312 - `List<Content> content`

313 

314 The content of the output message.

315 

316 - `class ResponseOutputText:`

317 

318 A text output from the model.

319 

320 - `List<Annotation> annotations`

321 

322 The annotations of the text output.

323 

324 - `class FileCitation:`

325 

326 A citation to a file.

327 

328 - `String fileId`

329 

330 The ID of the file.

331 

332 - `String filename`

333 

334 The filename of the file cited.

335 

336 - `long index`

337 

338 The index of the file in the list of files.

339 

340 - `JsonValue; type "file_citation"constant`

341 

342 The type of the file citation. Always `file_citation`.

343 

344 - `FILE_CITATION("file_citation")`

345 

346 - `class UrlCitation:`

347 

348 A citation for a web resource used to generate a model response.

349 

350 - `long endIndex`

351 

352 The index of the last character of the URL citation in the message.

353 

354 - `long startIndex`

355 

356 The index of the first character of the URL citation in the message.

357 

358 - `String title`

359 

360 The title of the web resource.

361 

362 - `JsonValue; type "url_citation"constant`

363 

364 The type of the URL citation. Always `url_citation`.

365 

366 - `URL_CITATION("url_citation")`

367 

368 - `String url`

369 

370 The URL of the web resource.

371 

372 - `class ContainerFileCitation:`

373 

374 A citation for a container file used to generate a model response.

375 

376 - `String containerId`

377 

378 The ID of the container file.

379 

380 - `long endIndex`

381 

382 The index of the last character of the container file citation in the message.

383 

384 - `String fileId`

385 

386 The ID of the file.

387 

388 - `String filename`

389 

390 The filename of the container file cited.

391 

392 - `long startIndex`

393 

394 The index of the first character of the container file citation in the message.

395 

396 - `JsonValue; type "container_file_citation"constant`

397 

398 The type of the container file citation. Always `container_file_citation`.

399 

400 - `CONTAINER_FILE_CITATION("container_file_citation")`

401 

402 - `class FilePath:`

403 

404 A path to a file.

405 

406 - `String fileId`

407 

408 The ID of the file.

409 

410 - `long index`

411 

412 The index of the file in the list of files.

413 

414 - `JsonValue; type "file_path"constant`

415 

416 The type of the file path. Always `file_path`.

417 

418 - `FILE_PATH("file_path")`

419 

420 - `String text`

421 

422 The text output from the model.

423 

424 - `JsonValue; type "output_text"constant`

425 

426 The type of the output text. Always `output_text`.

427 

428 - `OUTPUT_TEXT("output_text")`

429 

430 - `Optional<List<Logprob>> logprobs`

431 

432 - `String token`

433 

434 - `List<long> bytes`

435 

436 - `double logprob`

437 

438 - `List<TopLogprob> topLogprobs`

439 

440 - `String token`

441 

442 - `List<long> bytes`

443 

444 - `double logprob`

445 

446 - `class ResponseOutputRefusal:`

447 

448 A refusal from the model.

449 

450 - `String refusal`

451 

452 The refusal explanation from the model.

453 

454 - `JsonValue; type "refusal"constant`

455 

456 The type of the refusal. Always `refusal`.

457 

458 - `REFUSAL("refusal")`

459 

460 - `JsonValue; role "assistant"constant`

461 

462 The role of the output message. Always `assistant`.

463 

464 - `ASSISTANT("assistant")`

465 

466 - `Status status`

467 

468 The status of the message input. One of `in_progress`, `completed`, or

469 `incomplete`. Populated when input items are returned via API.

470 

471 - `IN_PROGRESS("in_progress")`

472 

473 - `COMPLETED("completed")`

474 

475 - `INCOMPLETE("incomplete")`

476 

477 - `JsonValue; type "message"constant`

478 

479 The type of the output message. Always `message`.

480 

481 - `MESSAGE("message")`

482 

483 - `Optional<Phase> phase`

484 

485 Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`).

486 For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend

487 phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

488 

489 - `COMMENTARY("commentary")`

490 

491 - `FINAL_ANSWER("final_answer")`

492 

493 - `class ResponseFileSearchToolCall:`

494 

495 The results of a file search tool call. See the

496 [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information.

497 

498 - `String id`

499 

500 The unique ID of the file search tool call.

501 

502 - `List<String> queries`

503 

504 The queries used to search for files.

505 

506 - `Status status`

507 

508 The status of the file search tool call. One of `in_progress`,

509 `searching`, `incomplete` or `failed`,

510 

511 - `IN_PROGRESS("in_progress")`

512 

513 - `SEARCHING("searching")`

514 

515 - `COMPLETED("completed")`

516 

517 - `INCOMPLETE("incomplete")`

518 

519 - `FAILED("failed")`

520 

521 - `JsonValue; type "file_search_call"constant`

522 

523 The type of the file search tool call. Always `file_search_call`.

524 

525 - `FILE_SEARCH_CALL("file_search_call")`

526 

527 - `Optional<List<Result>> results`

528 

529 The results of the file search tool call.

530 

531 - `Optional<Attributes> attributes`

532 

533 Set of 16 key-value pairs that can be attached to an object. This can be

534 useful for storing additional information about the object in a structured

535 format, and querying for objects via API or the dashboard. Keys are strings

536 with a maximum length of 64 characters. Values are strings with a maximum

537 length of 512 characters, booleans, or numbers.

538 

539 - `String`

540 

541 - `double`

542 

543 - `boolean`

544 

545 - `Optional<String> fileId`

546 

547 The unique ID of the file.

548 

549 - `Optional<String> filename`

550 

551 The name of the file.

552 

553 - `Optional<Double> score`

554 

555 The relevance score of the file - a value between 0 and 1.

556 

557 - `Optional<String> text`

558 

559 The text that was retrieved from the file.

560 

561 - `class ResponseComputerToolCall:`

562 

563 A tool call to a computer use tool. See the

564 [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information.

565 

566 - `String id`

567 

568 The unique ID of the computer call.

569 

570 - `String callId`

571 

572 An identifier used when responding to the tool call with output.

573 

574 - `List<PendingSafetyCheck> pendingSafetyChecks`

575 

576 The pending safety checks for the computer call.

577 

578 - `String id`

579 

580 The ID of the pending safety check.

581 

582 - `Optional<String> code`

583 

584 The type of the pending safety check.

585 

586 - `Optional<String> message`

587 

588 Details about the pending safety check.

589 

590 - `Status status`

591 

592 The status of the item. One of `in_progress`, `completed`, or

593 `incomplete`. Populated when items are returned via API.

594 

595 - `IN_PROGRESS("in_progress")`

596 

597 - `COMPLETED("completed")`

598 

599 - `INCOMPLETE("incomplete")`

600 

601 - `Type type`

602 

603 The type of the computer call. Always `computer_call`.

604 

605 - `COMPUTER_CALL("computer_call")`

606 

607 - `Optional<Action> action`

608 

609 A click action.

610 

611 - `class Click:`

612 

613 A click action.

614 

615 - `Button button`

616 

617 Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.

618 

619 - `LEFT("left")`

620 

621 - `RIGHT("right")`

622 

623 - `WHEEL("wheel")`

624 

625 - `BACK("back")`

626 

627 - `FORWARD("forward")`

628 

629 - `JsonValue; type "click"constant`

630 

631 Specifies the event type. For a click action, this property is always `click`.

632 

633 - `CLICK("click")`

634 

635 - `long x`

636 

637 The x-coordinate where the click occurred.

638 

639 - `long y`

640 

641 The y-coordinate where the click occurred.

642 

643 - `Optional<List<String>> keys`

644 

645 The keys being held while clicking.

646 

647 - `class DoubleClick:`

648 

649 A double click action.

650 

651 - `Optional<List<String>> keys`

652 

653 The keys being held while double-clicking.

654 

655 - `JsonValue; type "double_click"constant`

656 

657 Specifies the event type. For a double click action, this property is always set to `double_click`.

658 

659 - `DOUBLE_CLICK("double_click")`

660 

661 - `long x`

662 

663 The x-coordinate where the double click occurred.

664 

665 - `long y`

666 

667 The y-coordinate where the double click occurred.

668 

669 - `class Drag:`

670 

671 A drag action.

672 

673 - `List<Path> path`

674 

675 An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg

676 

677 ```

678 [

679 { x: 100, y: 200 },

680 { x: 200, y: 300 }

681 ]

682 ```

683 

684 - `long x`

685 

686 The x-coordinate.

687 

688 - `long y`

689 

690 The y-coordinate.

691 

692 - `JsonValue; type "drag"constant`

693 

694 Specifies the event type. For a drag action, this property is always set to `drag`.

695 

696 - `DRAG("drag")`

697 

698 - `Optional<List<String>> keys`

699 

700 The keys being held while dragging the mouse.

701 

702 - `class Keypress:`

703 

704 A collection of keypresses the model would like to perform.

705 

706 - `List<String> keys`

707 

708 The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

709 

710 - `JsonValue; type "keypress"constant`

711 

712 Specifies the event type. For a keypress action, this property is always set to `keypress`.

713 

714 - `KEYPRESS("keypress")`

715 

716 - `class Move:`

717 

718 A mouse move action.

719 

720 - `JsonValue; type "move"constant`

721 

722 Specifies the event type. For a move action, this property is always set to `move`.

723 

724 - `MOVE("move")`

725 

726 - `long x`

727 

728 The x-coordinate to move to.

729 

730 - `long y`

731 

732 The y-coordinate to move to.

733 

734 - `Optional<List<String>> keys`

735 

736 The keys being held while moving the mouse.

737 

738 - `JsonValue;`

739 

740 - `JsonValue; type "screenshot"constant`

741 

742 Specifies the event type. For a screenshot action, this property is always set to `screenshot`.

743 

744 - `SCREENSHOT("screenshot")`

745 

746 - `class Scroll:`

747 

748 A scroll action.

749 

750 - `long scrollX`

751 

752 The horizontal scroll distance.

753 

754 - `long scrollY`

755 

756 The vertical scroll distance.

757 

758 - `JsonValue; type "scroll"constant`

759 

760 Specifies the event type. For a scroll action, this property is always set to `scroll`.

761 

762 - `SCROLL("scroll")`

763 

764 - `long x`

765 

766 The x-coordinate where the scroll occurred.

767 

768 - `long y`

769 

770 The y-coordinate where the scroll occurred.

771 

772 - `Optional<List<String>> keys`

773 

774 The keys being held while scrolling.

775 

776 - `class Type:`

777 

778 An action to type in text.

779 

780 - `String text`

781 

782 The text to type.

783 

784 - `JsonValue; type "type"constant`

785 

786 Specifies the event type. For a type action, this property is always set to `type`.

787 

788 - `TYPE("type")`

789 

790 - `JsonValue;`

791 

792 - `JsonValue; type "wait"constant`

793 

794 Specifies the event type. For a wait action, this property is always set to `wait`.

795 

796 - `WAIT("wait")`

797 

798 - `Optional<List<ComputerAction>> actions`

799 

800 Flattened batched actions for `computer_use`. Each action includes an

801 `type` discriminator and action-specific fields.

802 

803 - `Click`

804 

805 - `Button button`

806 

807 Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.

808 

809 - `LEFT("left")`

810 

811 - `RIGHT("right")`

812 

813 - `WHEEL("wheel")`

814 

815 - `BACK("back")`

816 

817 - `FORWARD("forward")`

818 

819 - `JsonValue; type "click"constant`

820 

821 Specifies the event type. For a click action, this property is always `click`.

822 

823 - `CLICK("click")`

824 

825 - `long x`

826 

827 The x-coordinate where the click occurred.

828 

829 - `long y`

830 

831 The y-coordinate where the click occurred.

832 

833 - `Optional<List<String>> keys`

834 

835 The keys being held while clicking.

836 

837 - `DoubleClick`

838 

839 - `Optional<List<String>> keys`

840 

841 The keys being held while double-clicking.

842 

843 - `JsonValue; type "double_click"constant`

844 

845 Specifies the event type. For a double click action, this property is always set to `double_click`.

846 

847 - `DOUBLE_CLICK("double_click")`

848 

849 - `long x`

850 

851 The x-coordinate where the double click occurred.

852 

853 - `long y`

854 

855 The y-coordinate where the double click occurred.

856 

857 - `Drag`

858 

859 - `List<Path> path`

860 

861 An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg

862 

863 ```

864 [

865 { x: 100, y: 200 },

866 { x: 200, y: 300 }

867 ]

868 ```

869 

870 - `long x`

871 

872 The x-coordinate.

873 

874 - `long y`

875 

876 The y-coordinate.

877 

878 - `JsonValue; type "drag"constant`

879 

880 Specifies the event type. For a drag action, this property is always set to `drag`.

881 

882 - `DRAG("drag")`

883 

884 - `Optional<List<String>> keys`

885 

886 The keys being held while dragging the mouse.

887 

888 - `Keypress`

889 

890 - `List<String> keys`

891 

892 The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

893 

894 - `JsonValue; type "keypress"constant`

895 

896 Specifies the event type. For a keypress action, this property is always set to `keypress`.

897 

898 - `KEYPRESS("keypress")`

899 

900 - `Move`

901 

902 - `JsonValue; type "move"constant`

903 

904 Specifies the event type. For a move action, this property is always set to `move`.

905 

906 - `MOVE("move")`

907 

908 - `long x`

909 

910 The x-coordinate to move to.

911 

912 - `long y`

913 

914 The y-coordinate to move to.

915 

916 - `Optional<List<String>> keys`

917 

918 The keys being held while moving the mouse.

919 

920 - `JsonValue;`

921 

922 - `JsonValue; type "screenshot"constant`

923 

924 Specifies the event type. For a screenshot action, this property is always set to `screenshot`.

925 

926 - `SCREENSHOT("screenshot")`

927 

928 - `Scroll`

929 

930 - `long scrollX`

931 

932 The horizontal scroll distance.

933 

934 - `long scrollY`

935 

936 The vertical scroll distance.

937 

938 - `JsonValue; type "scroll"constant`

939 

940 Specifies the event type. For a scroll action, this property is always set to `scroll`.

941 

942 - `SCROLL("scroll")`

943 

944 - `long x`

945 

946 The x-coordinate where the scroll occurred.

947 

948 - `long y`

949 

950 The y-coordinate where the scroll occurred.

951 

952 - `Optional<List<String>> keys`

953 

954 The keys being held while scrolling.

955 

956 - `Type`

957 

958 - `String text`

959 

960 The text to type.

961 

962 - `JsonValue; type "type"constant`

963 

964 Specifies the event type. For a type action, this property is always set to `type`.

965 

966 - `TYPE("type")`

967 

968 - `JsonValue;`

969 

970 - `JsonValue; type "wait"constant`

971 

972 Specifies the event type. For a wait action, this property is always set to `wait`.

973 

974 - `WAIT("wait")`

975 

976 - `ComputerCallOutput`

977 

978 - `String callId`

979 

980 The ID of the computer tool call that produced the output.

981 

982 - `ResponseComputerToolCallOutputScreenshot output`

983 

984 A computer screenshot image used with the computer use tool.

985 

986 - `JsonValue; type "computer_screenshot"constant`

987 

988 Specifies the event type. For a computer screenshot, this property is

989 always set to `computer_screenshot`.

990 

991 - `COMPUTER_SCREENSHOT("computer_screenshot")`

992 

993 - `Optional<String> fileId`

994 

995 The identifier of an uploaded file that contains the screenshot.

996 

997 - `Optional<String> imageUrl`

998 

999 The URL of the screenshot image.

1000 

1001 - `JsonValue; type "computer_call_output"constant`

1002 

1003 The type of the computer tool call output. Always `computer_call_output`.

1004 

1005 - `COMPUTER_CALL_OUTPUT("computer_call_output")`

1006 

1007 - `Optional<String> id`

1008 

1009 The ID of the computer tool call output.

1010 

1011 - `Optional<List<AcknowledgedSafetyCheck>> acknowledgedSafetyChecks`

1012 

1013 The safety checks reported by the API that have been acknowledged by the developer.

1014 

1015 - `String id`

1016 

1017 The ID of the pending safety check.

1018 

1019 - `Optional<String> code`

1020 

1021 The type of the pending safety check.

1022 

1023 - `Optional<String> message`

1024 

1025 Details about the pending safety check.

1026 

1027 - `Optional<Status> status`

1028 

1029 The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API.

1030 

1031 - `IN_PROGRESS("in_progress")`

1032 

1033 - `COMPLETED("completed")`

1034 

1035 - `INCOMPLETE("incomplete")`

1036 

1037 - `class ResponseFunctionWebSearch:`

1038 

1039 The results of a web search tool call. See the

1040 [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information.

1041 

1042 - `String id`

1043 

1044 The unique ID of the web search tool call.

1045 

1046 - `Action action`

1047 

1048 An object describing the specific action taken in this web search call.

1049 Includes details on how the model used the web (search, open_page, find_in_page).

1050 

1051 - `class Search:`

1052 

1053 Action type "search" - Performs a web search query.

1054 

1055 - `String query`

1056 

1057 [DEPRECATED] The search query.

1058 

1059 - `JsonValue; type "search"constant`

1060 

1061 The action type.

1062 

1063 - `SEARCH("search")`

1064 

1065 - `Optional<List<String>> queries`

1066 

1067 The search queries.

1068 

1069 - `Optional<List<Source>> sources`

1070 

1071 The sources used in the search.

1072 

1073 - `JsonValue; type "url"constant`

1074 

1075 The type of source. Always `url`.

1076 

1077 - `URL("url")`

1078 

1079 - `String url`

1080 

1081 The URL of the source.

1082 

1083 - `class OpenPage:`

1084 

1085 Action type "open_page" - Opens a specific URL from search results.

1086 

1087 - `JsonValue; type "open_page"constant`

1088 

1089 The action type.

1090 

1091 - `OPEN_PAGE("open_page")`

1092 

1093 - `Optional<String> url`

1094 

1095 The URL opened by the model.

1096 

1097 - `class FindInPage:`

1098 

1099 Action type "find_in_page": Searches for a pattern within a loaded page.

1100 

1101 - `String pattern`

1102 

1103 The pattern or text to search for within the page.

1104 

1105 - `JsonValue; type "find_in_page"constant`

1106 

1107 The action type.

1108 

1109 - `FIND_IN_PAGE("find_in_page")`

1110 

1111 - `String url`

1112 

1113 The URL of the page searched for the pattern.

1114 

1115 - `Status status`

1116 

1117 The status of the web search tool call.

1118 

1119 - `IN_PROGRESS("in_progress")`

1120 

1121 - `SEARCHING("searching")`

1122 

1123 - `COMPLETED("completed")`

1124 

1125 - `FAILED("failed")`

1126 

1127 - `JsonValue; type "web_search_call"constant`

1128 

1129 The type of the web search tool call. Always `web_search_call`.

1130 

1131 - `WEB_SEARCH_CALL("web_search_call")`

1132 

1133 - `class ResponseFunctionToolCall:`

1134 

1135 A tool call to run a function. See the

1136 [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information.

1137 

1138 - `String arguments`

1139 

1140 A JSON string of the arguments to pass to the function.

1141 

1142 - `String callId`

1143 

1144 The unique ID of the function tool call generated by the model.

1145 

1146 - `String name`

1147 

1148 The name of the function to run.

1149 

1150 - `JsonValue; type "function_call"constant`

1151 

1152 The type of the function tool call. Always `function_call`.

1153 

1154 - `FUNCTION_CALL("function_call")`

1155 

1156 - `Optional<String> id`

1157 

1158 The unique ID of the function tool call.

1159 

1160 - `Optional<String> namespace`

1161 

1162 The namespace of the function to run.

1163 

1164 - `Optional<Status> status`

1165 

1166 The status of the item. One of `in_progress`, `completed`, or

1167 `incomplete`. Populated when items are returned via API.

1168 

1169 - `IN_PROGRESS("in_progress")`

1170 

1171 - `COMPLETED("completed")`

1172 

1173 - `INCOMPLETE("incomplete")`

1174 

1175 - `FunctionCallOutput`

1176 

1177 - `String callId`

1178 

1179 The unique ID of the function tool call generated by the model.

1180 

1181 - `Output output`

1182 

1183 Text, image, or file output of the function tool call.

1184 

1185 - `String`

1186 

1187 - `List<ResponseFunctionCallOutputItem>`

1188 

1189 - `class ResponseInputTextContent:`

1190 

1191 A text input to the model.

1192 

1193 - `String text`

1194 

1195 The text input to the model.

1196 

1197 - `JsonValue; type "input_text"constant`

1198 

1199 The type of the input item. Always `input_text`.

1200 

1201 - `INPUT_TEXT("input_text")`

1202 

1203 - `class ResponseInputImageContent:`

1204 

1205 An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision)

1206 

1207 - `JsonValue; type "input_image"constant`

1208 

1209 The type of the input item. Always `input_image`.

1210 

1211 - `INPUT_IMAGE("input_image")`

1212 

1213 - `Optional<Detail> detail`

1214 

1215 The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.

1216 

1217 - `LOW("low")`

1218 

1219 - `HIGH("high")`

1220 

1221 - `AUTO("auto")`

1222 

1223 - `ORIGINAL("original")`

1224 

1225 - `Optional<String> fileId`

1226 

1227 The ID of the file to be sent to the model.

1228 

1229 - `Optional<String> imageUrl`

1230 

1231 The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

1232 

1233 - `class ResponseInputFileContent:`

1234 

1235 A file input to the model.

1236 

1237 - `JsonValue; type "input_file"constant`

1238 

1239 The type of the input item. Always `input_file`.

1240 

1241 - `INPUT_FILE("input_file")`

1242 

1243 - `Optional<Detail> detail`

1244 

1245 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

1246 

1247 - `LOW("low")`

1248 

1249 - `HIGH("high")`

1250 

1251 - `Optional<String> fileData`

1252 

1253 The base64-encoded data of the file to be sent to the model.

1254 

1255 - `Optional<String> fileId`

1256 

1257 The ID of the file to be sent to the model.

1258 

1259 - `Optional<String> fileUrl`

1260 

1261 The URL of the file to be sent to the model.

1262 

1263 - `Optional<String> filename`

1264 

1265 The name of the file to be sent to the model.

1266 

1267 - `JsonValue; type "function_call_output"constant`

1268 

1269 The type of the function tool call output. Always `function_call_output`.

1270 

1271 - `FUNCTION_CALL_OUTPUT("function_call_output")`

1272 

1273 - `Optional<String> id`

1274 

1275 The unique ID of the function tool call output. Populated when this item is returned via API.

1276 

1277 - `Optional<Status> status`

1278 

1279 The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.

1280 

1281 - `IN_PROGRESS("in_progress")`

1282 

1283 - `COMPLETED("completed")`

1284 

1285 - `INCOMPLETE("incomplete")`

1286 

1287 - `ToolSearchCall`

1288 

1289 - `JsonValue arguments`

1290 

1291 The arguments supplied to the tool search call.

1292 

1293 - `JsonValue; type "tool_search_call"constant`

1294 

1295 The item type. Always `tool_search_call`.

1296 

1297 - `TOOL_SEARCH_CALL("tool_search_call")`

1298 

1299 - `Optional<String> id`

1300 

1301 The unique ID of this tool search call.

1302 

1303 - `Optional<String> callId`

1304 

1305 The unique ID of the tool search call generated by the model.

1306 

1307 - `Optional<Execution> execution`

1308 

1309 Whether tool search was executed by the server or by the client.

1310 

1311 - `SERVER("server")`

1312 

1313 - `CLIENT("client")`

1314 

1315 - `Optional<Status> status`

1316 

1317 The status of the tool search call.

1318 

1319 - `IN_PROGRESS("in_progress")`

1320 

1321 - `COMPLETED("completed")`

1322 

1323 - `INCOMPLETE("incomplete")`

1324 

1325 - `class ResponseToolSearchOutputItemParam:`

1326 

1327 - `List<Tool> tools`

1328 

1329 The loaded tool definitions returned by the tool search output.

1330 

1331 - `class FunctionTool:`

1332 

1333 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).

1334 

1335 - `String name`

1336 

1337 The name of the function to call.

1338 

1339 - `Optional<Parameters> parameters`

1340 

1341 A JSON schema object describing the parameters of the function.

1342 

1343 - `Optional<Boolean> strict`

1344 

1345 Whether to enforce strict parameter validation. Default `true`.

1346 

1347 - `JsonValue; type "function"constant`

1348 

1349 The type of the function tool. Always `function`.

1350 

1351 - `FUNCTION("function")`

1352 

1353 - `Optional<Boolean> deferLoading`

1354 

1355 Whether this function is deferred and loaded via tool search.

1356 

1357 - `Optional<String> description`

1358 

1359 A description of the function. Used by the model to determine whether or not to call the function.

1360 

1361 - `class FileSearchTool:`

1362 

1363 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).

1364 

1365 - `JsonValue; type "file_search"constant`

1366 

1367 The type of the file search tool. Always `file_search`.

1368 

1369 - `FILE_SEARCH("file_search")`

1370 

1371 - `List<String> vectorStoreIds`

1372 

1373 The IDs of the vector stores to search.

1374 

1375 - `Optional<Filters> filters`

1376 

1377 A filter to apply.

1378 

1379 - `class ComparisonFilter:`

1380 

1381 A filter used to compare a specified attribute key to a given value using a defined comparison operation.

1382 

1383 - `String key`

1384 

1385 The key to compare against the value.

1386 

1387 - `Type type`

1388 

1389 Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.

1390 

1391 - `eq`: equals

1392 - `ne`: not equal

1393 - `gt`: greater than

1394 - `gte`: greater than or equal

1395 - `lt`: less than

1396 - `lte`: less than or equal

1397 - `in`: in

1398 - `nin`: not in

1399 

1400 - `EQ("eq")`

1401 

1402 - `NE("ne")`

1403 

1404 - `GT("gt")`

1405 

1406 - `GTE("gte")`

1407 

1408 - `LT("lt")`

1409 

1410 - `LTE("lte")`

1411 

1412 - `IN("in")`

1413 

1414 - `NIN("nin")`

1415 

1416 - `Value value`

1417 

1418 The value to compare against the attribute key; supports string, number, or boolean types.

1419 

1420 - `String`

1421 

1422 - `double`

1423 

1424 - `boolean`

1425 

1426 - `List<ComparisonFilterValueItem>`

1427 

1428 - `String`

1429 

1430 - `double`

1431 

1432 - `class CompoundFilter:`

1433 

1434 Combine multiple filters using `and` or `or`.

1435 

1436 - `List<Filter> filters`

1437 

1438 Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.

1439 

1440 - `class ComparisonFilter:`

1441 

1442 A filter used to compare a specified attribute key to a given value using a defined comparison operation.

1443 

1444 - `JsonValue`

1445 

1446 - `Type type`

1447 

1448 Type of operation: `and` or `or`.

1449 

1450 - `AND("and")`

1451 

1452 - `OR("or")`

1453 

1454 - `Optional<Long> maxNumResults`

1455 

1456 The maximum number of results to return. This number should be between 1 and 50 inclusive.

1457 

1458 - `Optional<RankingOptions> rankingOptions`

1459 

1460 Ranking options for search.

1461 

1462 - `Optional<HybridSearch> hybridSearch`

1463 

1464 Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

1465 

1466 - `double embeddingWeight`

1467 

1468 The weight of the embedding in the reciprocal ranking fusion.

1469 

1470 - `double textWeight`

1471 

1472 The weight of the text in the reciprocal ranking fusion.

1473 

1474 - `Optional<Ranker> ranker`

1475 

1476 The ranker to use for the file search.

1477 

1478 - `AUTO("auto")`

1479 

1480 - `DEFAULT_2024_11_15("default-2024-11-15")`

1481 

1482 - `Optional<Double> scoreThreshold`

1483 

1484 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.

1485 

1486 - `class ComputerTool:`

1487 

1488 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

1489 

1490 - `JsonValue; type "computer"constant`

1491 

1492 The type of the computer tool. Always `computer`.

1493 

1494 - `COMPUTER("computer")`

1495 

1496 - `class ComputerUsePreviewTool:`

1497 

1498 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

1499 

1500 - `long displayHeight`

1501 

1502 The height of the computer display.

1503 

1504 - `long displayWidth`

1505 

1506 The width of the computer display.

1507 

1508 - `Environment environment`

1509 

1510 The type of computer environment to control.

1511 

1512 - `WINDOWS("windows")`

1513 

1514 - `MAC("mac")`

1515 

1516 - `LINUX("linux")`

1517 

1518 - `UBUNTU("ubuntu")`

1519 

1520 - `BROWSER("browser")`

1521 

1522 - `JsonValue; type "computer_use_preview"constant`

1523 

1524 The type of the computer use tool. Always `computer_use_preview`.

1525 

1526 - `COMPUTER_USE_PREVIEW("computer_use_preview")`

1527 

1528 - `class WebSearchTool:`

1529 

1530 Search the Internet for sources related to the prompt. Learn more about the

1531 [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

1532 

1533 - `Type type`

1534 

1535 The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.

1536 

1537 - `WEB_SEARCH("web_search")`

1538 

1539 - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")`

1540 

1541 - `Optional<Filters> filters`

1542 

1543 Filters for the search.

1544 

1545 - `Optional<List<String>> allowedDomains`

1546 

1547 Allowed domains for the search. If not provided, all domains are allowed.

1548 Subdomains of the provided domains are allowed as well.

1549 

1550 Example: `["pubmed.ncbi.nlm.nih.gov"]`

1551 

1552 - `Optional<SearchContextSize> searchContextSize`

1553 

1554 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.

1555 

1556 - `LOW("low")`

1557 

1558 - `MEDIUM("medium")`

1559 

1560 - `HIGH("high")`

1561 

1562 - `Optional<UserLocation> userLocation`

1563 

1564 The approximate location of the user.

1565 

1566 - `Optional<String> city`

1567 

1568 Free text input for the city of the user, e.g. `San Francisco`.

1569 

1570 - `Optional<String> country`

1571 

1572 The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.

1573 

1574 - `Optional<String> region`

1575 

1576 Free text input for the region of the user, e.g. `California`.

1577 

1578 - `Optional<String> timezone`

1579 

1580 The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.

1581 

1582 - `Optional<Type> type`

1583 

1584 The type of location approximation. Always `approximate`.

1585 

1586 - `APPROXIMATE("approximate")`

1587 

1588 - `Mcp`

1589 

1590 - `String serverLabel`

1591 

1592 A label for this MCP server, used to identify it in tool calls.

1593 

1594 - `JsonValue; type "mcp"constant`

1595 

1596 The type of the MCP tool. Always `mcp`.

1597 

1598 - `MCP("mcp")`

1599 

1600 - `Optional<AllowedTools> allowedTools`

1601 

1602 List of allowed tool names or a filter object.

1603 

1604 - `List<String>`

1605 

1606 - `class McpToolFilter:`

1607 

1608 A filter object to specify which tools are allowed.

1609 

1610 - `Optional<Boolean> readOnly`

1611 

1612 Indicates whether or not a tool modifies data or is read-only. If an

1613 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1614 it will match this filter.

1615 

1616 - `Optional<List<String>> toolNames`

1617 

1618 List of allowed tool names.

1619 

1620 - `Optional<String> authorization`

1621 

1622 An OAuth access token that can be used with a remote MCP server, either

1623 with a custom MCP server URL or a service connector. Your application

1624 must handle the OAuth authorization flow and provide the token here.

1625 

1626 - `Optional<ConnectorId> connectorId`

1627 

1628 Identifier for service connectors, like those available in ChatGPT. One of

1629 `server_url` or `connector_id` must be provided. Learn more about service

1630 connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).

1631 

1632 Currently supported `connector_id` values are:

1633 

1634 - Dropbox: `connector_dropbox`

1635 - Gmail: `connector_gmail`

1636 - Google Calendar: `connector_googlecalendar`

1637 - Google Drive: `connector_googledrive`

1638 - Microsoft Teams: `connector_microsoftteams`

1639 - Outlook Calendar: `connector_outlookcalendar`

1640 - Outlook Email: `connector_outlookemail`

1641 - SharePoint: `connector_sharepoint`

1642 

1643 - `CONNECTOR_DROPBOX("connector_dropbox")`

1644 

1645 - `CONNECTOR_GMAIL("connector_gmail")`

1646 

1647 - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")`

1648 

1649 - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")`

1650 

1651 - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")`

1652 

1653 - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")`

1654 

1655 - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")`

1656 

1657 - `CONNECTOR_SHAREPOINT("connector_sharepoint")`

1658 

1659 - `Optional<Boolean> deferLoading`

1660 

1661 Whether this MCP tool is deferred and discovered via tool search.

1662 

1663 - `Optional<Headers> headers`

1664 

1665 Optional HTTP headers to send to the MCP server. Use for authentication

1666 or other purposes.

1667 

1668 - `Optional<RequireApproval> requireApproval`

1669 

1670 Specify which of the MCP server's tools require approval.

1671 

1672 - `class McpToolApprovalFilter:`

1673 

1674 Specify which of the MCP server's tools require approval. Can be

1675 `always`, `never`, or a filter object associated with tools

1676 that require approval.

1677 

1678 - `Optional<Always> always`

1679 

1680 A filter object to specify which tools are allowed.

1681 

1682 - `Optional<Boolean> readOnly`

1683 

1684 Indicates whether or not a tool modifies data or is read-only. If an

1685 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1686 it will match this filter.

1687 

1688 - `Optional<List<String>> toolNames`

1689 

1690 List of allowed tool names.

1691 

1692 - `Optional<Never> never`

1693 

1694 A filter object to specify which tools are allowed.

1695 

1696 - `Optional<Boolean> readOnly`

1697 

1698 Indicates whether or not a tool modifies data or is read-only. If an

1699 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1700 it will match this filter.

1701 

1702 - `Optional<List<String>> toolNames`

1703 

1704 List of allowed tool names.

1705 

1706 - `enum McpToolApprovalSetting:`

1707 

1708 Specify a single approval policy for all tools. One of `always` or

1709 `never`. When set to `always`, all tools will require approval. When

1710 set to `never`, all tools will not require approval.

1711 

1712 - `ALWAYS("always")`

1713 

1714 - `NEVER("never")`

1715 

1716 - `Optional<String> serverDescription`

1717 

1718 Optional description of the MCP server, used to provide more context.

1719 

1720 - `Optional<String> serverUrl`

1721 

1722 The URL for the MCP server. One of `server_url` or `connector_id` must be

1723 provided.

1724 

1725 - `CodeInterpreter`

1726 

1727 - `Container container`

1728 

1729 The code interpreter container. Can be a container ID or an object that

1730 specifies uploaded file IDs to make available to your code, along with an

1731 optional `memory_limit` setting.

1732 

1733 - `String`

1734 

1735 - `class CodeInterpreterToolAuto:`

1736 

1737 Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

1738 

1739 - `JsonValue; type "auto"constant`

1740 

1741 Always `auto`.

1742 

1743 - `AUTO("auto")`

1744 

1745 - `Optional<List<String>> fileIds`

1746 

1747 An optional list of uploaded files to make available to your code.

1748 

1749 - `Optional<MemoryLimit> memoryLimit`

1750 

1751 The memory limit for the code interpreter container.

1752 

1753 - `_1G("1g")`

1754 

1755 - `_4G("4g")`

1756 

1757 - `_16G("16g")`

1758 

1759 - `_64G("64g")`

1760 

1761 - `Optional<NetworkPolicy> networkPolicy`

1762 

1763 Network access policy for the container.

1764 

1765 - `class ContainerNetworkPolicyDisabled:`

1766 

1767 - `JsonValue; type "disabled"constant`

1768 

1769 Disable outbound network access. Always `disabled`.

1770 

1771 - `DISABLED("disabled")`

1772 

1773 - `class ContainerNetworkPolicyAllowlist:`

1774 

1775 - `List<String> allowedDomains`

1776 

1777 A list of allowed domains when type is `allowlist`.

1778 

1779 - `JsonValue; type "allowlist"constant`

1780 

1781 Allow outbound network access only to specified domains. Always `allowlist`.

1782 

1783 - `ALLOWLIST("allowlist")`

1784 

1785 - `Optional<List<ContainerNetworkPolicyDomainSecret>> domainSecrets`

1786 

1787 Optional domain-scoped secrets for allowlisted domains.

1788 

1789 - `String domain`

1790 

1791 The domain associated with the secret.

1792 

1793 - `String name`

1794 

1795 The name of the secret to inject for the domain.

1796 

1797 - `String value`

1798 

1799 The secret value to inject for the domain.

1800 

1801 - `JsonValue; type "code_interpreter"constant`

1802 

1803 The type of the code interpreter tool. Always `code_interpreter`.

1804 

1805 - `CODE_INTERPRETER("code_interpreter")`

1806 

1807 - `ImageGeneration`

1808 

1809 - `JsonValue; type "image_generation"constant`

1810 

1811 The type of the image generation tool. Always `image_generation`.

1812 

1813 - `IMAGE_GENERATION("image_generation")`

1814 

1815 - `Optional<Action> action`

1816 

1817 Whether to generate a new image or edit an existing image. Default: `auto`.

1818 

1819 - `GENERATE("generate")`

1820 

1821 - `EDIT("edit")`

1822 

1823 - `AUTO("auto")`

1824 

1825 - `Optional<Background> background`

1826 

1827 Allows to set transparency for the background of the generated image(s).

1828 This parameter is only supported for GPT image models that support

1829 transparent backgrounds. Must be one of `transparent`, `opaque`, or

1830 `auto` (default value). When `auto` is used, the model will

1831 automatically determine the best background for the image.

1832 

1833 `gpt-image-2` and `gpt-image-2-2026-04-21` do not support

1834 transparent backgrounds. Requests with `background` set to

1835 `transparent` will return an error for these models; use `opaque` or

1836 `auto` instead.

1837 

1838 If `transparent`, the output format needs to support transparency,

1839 so it should be set to either `png` (default value) or `webp`.

1840 

1841 - `TRANSPARENT("transparent")`

1842 

1843 - `OPAQUE("opaque")`

1844 

1845 - `AUTO("auto")`

1846 

1847 - `Optional<InputFidelity> inputFidelity`

1848 

1849 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`.

1850 

1851 - `HIGH("high")`

1852 

1853 - `LOW("low")`

1854 

1855 - `Optional<InputImageMask> inputImageMask`

1856 

1857 Optional mask for inpainting. Contains `image_url`

1858 (string, optional) and `file_id` (string, optional).

1859 

1860 - `Optional<String> fileId`

1861 

1862 File ID for the mask image.

1863 

1864 - `Optional<String> imageUrl`

1865 

1866 Base64-encoded mask image.

1867 

1868 - `Optional<Model> model`

1869 

1870 The image generation model to use. Default: `gpt-image-1`.

1871 

1872 - `GPT_IMAGE_1("gpt-image-1")`

1873 

1874 - `GPT_IMAGE_1_MINI("gpt-image-1-mini")`

1875 

1876 - `GPT_IMAGE_2("gpt-image-2")`

1877 

1878 - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")`

1879 

1880 - `GPT_IMAGE_1_5("gpt-image-1.5")`

1881 

1882 - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")`

1883 

1884 - `Optional<Moderation> moderation`

1885 

1886 Moderation level for the generated image. Default: `auto`.

1887 

1888 - `AUTO("auto")`

1889 

1890 - `LOW("low")`

1891 

1892 - `Optional<Long> outputCompression`

1893 

1894 Compression level for the output image. Default: 100.

1895 

1896 - `Optional<OutputFormat> outputFormat`

1897 

1898 The output format of the generated image. One of `png`, `webp`, or

1899 `jpeg`. Default: `png`.

1900 

1901 - `PNG("png")`

1902 

1903 - `WEBP("webp")`

1904 

1905 - `JPEG("jpeg")`

1906 

1907 - `Optional<Long> partialImages`

1908 

1909 Number of partial images to generate in streaming mode, from 0 (default value) to 3.

1910 

1911 - `Optional<Quality> quality`

1912 

1913 The quality of the generated image. One of `low`, `medium`, `high`,

1914 or `auto`. Default: `auto`.

1915 

1916 - `LOW("low")`

1917 

1918 - `MEDIUM("medium")`

1919 

1920 - `HIGH("high")`

1921 

1922 - `AUTO("auto")`

1923 

1924 - `Optional<Size> size`

1925 

1926 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`.

1927 

1928 - `_1024X1024("1024x1024")`

1929 

1930 - `_1024X1536("1024x1536")`

1931 

1932 - `_1536X1024("1536x1024")`

1933 

1934 - `AUTO("auto")`

1935 

1936 - `JsonValue;`

1937 

1938 - `JsonValue; type "local_shell"constant`

1939 

1940 The type of the local shell tool. Always `local_shell`.

1941 

1942 - `LOCAL_SHELL("local_shell")`

1943 

1944 - `class FunctionShellTool:`

1945 

1946 A tool that allows the model to execute shell commands.

1947 

1948 - `JsonValue; type "shell"constant`

1949 

1950 The type of the shell tool. Always `shell`.

1951 

1952 - `SHELL("shell")`

1953 

1954 - `Optional<Environment> environment`

1955 

1956 - `class ContainerAuto:`

1957 

1958 - `JsonValue; type "container_auto"constant`

1959 

1960 Automatically creates a container for this request

1961 

1962 - `CONTAINER_AUTO("container_auto")`

1963 

1964 - `Optional<List<String>> fileIds`

1965 

1966 An optional list of uploaded files to make available to your code.

1967 

1968 - `Optional<MemoryLimit> memoryLimit`

1969 

1970 The memory limit for the container.

1971 

1972 - `_1G("1g")`

1973 

1974 - `_4G("4g")`

1975 

1976 - `_16G("16g")`

1977 

1978 - `_64G("64g")`

1979 

1980 - `Optional<NetworkPolicy> networkPolicy`

1981 

1982 Network access policy for the container.

1983 

1984 - `class ContainerNetworkPolicyDisabled:`

1985 

1986 - `class ContainerNetworkPolicyAllowlist:`

1987 

1988 - `Optional<List<Skill>> skills`

1989 

1990 An optional list of skills referenced by id or inline data.

1991 

1992 - `class SkillReference:`

1993 

1994 - `String skillId`

1995 

1996 The ID of the referenced skill.