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

1## Cancel a response

2 

3`responses.cancel(response_id) -> Response`

4 

5**post** `/responses/{response_id}/cancel`

6 

7Cancels a model response with the given ID. Only responses created with

8the `background` parameter set to `true` can be cancelled.

9[Learn more](https://platform.openai.com/docs/guides/background).

10 

11### Parameters

12 

13- `response_id: String`

14 

15### Returns

16 

17- `class Response`

18 

19 - `id: String`

20 

21 Unique identifier for this Response.

22 

23 - `created_at: Float`

24 

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

26 

27 - `error: ResponseError`

28 

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

30 

31 - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more`

32 

33 The error code for the response.

34 

35 - `:server_error`

36 

37 - `:rate_limit_exceeded`

38 

39 - `:invalid_prompt`

40 

41 - `:vector_store_timeout`

42 

43 - `:invalid_image`

44 

45 - `:invalid_image_format`

46 

47 - `:invalid_base64_image`

48 

49 - `:invalid_image_url`

50 

51 - `:image_too_large`

52 

53 - `:image_too_small`

54 

55 - `:image_parse_error`

56 

57 - `:image_content_policy_violation`

58 

59 - `:invalid_image_mode`

60 

61 - `:image_file_too_large`

62 

63 - `:unsupported_image_media_type`

64 

65 - `:empty_image_file`

66 

67 - `:failed_to_download_image`

68 

69 - `:image_file_not_found`

70 

71 - `message: String`

72 

73 A human-readable description of the error.

74 

75 - `incomplete_details: IncompleteDetails{ reason}`

76 

77 Details about why the response is incomplete.

78 

79 - `reason: :max_output_tokens | :content_filter`

80 

81 The reason why the response is incomplete.

82 

83 - `:max_output_tokens`

84 

85 - `:content_filter`

86 

87 - `instructions: String | Array[ResponseInputItem]`

88 

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

90 

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

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

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

94 

95 - `String = String`

96 

97 A text input to the model, equivalent to a text input with the

98 `developer` role.

99 

100 - `InputItemList = Array[ResponseInputItem]`

101 

102 A list of one or many input items to the model, containing

103 different content types.

104 

105 - `class EasyInputMessage`

106 

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

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

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

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

111 interactions.

112 

113 - `content: String | ResponseInputMessageContentList`

114 

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

116 Can also contain previous assistant responses.

117 

118 - `String = String`

119 

120 A text input to the model.

121 

122 - `ResponseInputMessageContentList = Array[ResponseInputContent]`

123 

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

125 types.

126 

127 - `class ResponseInputText`

128 

129 A text input to the model.

130 

131 - `text: String`

132 

133 The text input to the model.

134 

135 - `type: :input_text`

136 

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

138 

139 - `:input_text`

140 

141 - `class ResponseInputImage`

142 

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

144 

145 - `detail: :low | :high | :auto | :original`

146 

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

148 

149 - `:low`

150 

151 - `:high`

152 

153 - `:auto`

154 

155 - `:original`

156 

157 - `type: :input_image`

158 

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

160 

161 - `:input_image`

162 

163 - `file_id: String`

164 

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

166 

167 - `image_url: String`

168 

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

170 

171 - `class ResponseInputFile`

172 

173 A file input to the model.

174 

175 - `type: :input_file`

176 

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

178 

179 - `:input_file`

180 

181 - `detail: :low | :high`

182 

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

184 

185 - `:low`

186 

187 - `:high`

188 

189 - `file_data: String`

190 

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

192 

193 - `file_id: String`

194 

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

196 

197 - `file_url: String`

198 

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

200 

201 - `filename: String`

202 

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

204 

205 - `role: :user | :assistant | :system | :developer`

206 

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

208 `developer`.

209 

210 - `:user`

211 

212 - `:assistant`

213 

214 - `:system`

215 

216 - `:developer`

217 

218 - `phase: :commentary | :final_answer`

219 

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

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

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

223 

224 - `:commentary`

225 

226 - `:final_answer`

227 

228 - `type: :message`

229 

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

231 

232 - `:message`

233 

234 - `class Message`

235 

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

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

238 precedence over instructions given with the `user` role.

239 

240 - `content: ResponseInputMessageContentList`

241 

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

243 types.

244 

245 - `role: :user | :system | :developer`

246 

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

248 

249 - `:user`

250 

251 - `:system`

252 

253 - `:developer`

254 

255 - `status: :in_progress | :completed | :incomplete`

256 

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

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

259 

260 - `:in_progress`

261 

262 - `:completed`

263 

264 - `:incomplete`

265 

266 - `type: :message`

267 

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

269 

270 - `:message`

271 

272 - `class ResponseOutputMessage`

273 

274 An output message from the model.

275 

276 - `id: String`

277 

278 The unique ID of the output message.

279 

280 - `content: Array[ResponseOutputText | ResponseOutputRefusal]`

281 

282 The content of the output message.

283 

284 - `class ResponseOutputText`

285 

286 A text output from the model.

287 

288 - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]`

289 

290 The annotations of the text output.

291 

292 - `class FileCitation`

293 

294 A citation to a file.

295 

296 - `file_id: String`

297 

298 The ID of the file.

299 

300 - `filename: String`

301 

302 The filename of the file cited.

303 

304 - `index: Integer`

305 

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

307 

308 - `type: :file_citation`

309 

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

311 

312 - `:file_citation`

313 

314 - `class URLCitation`

315 

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

317 

318 - `end_index: Integer`

319 

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

321 

322 - `start_index: Integer`

323 

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

325 

326 - `title: String`

327 

328 The title of the web resource.

329 

330 - `type: :url_citation`

331 

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

333 

334 - `:url_citation`

335 

336 - `url: String`

337 

338 The URL of the web resource.

339 

340 - `class ContainerFileCitation`

341 

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

343 

344 - `container_id: String`

345 

346 The ID of the container file.

347 

348 - `end_index: Integer`

349 

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

351 

352 - `file_id: String`

353 

354 The ID of the file.

355 

356 - `filename: String`

357 

358 The filename of the container file cited.

359 

360 - `start_index: Integer`

361 

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

363 

364 - `type: :container_file_citation`

365 

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

367 

368 - `:container_file_citation`

369 

370 - `class FilePath`

371 

372 A path to a file.

373 

374 - `file_id: String`

375 

376 The ID of the file.

377 

378 - `index: Integer`

379 

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

381 

382 - `type: :file_path`

383 

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

385 

386 - `:file_path`

387 

388 - `text: String`

389 

390 The text output from the model.

391 

392 - `type: :output_text`

393 

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

395 

396 - `:output_text`

397 

398 - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]`

399 

400 - `token: String`

401 

402 - `bytes: Array[Integer]`

403 

404 - `logprob: Float`

405 

406 - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]`

