ruby/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`responses.retrieve(response_id, **kwargs) -> Response`

4 

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

6 

7Retrieves a model response with the given ID.

8 

9### Parameters

10 

11- `response_id: String`

12 

13- `include: Array[ResponseIncludable]`

14 

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

16 parameter for Response creation above for more information.

17 

18 - `:"file_search_call.results"`

19 

20 - `:"web_search_call.results"`

21 

22 - `:"web_search_call.action.sources"`

23 

24 - `:"message.input_image.image_url"`

25 

26 - `:"computer_call_output.output.image_url"`

27 

28 - `:"code_interpreter_call.outputs"`

29 

30 - `:"reasoning.encrypted_content"`

31 

32 - `:"message.output_text.logprobs"`

33 

34- `include_obfuscation: bool`

35 

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

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

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

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

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

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

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

43 

44- `starting_after: Integer`

45 

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

47 

48- `stream: bool`

49 

50 If set to true, the model response data will be streamed to the client

51 as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).

52 See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming)

53 for more information.

54 

55### Returns

56 

57- `class Response`

58 

59 - `id: String`

60 

61 Unique identifier for this Response.

62 

63 - `created_at: Float`

64 

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

66 

67 - `error: ResponseError`

68 

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

70 

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

72 

73 The error code for the response.

74 

75 - `:server_error`

76 

77 - `:rate_limit_exceeded`

78 

79 - `:invalid_prompt`

80 

81 - `:vector_store_timeout`

82 

83 - `:invalid_image`

84 

85 - `:invalid_image_format`

86 

87 - `:invalid_base64_image`

88 

89 - `:invalid_image_url`

90 

91 - `:image_too_large`

92 

93 - `:image_too_small`

94 

95 - `:image_parse_error`

96 

97 - `:image_content_policy_violation`

98 

99 - `:invalid_image_mode`

100 

101 - `:image_file_too_large`

102 

103 - `:unsupported_image_media_type`

104 

105 - `:empty_image_file`

106 

107 - `:failed_to_download_image`

108 

109 - `:image_file_not_found`

110 

111 - `message: String`

112 

113 A human-readable description of the error.

114 

115 - `incomplete_details: IncompleteDetails{ reason}`

116 

117 Details about why the response is incomplete.

118 

119 - `reason: :max_output_tokens | :content_filter`

120 

121 The reason why the response is incomplete.

122 

123 - `:max_output_tokens`

124 

125 - `:content_filter`

126 

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

128 

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

130 

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

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

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

134 

135 - `String = String`

136 

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

138 `developer` role.

139 

140 - `InputItemList = Array[ResponseInputItem]`

141 

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

143 different content types.

144 

145 - `class EasyInputMessage`

146 

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

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

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

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

151 interactions.

152 

153 - `content: String | ResponseInputMessageContentList`

154 

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

156 Can also contain previous assistant responses.

157 

158 - `String = String`

159 

160 A text input to the model.

161 

162 - `ResponseInputMessageContentList = Array[ResponseInputContent]`

163 

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

165 types.

166 

167 - `class ResponseInputText`

168 

169 A text input to the model.

170 

171 - `text: String`

172 

173 The text input to the model.

174 

175 - `type: :input_text`

176 

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

178 

179 - `:input_text`

180 

181 - `class ResponseInputImage`

182 

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

184 

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

186 

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

188 

189 - `:low`

190 

191 - `:high`

192 

193 - `:auto`

194 

195 - `:original`

196 

197 - `type: :input_image`

198 

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

200 

201 - `:input_image`

202 

203 - `file_id: String`

204 

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

206 

207 - `image_url: String`

208 

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

210 

211 - `class ResponseInputFile`

212 

213 A file input to the model.

214 

215 - `type: :input_file`

216 

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

218 

219 - `:input_file`

220 

221 - `detail: :low | :high`

222 

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

224 

225 - `:low`

226 

227 - `:high`

228 

229 - `file_data: String`

230 

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

232 

233 - `file_id: String`

234 

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

236 

237 - `file_url: String`

238 

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

240 

241 - `filename: String`

242 

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

244 

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

246 

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

248 `developer`.

249 

250 - `:user`

251 