407 

408 - `token: String`

409 

410 - `bytes: Array[Integer]`

411 

412 - `logprob: Float`

413 

414 - `class ResponseOutputRefusal`

415 

416 A refusal from the model.

417 

418 - `refusal: String`

419 

420 The refusal explanation from the model.

421 

422 - `type: :refusal`

423 

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

425 

426 - `:refusal`

427 

428 - `role: :assistant`

429 

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

431 

432 - `:assistant`

433 

434 - `status: :in_progress | :completed | :incomplete`

435 

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

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

438 

439 - `:in_progress`

440 

441 - `:completed`

442 

443 - `:incomplete`

444 

445 - `type: :message`

446 

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

448 

449 - `:message`

450 

451 - `phase: :commentary | :final_answer`

452 

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

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

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

456 

457 - `:commentary`

458 

459 - `:final_answer`

460 

461 - `class ResponseFileSearchToolCall`

462 

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

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

465 

466 - `id: String`

467 

468 The unique ID of the file search tool call.

469 

470 - `queries: Array[String]`

471 

472 The queries used to search for files.

473 

474 - `status: :in_progress | :searching | :completed | 2 more`

475 

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

477 `searching`, `incomplete` or `failed`,

478 

479 - `:in_progress`

480 

481 - `:searching`

482 

483 - `:completed`

484 

485 - `:incomplete`

486 

487 - `:failed`

488 

489 - `type: :file_search_call`

490 

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

492 

493 - `:file_search_call`

494 

495 - `results: Array[Result{ attributes, file_id, filename, 2 more}]`

496 

497 The results of the file search tool call.

498 

499 - `attributes: Hash[Symbol, String | Float | bool]`

500 

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

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

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

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

505 length of 512 characters, booleans, or numbers.

506 

507 - `String = String`

508 

509 - `Float = Float`

510 

511 - `UnionMember2 = bool`

512 

513 - `file_id: String`

514 

515 The unique ID of the file.

516 

517 - `filename: String`

518 

519 The name of the file.

520 

521 - `score: Float`

522 

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

524 

525 - `text: String`

526 

527 The text that was retrieved from the file.

528 

529 - `class ResponseComputerToolCall`

530 

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

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

533 

534 - `id: String`

535 

536 The unique ID of the computer call.

537 

538 - `call_id: String`

539 

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

541 

542 - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]`

543 

544 The pending safety checks for the computer call.

545 

546 - `id: String`

547 

548 The ID of the pending safety check.

549 

550 - `code: String`

551 

552 The type of the pending safety check.

553 

554 - `message: String`

555 

556 Details about the pending safety check.

557 

558 - `status: :in_progress | :completed | :incomplete`

559 

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

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

562 

563 - `:in_progress`

564 

565 - `:completed`

566 

567 - `:incomplete`

568 

569 - `type: :computer_call`

570 

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

572 

573 - `:computer_call`

574 

575 - `action: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more`

576 

577 A click action.

578 

579 - `class Click`

580 

581 A click action.

582 

583 - `button: :left | :right | :wheel | 2 more`

584 

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

586 

587 - `:left`

588 

589 - `:right`

590 

591 - `:wheel`

592 

593 - `:back`

594 

595 - `:forward`

596 

597 - `type: :click`

598 

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

600 

601 - `:click`

602 

603 - `x: Integer`

604 

605 The x-coordinate where the click occurred.

606 

607 - `y_: Integer`

608 

609 The y-coordinate where the click occurred.

610 

611 - `keys: Array[String]`

612 

613 The keys being held while clicking.

614 

615 - `class DoubleClick`

616 

617 A double click action.

618 

619 - `keys: Array[String]`

620 

621 The keys being held while double-clicking.

622 

623 - `type: :double_click`

624 

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

626 

627 - `:double_click`

628 

629 - `x: Integer`

630 

631 The x-coordinate where the double click occurred.

632 

633 - `y_: Integer`

634 

635 The y-coordinate where the double click occurred.

636 

637 - `class Drag`

638 

639 A drag action.

640 

641 - `path: Array[Path{ x, y_}]`

642 

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

644 

645 ```

646 [

647 { x: 100, y: 200 },

648 { x: 200, y: 300 }

649 ]

650 ```

651 

652 - `x: Integer`

653 

654 The x-coordinate.

655 

656 - `y_: Integer`

657 

658 The y-coordinate.

659 

660 - `type: :drag`

661 

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

663 

664 - `:drag`

665 

666 - `keys: Array[String]`

667 

668 The keys being held while dragging the mouse.

669 

670 - `class Keypress`

671 

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

673 

674 - `keys: Array[String]`

675 

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

677 

678 - `type: :keypress`

679 

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

681 

682 - `:keypress`

683 

684 - `class Move`

685 

686 A mouse move action.

687 

688 - `type: :move`

689 

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

691 

692 - `:move`

693 

694 - `x: Integer`

695 

696 The x-coordinate to move to.

697 

698 - `y_: Integer`

699 

700 The y-coordinate to move to.

701 

702 - `keys: Array[String]`

703 

704 The keys being held while moving the mouse.

705 

706 - `class Screenshot`

707 

708 A screenshot action.

709 

710 - `type: :screenshot`

711 

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

713 

714 - `:screenshot`

715 

716 - `class Scroll`

717 

718 A scroll action.

719 

720 - `scroll_x: Integer`

721 

722 The horizontal scroll distance.

723 

724 - `scroll_y: Integer`

725 

726 The vertical scroll distance.

727 

728 - `type: :scroll`

729 

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

731 

732 - `:scroll`

733 

734 - `x: Integer`

735 

736 The x-coordinate where the scroll occurred.

737 

738 - `y_: Integer`

739 

740 The y-coordinate where the scroll occurred.

741 

742 - `keys: Array[String]`

743 

744 The keys being held while scrolling.

745 

746 - `class Type`

747 

748 An action to type in text.

749 

750 - `text: String`

751 

752 The text to type.

753 

754 - `type: :type`

755 

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

757 

758 - `:type`

759 

760 - `class Wait`

761 

762 A wait action.

763 

764 - `type: :wait`

765 

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

767 

768 - `:wait`

769 

770 - `actions: ComputerActionList`

771 

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

773 `type` discriminator and action-specific fields.

774 

775 - `class Click`

776 

777 A click action.

778 

779 - `button: :left | :right | :wheel | 2 more`

780 

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

782 

783 - `:left`

784 

785 - `:right`

786 

787 - `:wheel`

788 

789 - `:back`

790 

791 - `:forward`

792 

793 - `type: :click`

794 

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

796 

797 - `:click`

798 

799 - `x: Integer`

800 

801 The x-coordinate where the click occurred.

802 

803 - `y_: Integer`

804 

805 The y-coordinate where the click occurred.

806 

807 - `keys: Array[String]`

808 

809 The keys being held while clicking.

810 

811 - `class DoubleClick`

812 

813 A double click action.

814 

815 - `keys: Array[String]`

816 

817 The keys being held while double-clicking.

818 

819 - `type: :double_click`

820 

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

822 

823 - `:double_click`

824 

825 - `x: Integer`

826 

827 The x-coordinate where the double click occurred.

828 

829 - `y_: Integer`

830 

831 The y-coordinate where the double click occurred.

832 

833 - `class Drag`

834 

835 A drag action.

836 

837 - `path: Array[Path{ x, y_}]`

838 

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

840 

841 ```