252 - `:assistant`

253 

254 - `:system`

255 

256 - `:developer`

257 

258 - `phase: :commentary | :final_answer`

259 

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

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

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

263 

264 - `:commentary`

265 

266 - `:final_answer`

267 

268 - `type: :message`

269 

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

271 

272 - `:message`

273 

274 - `class Message`

275 

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

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

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

279 

280 - `content: ResponseInputMessageContentList`

281 

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

283 types.

284 

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

286 

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

288 

289 - `:user`

290 

291 - `:system`

292 

293 - `:developer`

294 

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

296 

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

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

299 

300 - `:in_progress`

301 

302 - `:completed`

303 

304 - `:incomplete`

305 

306 - `type: :message`

307 

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

309 

310 - `:message`

311 

312 - `class ResponseOutputMessage`

313 

314 An output message from the model.

315 

316 - `id: String`

317 

318 The unique ID of the output message.

319 

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

321 

322 The content of the output message.

323 

324 - `class ResponseOutputText`

325 

326 A text output from the model.

327 

328 - `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}]`

329 

330 The annotations of the text output.

331 

332 - `class FileCitation`

333 

334 A citation to a file.

335 

336 - `file_id: String`

337 

338 The ID of the file.

339 

340 - `filename: String`

341 

342 The filename of the file cited.

343 

344 - `index: Integer`

345 

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

347 

348 - `type: :file_citation`

349 

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

351 

352 - `:file_citation`

353 

354 - `class URLCitation`

355 

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

357 

358 - `end_index: Integer`

359 

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

361 

362 - `start_index: Integer`

363 

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

365 

366 - `title: String`

367 

368 The title of the web resource.

369 

370 - `type: :url_citation`

371 

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

373 

374 - `:url_citation`

375 

376 - `url: String`

377 

378 The URL of the web resource.

379 

380 - `class ContainerFileCitation`

381 

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

383 

384 - `container_id: String`

385 

386 The ID of the container file.

387 

388 - `end_index: Integer`

389 

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

391 

392 - `file_id: String`

393 

394 The ID of the file.

395 

396 - `filename: String`

397 

398 The filename of the container file cited.

399 

400 - `start_index: Integer`

401 

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

403 

404 - `type: :container_file_citation`

405 

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

407 

408 - `:container_file_citation`

409 

410 - `class FilePath`

411 

412 A path to a file.

413 

414 - `file_id: String`

415 

416 The ID of the file.

417 

418 - `index: Integer`

419 

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

421 

422 - `type: :file_path`

423 

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

425 

426 - `:file_path`

427 

428 - `text: String`

429 

430 The text output from the model.

431 

432 - `type: :output_text`

433 

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

435 

436 - `:output_text`

437 

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

439 

440 - `token: String`

441 

442 - `bytes: Array[Integer]`

443 

444 - `logprob: Float`

445 

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

447 

448 - `token: String`

449 

450 - `bytes: Array[Integer]`

451 

452 - `logprob: Float`

453 

454 - `class ResponseOutputRefusal`

455 

456 A refusal from the model.

457 

458 - `refusal: String`

459 

460 The refusal explanation from the model.

461 

462 - `type: :refusal`

463 

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

465 

466 - `:refusal`

467 

468 - `role: :assistant`

469 

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

471 

472 - `:assistant`

473 

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

475 

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

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

478 

479 - `:in_progress`

480 

481 - `:completed`

482 

483 - `:incomplete`

484 

485 - `type: :message`

486 

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

488 

489 - `:message`

490 

491 - `phase: :commentary | :final_answer`

492 

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

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

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

496 

497 - `:commentary`

498 

499 - `:final_answer`

500 

501 - `class ResponseFileSearchToolCall`

502 

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

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

505 

506 - `id: String`

507 

508 The unique ID of the file search tool call.

509 

510 - `queries: Array[String]`

511 

512 The queries used to search for files.

513 

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

515 

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

517 `searching`, `incomplete` or `failed`,

518 

519 - `:in_progress`

520 

521 - `:searching`

522 

523 - `:completed`

524 

525 - `:incomplete`

526 

527 - `:failed`

528 

529 - `type: :file_search_call`

530 

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

532 