842 [

843 { x: 100, y: 200 },

844 { x: 200, y: 300 }

845 ]

846 ```

847 

848 - `x: Integer`

849 

850 The x-coordinate.

851 

852 - `y_: Integer`

853 

854 The y-coordinate.

855 

856 - `type: :drag`

857 

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

859 

860 - `:drag`

861 

862 - `keys: Array[String]`

863 

864 The keys being held while dragging the mouse.

865 

866 - `class Keypress`

867 

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

869 

870 - `keys: Array[String]`

871 

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

873 

874 - `type: :keypress`

875 

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

877 

878 - `:keypress`

879 

880 - `class Move`

881 

882 A mouse move action.

883 

884 - `type: :move`

885 

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

887 

888 - `:move`

889 

890 - `x: Integer`

891 

892 The x-coordinate to move to.

893 

894 - `y_: Integer`

895 

896 The y-coordinate to move to.

897 

898 - `keys: Array[String]`

899 

900 The keys being held while moving the mouse.

901 

902 - `class Screenshot`

903 

904 A screenshot action.

905 

906 - `type: :screenshot`

907 

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

909 

910 - `:screenshot`

911 

912 - `class Scroll`

913 

914 A scroll action.

915 

916 - `scroll_x: Integer`

917 

918 The horizontal scroll distance.

919 

920 - `scroll_y: Integer`

921 

922 The vertical scroll distance.

923 

924 - `type: :scroll`

925 

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

927 

928 - `:scroll`

929 

930 - `x: Integer`

931 

932 The x-coordinate where the scroll occurred.

933 

934 - `y_: Integer`

935 

936 The y-coordinate where the scroll occurred.

937 

938 - `keys: Array[String]`

939 

940 The keys being held while scrolling.

941 

942 - `class Type`

943 

944 An action to type in text.

945 

946 - `text: String`

947 

948 The text to type.

949 

950 - `type: :type`

951 

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

953 

954 - `:type`

955 

956 - `class Wait`

957 

958 A wait action.

959 

960 - `type: :wait`

961 

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

963 

964 - `:wait`

965 

966 - `class ComputerCallOutput`

967 

968 The output of a computer tool call.

969 

970 - `call_id: String`

971 

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

973 

974 - `output: ResponseComputerToolCallOutputScreenshot`

975 

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

977 

978 - `type: :computer_screenshot`

979 

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

981 always set to `computer_screenshot`.

982 

983 - `:computer_screenshot`

984 

985 - `file_id: String`

986 

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

988 

989 - `image_url: String`

990 

991 The URL of the screenshot image.

992 

993 - `type: :computer_call_output`

994 

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

996 

997 - `:computer_call_output`

998 

999 - `id: String`

1000 

1001 The ID of the computer tool call output.

1002 

1003 - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]`

1004 

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

1006 

1007 - `id: String`

1008 

1009 The ID of the pending safety check.

1010 

1011 - `code: String`

1012 

1013 The type of the pending safety check.

1014 

1015 - `message: String`

1016 

1017 Details about the pending safety check.

1018 

1019 - `status: :in_progress | :completed | :incomplete`

1020 

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

1022 

1023 - `:in_progress`

1024 

1025 - `:completed`

1026 

1027 - `:incomplete`

1028 

1029 - `class ResponseFunctionWebSearch`

1030 

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

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

1033 

1034 - `id: String`

1035 

1036 The unique ID of the web search tool call.

1037 

1038 - `action: Search{ query, type, queries, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}`

1039 

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

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

1042 

1043 - `class Search`

1044 

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

1046 

1047 - `query: String`

1048 

1049 [DEPRECATED] The search query.

1050 

1051 - `type: :search`

1052 

1053 The action type.

1054 

1055 - `:search`

1056 

1057 - `queries: Array[String]`

1058 

1059 The search queries.

1060 

1061 - `sources: Array[Source{ type, url}]`

1062 

1063 The sources used in the search.

1064 

1065 - `type: :url`

1066 

1067 The type of source. Always `url`.

1068 

1069 - `:url`

1070 

1071 - `url: String`

1072 

1073 The URL of the source.

1074 

1075 - `class OpenPage`

1076 

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

1078 

1079 - `type: :open_page`

1080 

1081 The action type.

1082 

1083 - `:open_page`

1084 

1085 - `url: String`

1086 

1087 The URL opened by the model.

1088 

1089 - `class FindInPage`

1090 

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

1092 

1093 - `pattern: String`

1094 

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

1096 

1097 - `type: :find_in_page`

1098 

1099 The action type.

1100 

1101 - `:find_in_page`

1102 

1103 - `url: String`

1104 

1105 The URL of the page searched for the pattern.

1106 

1107 - `status: :in_progress | :searching | :completed | :failed`

1108 

1109 The status of the web search tool call.

1110 

1111 - `:in_progress`

1112 

1113 - `:searching`

1114 

1115 - `:completed`

1116 

1117 - `:failed`

1118 

1119 - `type: :web_search_call`

1120 

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

1122 

1123 - `:web_search_call`

1124 

1125 - `class ResponseFunctionToolCall`

1126 

1127 A tool call to run a function. See the

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

1129 

1130 - `arguments: String`

1131 

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

1133 

1134 - `call_id: String`

1135 

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

1137 

1138 - `name: String`

1139 

1140 The name of the function to run.

1141 

1142 - `type: :function_call`

1143 

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

1145 

1146 - `:function_call`

1147 

1148 - `id: String`

1149 

1150 The unique ID of the function tool call.

1151 

1152 - `namespace: String`

1153 

1154 The namespace of the function to run.

1155 

1156 - `status: :in_progress | :completed | :incomplete`

1157 

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

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

1160 

1161 - `:in_progress`

1162 

1163 - `:completed`

1164 

1165 - `:incomplete`

1166 

1167 - `class FunctionCallOutput`

1168 

1169 The output of a function tool call.

1170 

1171 - `call_id: String`

1172 

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

1174 

1175 - `output: String | ResponseFunctionCallOutputItemList`

1176 

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

1178 

1179 - `String = String`

1180 

1181 A JSON string of the output of the function tool call.

1182 

1183 - `ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]`

1184 

1185 An array of content outputs (text, image, file) for the function tool call.

1186 

1187 - `class ResponseInputTextContent`

1188 

1189 A text input to the model.

1190 

1191 - `text: String`

1192 

1193 The text input to the model.

1194 

1195 - `type: :input_text`

1196 

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

1198 

1199 - `:input_text`

1200 

1201 - `class ResponseInputImageContent`

1202 

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

1204 

1205 - `type: :input_image`

1206 

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

1208 

1209 - `:input_image`

1210 

1211 - `detail: :low | :high | :auto | :original`

1212 

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

1214 

1215 - `:low`

1216 

1217 - `:high`

1218 

1219 - `:auto`

1220 

1221 - `:original`

1222 

1223 - `file_id: String`

1224 

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

1226 

1227 - `image_url: String`

1228 

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

1230 

1231 - `class ResponseInputFileContent`

1232 

1233 A file input to the model.

1234 

1235 - `type: :input_file`

1236 

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

1238 

1239 - `:input_file`

1240 

1241 - `detail: :low | :high`

1242 

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

1244 

1245 - `:low`

1246 

1247 - `:high`

1248 

1249 - `file_data: String`

1250 

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

1252 

1253 - `file_id: String`

1254 

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

1256 

1257 - `file_url: String`

1258 

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

1260 

1261 - `filename: String`

1262 

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

1264 

1265 - `type: :function_call_output`

1266 

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

1268 

1269 - `:function_call_output`

1270 

1271 - `id: String`

1272 

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

1274 

1275 - `status: :in_progress | :completed | :incomplete`

1276 

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

1278 

1279 - `:in_progress`

1280 

1281 - `:completed`

1282 

1283 - `:incomplete`

1284 

1285 - `class ToolSearchCall`

1286 

1287 - `arguments: untyped`

1288 

1289 The arguments supplied to the tool search call.

1290 

1291 - `type: :tool_search_call`

1292 

1293 The item type. Always `tool_search_call`.

1294 

1295 - `:tool_search_call`

1296 

1297 - `id: String`

1298 

1299 The unique ID of this tool search call.

1300 

1301 - `call_id: String`

1302 

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

1304 

1305 - `execution: :server | :client`

1306 

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

1308 

1309 - `:server`

1310 

1311 - `:client`

1312 

1313 - `status: :in_progress | :completed | :incomplete`