533 - `:file_search_call`

534 

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

536 

537 The results of the file search tool call.

538 

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

540 

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

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

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

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

545 length of 512 characters, booleans, or numbers.

546 

547 - `String = String`

548 

549 - `Float = Float`

550 

551 - `UnionMember2 = bool`

552 

553 - `file_id: String`

554 

555 The unique ID of the file.

556 

557 - `filename: String`

558 

559 The name of the file.

560 

561 - `score: Float`

562 

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

564 

565 - `text: String`

566 

567 The text that was retrieved from the file.

568 

569 - `class ResponseComputerToolCall`

570 

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

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

573 

574 - `id: String`

575 

576 The unique ID of the computer call.

577 

578 - `call_id: String`

579 

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

581 

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

583 

584 The pending safety checks for the computer call.

585 

586 - `id: String`

587 

588 The ID of the pending safety check.

589 

590 - `code: String`

591 

592 The type of the pending safety check.

593 

594 - `message: String`

595 

596 Details about the pending safety check.

597 

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

599 

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

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

602 

603 - `:in_progress`

604 

605 - `:completed`

606 

607 - `:incomplete`

608 

609 - `type: :computer_call`

610 

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

612 

613 - `:computer_call`

614 

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

616 

617 A click action.

618 

619 - `class Click`

620 

621 A click action.

622 

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

624 

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

626 

627 - `:left`

628 

629 - `:right`

630 

631 - `:wheel`

632 

633 - `:back`

634 

635 - `:forward`

636 

637 - `type: :click`

638 

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

640 

641 - `:click`

642 

643 - `x: Integer`

644 

645 The x-coordinate where the click occurred.

646 

647 - `y_: Integer`

648 

649 The y-coordinate where the click occurred.

650 

651 - `keys: Array[String]`

652 

653 The keys being held while clicking.

654 

655 - `class DoubleClick`

656 

657 A double click action.

658 

659 - `keys: Array[String]`

660 

661 The keys being held while double-clicking.

662 

663 - `type: :double_click`

664 

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

666 

667 - `:double_click`

668 

669 - `x: Integer`

670 

671 The x-coordinate where the double click occurred.

672 

673 - `y_: Integer`

674 

675 The y-coordinate where the double click occurred.

676 

677 - `class Drag`

678 

679 A drag action.

680 

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

682 

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

684 

685 ```

686 [

687 { x: 100, y: 200 },

688 { x: 200, y: 300 }

689 ]

690 ```

691 

692 - `x: Integer`

693 

694 The x-coordinate.

695 

696 - `y_: Integer`

697 

698 The y-coordinate.

699 

700 - `type: :drag`

701 

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

703 

704 - `:drag`

705 

706 - `keys: Array[String]`

707 

708 The keys being held while dragging the mouse.

709 

710 - `class Keypress`

711 

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

713 

714 - `keys: Array[String]`

715 

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

717 

718 - `type: :keypress`

719 

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

721 

722 - `:keypress`

723 

724 - `class Move`

725 

726 A mouse move action.

727 

728 - `type: :move`

729 

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

731 

732 - `:move`

733 

734 - `x: Integer`

735 

736 The x-coordinate to move to.

737 

738 - `y_: Integer`

739 

740 The y-coordinate to move to.

741 

742 - `keys: Array[String]`

743 

744 The keys being held while moving the mouse.

745 

746 - `class Screenshot`

747 

748 A screenshot action.

749 

750 - `type: :screenshot`

751 

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

753 

754 - `:screenshot`

755 

756 - `class Scroll`

757 

758 A scroll action.

759 

760 - `scroll_x: Integer`

761 

762 The horizontal scroll distance.

763 

764 - `scroll_y: Integer`

765 

766 The vertical scroll distance.

767 

768 - `type: :scroll`

769 

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

771 

772 - `:scroll`

773 

774 - `x: Integer`

775 

776 The x-coordinate where the scroll occurred.

777 

778 - `y_: Integer`

779 

780 The y-coordinate where the scroll occurred.

781 

782 - `keys: Array[String]`

783 

784 The keys being held while scrolling.

785 

786 - `class Type`

787 

788 An action to type in text.

789 

790 - `text: String`

791 

792 The text to type.

793 

794 - `type: :type`

795 

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

797 

798 - `:type`

799 

800 - `class Wait`

801 

802 A wait action.

803 

804 - `type: :wait`

805 

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

807 

808 - `:wait`

809 

810 - `actions: ComputerActionList`

811 

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

813 `type` discriminator and action-specific fields.

814 

815 - `class Click`

816 

817 A click action.

818 

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

820 

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

822 

823 - `:left`

824 

825 - `:right`

826 

827 - `:wheel`

828 

829 - `:back`

830 

831 - `:forward`

832 

833 - `type: :click`

834 

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

836 

837 - `:click`

838 

839 - `x: Integer`

840 

841 The x-coordinate where the click occurred.

842 

843 - `y_: Integer`

844 

845 The y-coordinate where the click occurred.

846 

847 - `keys: Array[String]`

848 

849 The keys being held while clicking.

850 

851 - `class DoubleClick`

852 

853 A double click action.

854 

855 - `keys: Array[String]`

856 

857 The keys being held while double-clicking.

858 

859 - `type: :double_click`

860 

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

862 

863 - `:double_click`

864 

865 - `x: Integer`

866 

867 The x-coordinate where the double click occurred.

868 

869 - `y_: Integer`

870 

871 The y-coordinate where the double click occurred.

872 

873 - `class Drag`

874 

875 A drag action.

876 

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

878 

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

880 

881 ```

882 [

883 { x: 100, y: 200 },

884 { x: 200, y: 300 }

885 ]

886 ```

887 

888 - `x: Integer`

889 

890 The x-coordinate.

891 

892 - `y_: Integer`

893 

894 The y-coordinate.

895 

896 - `type: :drag`

897 

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

899 

900 - `:drag`

901 

902 - `keys: Array[String]`

903 

904 The keys being held while dragging the mouse.

905 

906 - `class Keypress`

907 

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

909 

910 - `keys: Array[String]`

911 

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

913 

914 - `type: :keypress`

915 

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

917 

918 - `:keypress`

919 

920 - `class Move`

921 

922 A mouse move action.

923 

924 - `type: :move`

925 

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

927 

928 - `:move`

929 

930 - `x: Integer`

931 

932 The x-coordinate to move to.

933 

934 - `y_: Integer`

935 

936 The y-coordinate to move to.

937 

938 - `keys: Array[String]`

939 

940 The keys being held while moving the mouse.

941 

942 - `class Screenshot`

943 

944 A screenshot action.

945 

946 - `type: :screenshot`

947 

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

949 

950 - `:screenshot`

951 

952 - `class Scroll`

953 

954 A scroll action.

955 

956 - `scroll_x: Integer`

957 

958 The horizontal scroll distance.

959 

960 - `scroll_y: Integer`

961 

962 The vertical scroll distance.

963 

964 - `type: :scroll`

965 

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

967 

968 - `:scroll`

969 

970 - `x: Integer`

971 

972 The x-coordinate where the scroll occurred.

973 

974 - `y_: Integer`

975 

976 The y-coordinate where the scroll occurred.

977 

978 - `keys: Array[String]`

979 

980 The keys being held while scrolling.

981 

982 - `class Type`

983 

984 An action to type in text.

985 

986 - `text: String`

987 

988 The text to type.

989 

990 - `type: :type`

991 

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

993 

994 - `:type`

995 

996 - `class Wait`

997 

998 A wait action.

999 

1000 - `type: :wait`

1001 

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

1003 

1004 - `:wait`

1005 

1006 - `class ComputerCallOutput`

1007 

1008 The output of a computer tool call.

1009 

1010 - `call_id: String`

1011 

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

1013 

1014 - `output: ResponseComputerToolCallOutputScreenshot`

1015 

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

1017 

1018 - `type: :computer_screenshot`

1019 

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

1021 always set to `computer_screenshot`.

1022 

1023 - `:computer_screenshot`

1024 

1025 - `file_id: String`

1026 

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

1028 

1029 - `image_url: String`

1030 

1031 The URL of the screenshot image.

1032 

1033 - `type: :computer_call_output`

1034 

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

1036 

1037 - `:computer_call_output`

1038 