1314 

1315 The status of the tool search call.

1316 

1317 - `:in_progress`

1318 

1319 - `:completed`

1320 

1321 - `:incomplete`

1322 

1323 - `class ResponseToolSearchOutputItemParam`

1324 

1325 - `tools: Array[Tool]`

1326 

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

1328 

1329 - `class FunctionTool`

1330 

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

1332 

1333 - `name: String`

1334 

1335 The name of the function to call.

1336 

1337 - `parameters: Hash[Symbol, untyped]`

1338 

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

1340 

1341 - `strict: bool`

1342 

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

1344 

1345 - `type: :function`

1346 

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

1348 

1349 - `:function`

1350 

1351 - `defer_loading: bool`

1352 

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

1354 

1355 - `description: String`

1356 

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

1358 

1359 - `class FileSearchTool`

1360 

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

1362 

1363 - `type: :file_search`

1364 

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

1366 

1367 - `:file_search`

1368 

1369 - `vector_store_ids: Array[String]`

1370 

1371 The IDs of the vector stores to search.

1372 

1373 - `filters: ComparisonFilter | CompoundFilter`

1374 

1375 A filter to apply.

1376 

1377 - `class ComparisonFilter`

1378 

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

1380 

1381 - `key: String`

1382 

1383 The key to compare against the value.

1384 

1385 - `type: :eq | :ne | :gt | 5 more`

1386 

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

1388 

1389 - `eq`: equals

1390 - `ne`: not equal

1391 - `gt`: greater than

1392 - `gte`: greater than or equal

1393 - `lt`: less than

1394 - `lte`: less than or equal

1395 - `in`: in

1396 - `nin`: not in

1397 

1398 - `:eq`

1399 

1400 - `:ne`

1401 

1402 - `:gt`

1403 

1404 - `:gte`

1405 

1406 - `:lt`

1407 

1408 - `:lte`

1409 

1410 - `:in`

1411 

1412 - `:nin`

1413 

1414 - `value: String | Float | bool | Array[String | Float]`

1415 

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

1417 

1418 - `String = String`

1419 

1420 - `Float = Float`

1421 

1422 - `UnionMember2 = bool`

1423 

1424 - `UnionMember3 = Array[String | Float]`

1425 

1426 - `String = String`

1427 

1428 - `Float = Float`

1429 

1430 - `class CompoundFilter`

1431 

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

1433 

1434 - `filters: Array[ComparisonFilter | untyped]`

1435 

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

1437 

1438 - `class ComparisonFilter`

1439 

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

1441 

1442 - `UnionMember1 = untyped`

1443 

1444 - `type: :and | :or`

1445 

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

1447 

1448 - `:and`

1449 

1450 - `:or`

1451 

1452 - `max_num_results: Integer`

1453 

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

1455 

1456 - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}`

1457 

1458 Ranking options for search.

1459 

1460 - `hybrid_search: HybridSearch{ embedding_weight, text_weight}`

1461 

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

1463 

1464 - `embedding_weight: Float`

1465 

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

1467 

1468 - `text_weight: Float`

1469 

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

1471 

1472 - `ranker: :auto | :"default-2024-11-15"`

1473 

1474 The ranker to use for the file search.

1475 

1476 - `:auto`

1477 

1478 - `:"default-2024-11-15"`

1479 

1480 - `score_threshold: Float`

1481 

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

1483 

1484 - `class ComputerTool`

1485 

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

1487 

1488 - `type: :computer`

1489 

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

1491 

1492 - `:computer`

1493 

1494 - `class ComputerUsePreviewTool`

1495 

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

1497 

1498 - `display_height: Integer`

1499 

1500 The height of the computer display.

1501 

1502 - `display_width: Integer`

1503 

1504 The width of the computer display.

1505 

1506 - `environment: :windows | :mac | :linux | 2 more`

1507 

1508 The type of computer environment to control.

1509 

1510 - `:windows`

1511 

1512 - `:mac`

1513 

1514 - `:linux`

1515 

1516 - `:ubuntu`

1517 

1518 - `:browser`

1519 

1520 - `type: :computer_use_preview`

1521 

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

1523 

1524 - `:computer_use_preview`

1525 

1526 - `class WebSearchTool`

1527 

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

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

1530 

1531 - `type: :web_search | :web_search_2025_08_26`

1532 

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

1534 

1535 - `:web_search`

1536 

1537 - `:web_search_2025_08_26`

1538 

1539 - `filters: Filters{ allowed_domains}`

1540 

1541 Filters for the search.

1542 

1543 - `allowed_domains: Array[String]`

1544 

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

1546 Subdomains of the provided domains are allowed as well.

1547 

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

1549 

1550 - `search_context_size: :low | :medium | :high`

1551 

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

1553 

1554 - `:low`

1555 

1556 - `:medium`

1557 

1558 - `:high`

1559 

1560 - `user_location: UserLocation{ city, country, region, 2 more}`

1561 

1562 The approximate location of the user.

1563 

1564 - `city: String`

1565 

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

1567 

1568 - `country: String`

1569 

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

1571 

1572 - `region: String`

1573 

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

1575 

1576 - `timezone: String`

1577 

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

1579 

1580 - `type: :approximate`

1581 

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

1583 

1584 - `:approximate`

1585 

1586 - `class Mcp`

1587 

1588 Give the model access to additional tools via remote Model Context Protocol

1589 (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp).

1590 

1591 - `server_label: String`

1592 

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

1594 

1595 - `type: :mcp`

1596 

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

1598 

1599 - `:mcp`

1600 

1601 - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}`