1039 - `id: String`

1040 

1041 The ID of the computer tool call output.

1042 

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

1044 

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

1046 

1047 - `id: String`

1048 

1049 The ID of the pending safety check.

1050 

1051 - `code: String`

1052 

1053 The type of the pending safety check.

1054 

1055 - `message: String`

1056 

1057 Details about the pending safety check.

1058 

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

1060 

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

1062 

1063 - `:in_progress`

1064 

1065 - `:completed`

1066 

1067 - `:incomplete`

1068 

1069 - `class ResponseFunctionWebSearch`

1070 

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

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

1073 

1074 - `id: String`

1075 

1076 The unique ID of the web search tool call.

1077 

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

1079 

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

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

1082 

1083 - `class Search`

1084 

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

1086 

1087 - `query: String`

1088 

1089 [DEPRECATED] The search query.

1090 

1091 - `type: :search`

1092 

1093 The action type.

1094 

1095 - `:search`

1096 

1097 - `queries: Array[String]`

1098 

1099 The search queries.

1100 

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

1102 

1103 The sources used in the search.

1104 

1105 - `type: :url`

1106 

1107 The type of source. Always `url`.

1108 

1109 - `:url`

1110 

1111 - `url: String`

1112 

1113 The URL of the source.

1114 

1115 - `class OpenPage`

1116 

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

1118 

1119 - `type: :open_page`

1120 

1121 The action type.

1122 

1123 - `:open_page`

1124 

1125 - `url: String`

1126 

1127 The URL opened by the model.

1128 

1129 - `class FindInPage`

1130 

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

1132 

1133 - `pattern: String`

1134 

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

1136 

1137 - `type: :find_in_page`

1138 

1139 The action type.

1140 

1141 - `:find_in_page`

1142 

1143 - `url: String`

1144 

1145 The URL of the page searched for the pattern.

1146 

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

1148 

1149 The status of the web search tool call.

1150 

1151 - `:in_progress`

1152 

1153 - `:searching`

1154 

1155 - `:completed`

1156 

1157 - `:failed`

1158 

1159 - `type: :web_search_call`

1160 

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

1162 

1163 - `:web_search_call`

1164 

1165 - `class ResponseFunctionToolCall`

1166 

1167 A tool call to run a function. See the

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

1169 

1170 - `arguments: String`

1171 

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

1173 

1174 - `call_id: String`

1175 

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

1177 

1178 - `name: String`

1179 

1180 The name of the function to run.

1181 

1182 - `type: :function_call`

1183 

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

1185 

1186 - `:function_call`

1187 

1188 - `id: String`

1189 

1190 The unique ID of the function tool call.

1191 

1192 - `namespace: String`

1193 

1194 The namespace of the function to run.

1195 

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

1197 

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

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

1200 

1201 - `:in_progress`

1202 

1203 - `:completed`

1204 

1205 - `:incomplete`

1206 

1207 - `class FunctionCallOutput`

1208 

1209 The output of a function tool call.

1210 

1211 - `call_id: String`

1212 

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

1214 

1215 - `output: String | ResponseFunctionCallOutputItemList`

1216 

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

1218 

1219 - `String = String`

1220 

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

1222 

1223 - `ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]`

1224 

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

1226 

1227 - `class ResponseInputTextContent`

1228 

1229 A text input to the model.

1230 

1231 - `text: String`

1232 

1233 The text input to the model.

1234 

1235 - `type: :input_text`

1236 

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

1238 

1239 - `:input_text`

1240 

1241 - `class ResponseInputImageContent`

1242 

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

1244 

1245 - `type: :input_image`

1246 

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

1248 

1249 - `:input_image`

1250 

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

1252 

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

1254 

1255 - `:low`

1256 

1257 - `:high`

1258 

1259 - `:auto`

1260 

1261 - `:original`

1262 

1263 - `file_id: String`

1264 

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

1266 

1267 - `image_url: String`

1268 

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

1270 

1271 - `class ResponseInputFileContent`

1272 

1273 A file input to the model.

1274 

1275 - `type: :input_file`

1276 

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

1278 

1279 - `:input_file`

1280 

1281 - `detail: :low | :high`

1282 

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

1284 

1285 - `:low`

1286 

1287 - `:high`

1288 

1289 - `file_data: String`

1290 

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

1292 

1293 - `file_id: String`

1294 

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

1296 

1297 - `file_url: String`

1298 

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

1300 

1301 - `filename: String`

1302 

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

1304 

1305 - `type: :function_call_output`

1306 

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

1308 

1309 - `:function_call_output`

1310 

1311 - `id: String`

1312 

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

1314 

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

1316 

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

1318 

1319 - `:in_progress`

1320 

1321 - `:completed`

1322 

1323 - `:incomplete`

1324 

1325 - `class ToolSearchCall`

1326 

1327 - `arguments: untyped`

1328 

1329 The arguments supplied to the tool search call.

1330 

1331 - `type: :tool_search_call`

1332 

1333 The item type. Always `tool_search_call`.

1334 

1335 - `:tool_search_call`

1336 

1337 - `id: String`

1338 

1339 The unique ID of this tool search call.

1340 

1341 - `call_id: String`

1342 

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

1344 

1345 - `execution: :server | :client`

1346 

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

1348 

1349 - `:server`

1350 

1351 - `:client`

1352 

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

1354 

1355 The status of the tool search call.

1356 

1357 - `:in_progress`

1358 

1359 - `:completed`

1360 

1361 - `:incomplete`

1362 

1363 - `class ResponseToolSearchOutputItemParam`

1364 

1365 - `tools: Array[Tool]`

1366 

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

1368 

1369 - `class FunctionTool`

1370 

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

1372 

1373 - `name: String`

1374 

1375 The name of the function to call.

1376 

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

1378 

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

1380 

1381 - `strict: bool`

1382 

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

1384 

1385 - `type: :function`

1386 

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

1388 

1389 - `:function`

1390 

1391 - `defer_loading: bool`

1392 

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

1394 

1395 - `description: String`

1396 

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

1398 

1399 - `class FileSearchTool`

1400 

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

1402 

1403 - `type: :file_search`

1404 

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

1406 

1407 - `:file_search`

1408 

1409 - `vector_store_ids: Array[String]`

1410 

1411 The IDs of the vector stores to search.

1412 

1413 - `filters: ComparisonFilter | CompoundFilter`

1414 

1415 A filter to apply.

1416 

1417 - `class ComparisonFilter`

1418 

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

1420 

1421 - `key: String`

1422 

1423 The key to compare against the value.

1424 

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

1426 

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

1428 

1429 - `eq`: equals

1430 - `ne`: not equal

1431 - `gt`: greater than

1432 - `gte`: greater than or equal

1433 - `lt`: less than

1434 - `lte`: less than or equal

1435 - `in`: in

1436 - `nin`: not in

1437 

1438 - `:eq`

1439 

1440 - `:ne`

1441 

1442 - `:gt`

1443 

1444 - `:gte`

1445 

1446 - `:lt`

1447 

1448 - `:lte`

1449 

1450 - `:in`

1451 

1452 - `:nin`

1453 

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

1455 

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

1457 

1458 - `String = String`

1459 

1460 - `Float = Float`

1461 

1462 - `UnionMember2 = bool`

1463 

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

1465 

1466 - `String = String`

1467 

1468 - `Float = Float`

1469 

1470 - `class CompoundFilter`

1471 

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

1473 

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

1475 

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

1477 

1478 - `class ComparisonFilter`

1479 

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

1481 

1482 - `UnionMember1 = untyped`

1483 

1484 - `type: :and | :or`

1485 

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

1487 

1488 - `:and`

1489 

1490 - `:or`

1491 

1492 - `max_num_results: Integer`

1493 

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

1495 

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

1497 

1498 Ranking options for search.

1499 

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

1501 

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

1503 

1504 - `embedding_weight: Float`

1505 

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

1507 

1508 - `text_weight: Float`

1509 

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

1511 

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

1513 

1514 The ranker to use for the file search.

1515 

1516 - `:auto`

1517 

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

1519 

1520 - `score_threshold: Float`

1521 

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

1523 

1524 - `class ComputerTool`

1525 

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

1527 

1528 - `type: :computer`

1529 

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

1531 

1532 - `:computer`

1533 