1602 

1603 List of allowed tool names or a filter object.

1604 

1605 - `McpAllowedTools = Array[String]`

1606 

1607 A string array of allowed tool names

1608 

1609 - `class McpToolFilter`

1610 

1611 A filter object to specify which tools are allowed.

1612 

1613 - `read_only: bool`

1614 

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

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

1617 it will match this filter.

1618 

1619 - `tool_names: Array[String]`

1620 

1621 List of allowed tool names.

1622 

1623 - `authorization: String`

1624 

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

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

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

1628 

1629 - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more`

1630 

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

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

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

1634 

1635 Currently supported `connector_id` values are:

1636 

1637 - Dropbox: `connector_dropbox`

1638 - Gmail: `connector_gmail`

1639 - Google Calendar: `connector_googlecalendar`

1640 - Google Drive: `connector_googledrive`

1641 - Microsoft Teams: `connector_microsoftteams`

1642 - Outlook Calendar: `connector_outlookcalendar`

1643 - Outlook Email: `connector_outlookemail`

1644 - SharePoint: `connector_sharepoint`

1645 

1646 - `:connector_dropbox`

1647 

1648 - `:connector_gmail`

1649 

1650 - `:connector_googlecalendar`

1651 

1652 - `:connector_googledrive`

1653 

1654 - `:connector_microsoftteams`

1655 

1656 - `:connector_outlookcalendar`

1657 

1658 - `:connector_outlookemail`

1659 

1660 - `:connector_sharepoint`

1661 

1662 - `defer_loading: bool`

1663 

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

1665 

1666 - `headers: Hash[Symbol, String]`

1667 

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

1669 or other purposes.

1670 

1671 - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never`

1672 

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

1674 

1675 - `class McpToolApprovalFilter`

1676 

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

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

1679 that require approval.

1680 

1681 - `always: Always{ read_only, tool_names}`

1682 

1683 A filter object to specify which tools are allowed.

1684 

1685 - `read_only: bool`

1686 

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

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

1689 it will match this filter.

1690 

1691 - `tool_names: Array[String]`

1692 

1693 List of allowed tool names.

1694 

1695 - `never: Never{ read_only, tool_names}`

1696 

1697 A filter object to specify which tools are allowed.

1698 

1699 - `read_only: bool`

1700 

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

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

1703 it will match this filter.

1704 

1705 - `tool_names: Array[String]`

1706 

1707 List of allowed tool names.

1708 

1709 - `McpToolApprovalSetting = :always | :never`

1710 

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

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

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

1714 

1715 - `:always`

1716 

1717 - `:never`

1718 

1719 - `server_description: String`

1720 

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

1722 

1723 - `server_url: String`

1724 

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

1726 provided.

1727 

1728 - `class CodeInterpreter`

1729 

1730 A tool that runs Python code to help generate a response to a prompt.

1731 

1732 - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}`

1733 

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

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

1736 optional `memory_limit` setting.

1737 

1738 - `String = String`

1739 

1740 The container ID.

1741 

1742 - `class CodeInterpreterToolAuto`

1743 

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

1745 

1746 - `type: :auto`

1747 

1748 Always `auto`.

1749 

1750 - `:auto`

1751 

1752 - `file_ids: Array[String]`

1753 

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

1755 

1756 - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"`

1757 

1758 The memory limit for the code interpreter container.

1759 

1760 - `:"1g"`

1761 

1762 - `:"4g"`

1763 

1764 - `:"16g"`

1765 

1766 - `:"64g"`

1767 

1768 - `network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist`

1769 

1770 Network access policy for the container.

1771 

1772 - `class ContainerNetworkPolicyDisabled`

1773 

1774 - `type: :disabled`

1775 

1776 Disable outbound network access. Always `disabled`.

1777 

1778 - `:disabled`

1779 

1780 - `class ContainerNetworkPolicyAllowlist`

1781 

1782 - `allowed_domains: Array[String]`

1783 

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

1785 

1786 - `type: :allowlist`

1787 

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

1789 

1790 - `:allowlist`

1791 

1792 - `domain_secrets: Array[ContainerNetworkPolicyDomainSecret]`

1793 

1794 Optional domain-scoped secrets for allowlisted domains.

1795 

1796 - `domain: String`

1797 

1798 The domain associated with the secret.

1799 

1800 - `name: String`

1801 

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

1803 

1804 - `value: String`

1805 

1806 The secret value to inject for the domain.

1807 

1808 - `type: :code_interpreter`

1809 

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

1811 

1812 - `:code_interpreter`

1813 

1814 - `class ImageGeneration`

1815 

1816 A tool that generates images using the GPT image models.

1817 

1818 - `type: :image_generation`

1819 

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

1821 

1822 - `:image_generation`

1823 

1824 - `action: :generate | :edit | :auto`

1825 

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

1827 

1828 - `:generate`

1829 

1830 - `:edit`

1831 

1832 - `:auto`

1833 

1834 - `background: :transparent | :opaque | :auto`

1835 

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

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

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

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

1840 automatically determine the best background for the image.

1841 

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

1843 transparent backgrounds. Requests with `background` set to

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

1845 `auto` instead.

1846 

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

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

1849 

1850 - `:transparent`

1851 

1852 - `:opaque`

1853 

1854 - `:auto`

1855 

1856 - `input_fidelity: :high | :low`

1857 

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

1859 

1860 - `:high`

1861 

1862 - `:low`

1863 

1864 - `input_image_mask: InputImageMask{ file_id, image_url}`

1865 

1866 Optional mask for inpainting. Contains `image_url`

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

1868 

1869 - `file_id: String`

1870 

1871 File ID for the mask image.

1872 

1873 - `image_url: String`

1874 

1875 Base64-encoded mask image.

1876 

1877 - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more`

1878 

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

1880 

1881 - `String = String`

1882 

1883 - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more`

1884 

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

1886 

1887 - `:"gpt-image-1"`

1888 

1889 - `:"gpt-image-1-mini"`

1890 

1891 - `:"gpt-image-2"`

1892 

1893 - `:"gpt-image-2-2026-04-21"`

1894 

1895 - `:"gpt-image-1.5"`

1896 

1897 - `:"chatgpt-image-latest"`

1898 

1899 - `moderation: :auto | :low`

1900 

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

1902 

1903 - `:auto`

1904 

1905 - `:low`

1906 

1907 - `output_compression: Integer`

1908 

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

1910 

1911 - `output_format: :png | :webp | :jpeg`

1912 

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

1914 `jpeg`. Default: `png`.

1915 

1916 - `:png`

1917 

1918 - `:webp`

1919 

1920 - `:jpeg`

1921 

1922 - `partial_images: Integer`

1923 

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

1925 

1926 - `quality: :low | :medium | :high | :auto`

1927 

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

1929 or `auto`. Default: `auto`.

1930 

1931 - `:low`

1932 

1933 - `:medium`

1934 

1935 - `:high`

1936 

1937 - `:auto`

1938 

1939 - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`

1940 

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

1942 

1943 - `String = String`

1944 

1945 - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`

1946 

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

1948 

1949 - `:"1024x1024"`

1950 

1951 - `:"1024x1536"`

1952 

1953 - `:"1536x1024"`

1954 

1955 - `:auto`

1956 

1957 - `class LocalShell`

1958 

1959 A tool that allows the model to execute shell commands in a local environment.

1960 

1961 - `type: :local_shell`

1962 

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

1964 

1965 - `:local_shell`

1966 

1967 - `class FunctionShellTool`

1968 

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

1970 

1971 - `type: :shell`

1972 

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

1974 

1975 - `:shell`

1976 

1977 - `environment: ContainerAuto | LocalEnvironment | ContainerReference`

1978 

1979 - `class ContainerAuto`

1980 

1981 - `type: :container_auto`

1982 

1983 Automatically creates a container for this request

1984 

1985 - `:container_auto`

1986 

1987 - `file_ids: Array[String]`

1988 

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

1990 

1991 - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"`

1992 

1993 The memory limit for the container.

1994 

1995 - `:"1g"`

1996