1534 - `class ComputerUsePreviewTool`

1535 

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

1537 

1538 - `display_height: Integer`

1539 

1540 The height of the computer display.

1541 

1542 - `display_width: Integer`

1543 

1544 The width of the computer display.

1545 

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

1547 

1548 The type of computer environment to control.

1549 

1550 - `:windows`

1551 

1552 - `:mac`

1553 

1554 - `:linux`

1555 

1556 - `:ubuntu`

1557 

1558 - `:browser`

1559 

1560 - `type: :computer_use_preview`

1561 

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

1563 

1564 - `:computer_use_preview`

1565 

1566 - `class WebSearchTool`

1567 

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

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

1570 

1571 - `type: :web_search | :web_search_2025_08_26`

1572 

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

1574 

1575 - `:web_search`

1576 

1577 - `:web_search_2025_08_26`

1578 

1579 - `filters: Filters{ allowed_domains}`

1580 

1581 Filters for the search.

1582 

1583 - `allowed_domains: Array[String]`

1584 

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

1586 Subdomains of the provided domains are allowed as well.

1587 

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

1589 

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

1591 

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

1593 

1594 - `:low`

1595 

1596 - `:medium`

1597 

1598 - `:high`

1599 

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

1601 

1602 The approximate location of the user.

1603 

1604 - `city: String`

1605 

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

1607 

1608 - `country: String`

1609 

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

1611 

1612 - `region: String`

1613 

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

1615 

1616 - `timezone: String`

1617 

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

1619 

1620 - `type: :approximate`

1621 

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

1623 

1624 - `:approximate`

1625 

1626 - `class Mcp`

1627 

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

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

1630 

1631 - `server_label: String`

1632 

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

1634 

1635 - `type: :mcp`

1636 

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

1638 

1639 - `:mcp`

1640 

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

1642 

1643 List of allowed tool names or a filter object.

1644 

1645 - `McpAllowedTools = Array[String]`

1646 

1647 A string array of allowed tool names

1648 

1649 - `class McpToolFilter`

1650 

1651 A filter object to specify which tools are allowed.

1652 

1653 - `read_only: bool`

1654 

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

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

1657 it will match this filter.

1658 

1659 - `tool_names: Array[String]`

1660 

1661 List of allowed tool names.

1662 

1663 - `authorization: String`

1664 

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

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

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

1668 

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

1670 

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

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

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

1674 

1675 Currently supported `connector_id` values are:

1676 

1677 - Dropbox: `connector_dropbox`

1678 - Gmail: `connector_gmail`

1679 - Google Calendar: `connector_googlecalendar`

1680 - Google Drive: `connector_googledrive`

1681 - Microsoft Teams: `connector_microsoftteams`

1682 - Outlook Calendar: `connector_outlookcalendar`

1683 - Outlook Email: `connector_outlookemail`

1684 - SharePoint: `connector_sharepoint`

1685 

1686 - `:connector_dropbox`

1687 

1688 - `:connector_gmail`

1689 

1690 - `:connector_googlecalendar`

1691 

1692 - `:connector_googledrive`

1693 

1694 - `:connector_microsoftteams`

1695 

1696 - `:connector_outlookcalendar`

1697 

1698 - `:connector_outlookemail`

1699 

1700 - `:connector_sharepoint`

1701 

1702 - `defer_loading: bool`

1703 

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

1705 

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

1707 

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

1709 or other purposes.

1710 

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

1712 

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

1714 

1715 - `class McpToolApprovalFilter`

1716 

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

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

1719 that require approval.

1720 

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

1722 

1723 A filter object to specify which tools are allowed.

1724 

1725 - `read_only: bool`

1726 

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

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

1729 it will match this filter.

1730 

1731 - `tool_names: Array[String]`

1732 

1733 List of allowed tool names.

1734 

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

1736 

1737 A filter object to specify which tools are allowed.

1738 

1739 - `read_only: bool`

1740 

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

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

1743 it will match this filter.

1744 

1745 - `tool_names: Array[String]`

1746 

1747 List of allowed tool names.

1748 

1749 - `McpToolApprovalSetting = :always | :never`

1750 

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

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

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

1754 

1755 - `:always`

1756 

1757 - `:never`

1758 

1759 - `server_description: String`

1760 

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

1762 

1763 - `server_url: String`

1764 

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

1766 provided.

1767 

1768 - `class CodeInterpreter`

1769 

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

1771 

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

1773 

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

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

1776 optional `memory_limit` setting.

1777 

1778 - `String = String`

1779 

1780 The container ID.

1781 

1782 - `class CodeInterpreterToolAuto`

1783 

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

1785 

1786 - `type: :auto`

1787 

1788 Always `auto`.

1789 

1790 - `:auto`

1791 

1792 - `file_ids: Array[String]`

1793 

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

1795 

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

1797 

1798 The memory limit for the code interpreter container.

1799 

1800 - `:"1g"`

1801 

1802 - `:"4g"`

1803 

1804 - `:"16g"`

1805 

1806 - `:"64g"`

1807 

1808 - `network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist`

1809 

1810 Network access policy for the container.

1811 

1812 - `class ContainerNetworkPolicyDisabled`

1813 

1814 - `type: :disabled`

1815 

1816 Disable outbound network access. Always `disabled`.

1817 

1818 - `:disabled`

1819 

1820 - `class ContainerNetworkPolicyAllowlist`

1821 

1822 - `allowed_domains: Array[String]`

1823 

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

1825 

1826 - `type: :allowlist`

1827 

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

1829 

1830 - `:allowlist`

1831 

1832 - `domain_secrets: Array[ContainerNetworkPolicyDomainSecret]`

1833 

1834 Optional domain-scoped secrets for allowlisted domains.

1835 

1836 - `domain: String`

1837 

1838 The domain associated with the secret.

1839 

1840 - `name: String`

1841 

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

1843 

1844 - `value: String`

1845 

1846 The secret value to inject for the domain.

1847 

1848 - `type: :code_interpreter`

1849 

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

1851 

1852 - `:code_interpreter`

1853 

1854 - `class ImageGeneration`

1855 

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

1857 

1858 - `type: :image_generation`

1859 

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

1861 

1862 - `:image_generation`

1863 

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

1865 

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

1867 

1868 - `:generate`

1869 

1870 - `:edit`

1871 

1872 - `:auto`

1873 

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

1875 

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

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

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

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

1880 automatically determine the best background for the image.

1881 

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

1883 transparent backgrounds. Requests with `background` set to

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

1885 `auto` instead.

1886 

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

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

1889 

1890 - `:transparent`

1891 

1892 - `:opaque`

1893 

1894 - `:auto`

1895 

1896 - `input_fidelity: :high | :low`

1897 

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

1899 

1900 - `:high`

1901 

1902 - `:low`

1903 

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

1905 

1906 Optional mask for inpainting. Contains `image_url`

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

1908 

1909 - `file_id: String`

1910 

1911 File ID for the mask image.

1912 

1913 - `image_url: String`

1914 

1915 Base64-encoded mask image.

1916 

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

1918 

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

1920 

1921 - `String = String`

1922 

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

1924 

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

1926 

1927 - `:"gpt-image-1"`

1928 

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

1930 

1931 - `:"gpt-image-2"`

1932 

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

1934 

1935 - `:"gpt-image-1.5"`

1936 

1937 - `:"chatgpt-image-latest"`

1938 

1939 - `moderation: :auto | :low`

1940 

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

1942 

1943 - `:auto`

1944 

1945 - `:low`

1946 

1947 - `output_compression: Integer`

1948 

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

1950 

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

1952 

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

1954 `jpeg`. Default: `png`.

1955 

1956 - `:png`

1957 

1958 - `:webp`

1959 

1960 - `:jpeg`

1961 

1962 - `partial_images: Integer`

1963 

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

1965 

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

1967 

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

1969 or `auto`. Default: `auto`.

1970 

1971 - `:low`

1972 

1973 - `:medium`

1974 

1975 - `:high`

1976 

1977 - `:auto`

1978 

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

1980 

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

1982 

1983 - `String = String`

1984 

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

1986 

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

1988 

1989 - `:"1024x1024"`

1990 

1991 - `:"1024x1536"`

1992 

1993 - `:"1536x1024"`

1994 

1995 - `:auto`

1996