ruby/resources/conversations/methods/create/index.md 2026-09-16 22:58 UTC to 2026-09-18 22:59 UTC

1## Create a conversation

2 

3`conversations.create(**kwargs) -> Conversation`

4 

5**post** `/conversations`

6 

7Create a conversation.

8 

9### Parameters

10 

11- `items: Array[ResponseInputItem]`

12 

13 Initial items to include in the conversation context. You may add up to 20 items at a time.

14 

15 - `class EasyInputMessage`

16 

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

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

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

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

21 interactions.

22 

23 - `content: String | ResponseInputMessageContentList`

24 

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

26 Can also contain previous assistant responses.

27 

28 - `String = String`

29 

30 A text input to the model.

31 

32 - `ResponseInputMessageContentList = Array[ResponseInputContent]`

33 

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

35 types.

36 

37 - `class ResponseInputText`

38 

39 A text input to the model.

40 

41 - `text: String`

42 

43 The text input to the model.

44 

45 - `type: :input_text`

46 

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

48 

49 - `:input_text`

50 

51 - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}`

52 

53 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

54 

55 - `mode: :explicit`

56 

57 The breakpoint mode. Always `explicit`.

58 

59 - `:explicit`

60 

61 - `class ResponseInputImage`

62 

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

64 

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

66 

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

68 

69 - `:low`

70 

71 - `:high`

72 

73 - `:auto`

74 

75 - `:original`

76 

77 - `type: :input_image`

78 

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

80 

81 - `:input_image`

82 

83 - `file_id: String`

84 

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

86 

87 - `image_url: String`

88 

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

90 

91 - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}`

92 

93 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

94 

95 - `mode: :explicit`

96 

97 The breakpoint mode. Always `explicit`.

98 

99 - `:explicit`

100 

101 - `class ResponseInputFile`

102 

103 A file input to the model.

104 

105 - `type: :input_file`

106 

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

108 

109 - `:input_file`

110 

111 - `detail: :auto | :low | :high`

112 

113 The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`.

114 

115 - `:auto`

116 

117 - `:low`

118 

119 - `:high`

120 

121 - `file_data: String`

122 

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

124 

125 - `file_id: String`

126 

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

128 

129 - `file_url: String`

130 

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

132 

133 - `filename: String`

134 

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

136 

137 - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}`

138 

139 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

140 

141 - `mode: :explicit`

142 

143 The breakpoint mode. Always `explicit`.

144 

145 - `:explicit`

146 

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

148 

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

150 `developer`.

151 

152 - `:user`

153 

154 - `:assistant`

155 

156 - `:system`

157 

158 - `:developer`

159 

160 - `phase: :commentary | :final_answer`

161 

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

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

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

165 

166 - `:commentary`

167 

168 - `:final_answer`

169 

170 - `type: :message`

171 

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

173 

174 - `:message`

175 

176 - `class Message`

177 

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

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

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

181 

182 - `content: ResponseInputMessageContentList`

183 

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

185 types.

186 

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

188 

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

190 

191 - `:user`

192 

193 - `:system`

194 

195 - `:developer`

196 

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

198 

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

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

201 

202 - `:in_progress`

203 

204 - `:completed`

205 

206 - `:incomplete`

207 

208 - `type: :message`

209 

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

211 

212 - `:message`

213 

214 - `class ResponseOutputMessage`

215 

216 An output message from the model.

217 

218 - `id: String`

219 

220 The unique ID of the output message.

221 

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

223 

224 The content of the output message.

225 

226 - `class ResponseOutputText`

227 

228 A text output from the model.

229 

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

231 

232 The annotations of the text output.

233 

234 - `class FileCitation`

235 

236 A citation to a file.

237 

238 - `file_id: String`

239 

240 The ID of the file.

241 

242 - `filename: String`

243 

244 The filename of the file cited.

245 

246 - `index: Integer`

247 

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

249 

250 - `type: :file_citation`

251 

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

253 

254 - `:file_citation`

255 

256 - `class URLCitation`

257 

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

259 

260 - `end_index: Integer`

261 

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

263 

264 - `start_index: Integer`

265 

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

267 

268 - `title: String`

269 

270 The title of the web resource.

271 

272 - `type: :url_citation`

273 

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

275 

276 - `:url_citation`

277 

278 - `url: String`

279 

280 The URL of the web resource.

281 

282 - `class ContainerFileCitation`

283 

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

285 

286 - `container_id: String`

287 

288 The ID of the container file.

289 

290 - `end_index: Integer`

291 

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

293 

294 - `file_id: String`

295 

296 The ID of the file.

297 

298 - `filename: String`

299 

300 The filename of the container file cited.

301 

302 - `start_index: Integer`

303 

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

305 

306 - `type: :container_file_citation`

307 

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

309 

310 - `:container_file_citation`

311 

312 - `class FilePath`

313 

314 A path to a file.

315 

316 - `file_id: String`

317 

318 The ID of the file.

319 

320 - `index: Integer`

321 

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

323 

324 - `type: :file_path`

325 

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

327 

328 - `:file_path`

329 

330 - `text: String`

331 

332 The text output from the model.

333 

334 - `type: :output_text`

335 

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

337 

338 - `:output_text`

339 

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

341 

342 - `token: String`

343 

344 - `bytes: Array[Integer]`

345 

346 - `logprob: Float`

347 

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

349 

350 - `token: String`

351 

352 - `bytes: Array[Integer]`

353 

354 - `logprob: Float`

355 

356 - `class ResponseOutputRefusal`

357 

358 A refusal from the model.

359 

360 - `refusal: String`

361 

362 The refusal explanation from the model.

363 

364 - `type: :refusal`

365 

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

367 

368 - `:refusal`

369 

370 - `role: :assistant`

371 

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

373 

374 - `:assistant`

375 

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

377 

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

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

380 

381 - `:in_progress`

382 

383 - `:completed`

384 

385 - `:incomplete`

386 

387 - `type: :message`

388 

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

390 

391 - `:message`

392 

393 - `phase: :commentary | :final_answer`

394 

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

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

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

398 

399 - `:commentary`

400 

401 - `:final_answer`

402 

403 - `class ResponseFileSearchToolCall`

404 

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

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

407 

408 - `id: String`

409 

410 The unique ID of the file search tool call.

411 

412 - `queries: Array[String]`

413 

414 The queries used to search for files.

415 

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

417 

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

419 `searching`, `incomplete` or `failed`,

420 

421 - `:in_progress`

422 

423 - `:searching`

424 

425 - `:completed`

426 

427 - `:incomplete`

428 

429 - `:failed`

430 

431 - `type: :file_search_call`

432 

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

434 

435 - `:file_search_call`

436 

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

438 

439 The results of the file search tool call.

440 

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

442 

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

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

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

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

447 length of 512 characters, booleans, or numbers.

448 

449 - `String = String`

450 

451 - `Float = Float`

452 

453 - `UnionMember2 = bool`

454 

455 - `file_id: String`

456 

457 The unique ID of the file.

458 

459 - `filename: String`

460 

461 The name of the file.

462 

463 - `score: Float`

464 

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

466 

467 - `text: String`

468 

469 The text that was retrieved from the file.

470 

471 - `class ResponseComputerToolCall`

472 

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

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

475 

476 - `id: String`

477 

478 The unique ID of the computer call.

479 

480 - `call_id: String`

481 

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

483 

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

485 

486 The pending safety checks for the computer call.

487 

488 - `id: String`

489 

490 The ID of the pending safety check.

491 

492 - `code: String`

493 

494 The type of the pending safety check.

495 

496 - `message: String`

497 

498 Details about the pending safety check.

499 

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

501 

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

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

504 

505 - `:in_progress`

506 

507 - `:completed`

508 

509 - `:incomplete`

510 

511 - `type: :computer_call`

512 

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

514 

515 - `:computer_call`

516 

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

518 

519 A click action.

520 

521 - `class Click`

522 

523 A click action.

524 

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

526 

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

528 

529 - `:left`

530 

531 - `:right`

532 

533 - `:wheel`

534 

535 - `:back`

536 

537 - `:forward`

538 

539 - `type: :click`

540 

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

542 

543 - `:click`

544 

545 - `x: Integer`

546 

547 The x-coordinate where the click occurred.

548 

549 - `y_: Integer`

550 

551 The y-coordinate where the click occurred.

552 

553 - `keys: Array[String]`

554 

555 The keys being held while clicking.

556 

557 - `class DoubleClick`

558 

559 A double click action.

560 

561 - `keys: Array[String]`

562 

563 The keys being held while double-clicking.

564 

565 - `type: :double_click`

566 

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

568 

569 - `:double_click`

570 

571 - `x: Integer`

572 

573 The x-coordinate where the double click occurred.

574 

575 - `y_: Integer`

576 

577 The y-coordinate where the double click occurred.

578 

579 - `class Drag`

580 

581 A drag action.

582 

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

584 

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

586 

587 ```

588 [

589 { x: 100, y: 200 },

590 { x: 200, y: 300 }

591 ]

592 ```

593 

594 - `x: Integer`

595 

596 The x-coordinate.

597 

598 - `y_: Integer`

599 

600 The y-coordinate.

601 

602 - `type: :drag`

603 

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

605 

606 - `:drag`

607 

608 - `keys: Array[String]`

609 

610 The keys being held while dragging the mouse.

611 

612 - `class Keypress`

613 

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

615 

616 - `keys: Array[String]`

617 

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

619 

620 - `type: :keypress`

621 

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

623 

624 - `:keypress`

625 

626 - `class Move`

627 

628 A mouse move action.

629 

630 - `type: :move`

631 

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

633 

634 - `:move`

635 

636 - `x: Integer`

637 

638 The x-coordinate to move to.

639 

640 - `y_: Integer`

641 

642 The y-coordinate to move to.

643 

644 - `keys: Array[String]`

645 

646 The keys being held while moving the mouse.

647 

648 - `class Screenshot`

649 

650 A screenshot action.

651 

652 - `type: :screenshot`

653 

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

655 

656 - `:screenshot`

657 

658 - `class Scroll`

659 

660 A scroll action.

661 

662 - `scroll_x: Integer`

663 

664 The horizontal scroll distance.

665 

666 - `scroll_y: Integer`

667 

668 The vertical scroll distance.

669 

670 - `type: :scroll`

671 

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

673 

674 - `:scroll`

675 

676 - `x: Integer`

677 

678 The x-coordinate where the scroll occurred.

679 

680 - `y_: Integer`

681 

682 The y-coordinate where the scroll occurred.

683 

684 - `keys: Array[String]`

685 

686 The keys being held while scrolling.

687 

688 - `class Type`

689 

690 An action to type in text.

691 

692 - `text: String`

693 

694 The text to type.

695 

696 - `type: :type`

697 

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

699 

700 - `:type`

701 

702 - `class Wait`

703 

704 A wait action.

705 

706 - `type: :wait`

707 

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

709 

710 - `:wait`

711 

712 - `actions: ComputerActionList`

713 

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

715 `type` discriminator and action-specific fields.

716 

717 - `class Click`

718 

719 A click action.

720 

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

722 

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

724 

725 - `:left`

726 

727 - `:right`

728 

729 - `:wheel`

730 

731 - `:back`

732 

733 - `:forward`

734 

735 - `type: :click`

736 

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

738 

739 - `:click`

740 

741 - `x: Integer`

742 

743 The x-coordinate where the click occurred.

744 

745 - `y_: Integer`

746 

747 The y-coordinate where the click occurred.

748 

749 - `keys: Array[String]`

750 

751 The keys being held while clicking.

752 

753 - `class DoubleClick`

754 

755 A double click action.

756 

757 - `keys: Array[String]`

758 

759 The keys being held while double-clicking.

760 

761 - `type: :double_click`

762 

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

764 

765 - `:double_click`

766 

767 - `x: Integer`

768 

769 The x-coordinate where the double click occurred.

770 

771 - `y_: Integer`

772 

773 The y-coordinate where the double click occurred.

774 

775 - `class Drag`

776 

777 A drag action.

778 

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

780 

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

782 

783 ```

784 [

785 { x: 100, y: 200 },

786 { x: 200, y: 300 }

787 ]

788 ```

789 

790 - `x: Integer`

791 

792 The x-coordinate.

793 

794 - `y_: Integer`

795 

796 The y-coordinate.

797 

798 - `type: :drag`

799 

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

801 

802 - `:drag`

803 

804 - `keys: Array[String]`

805 

806 The keys being held while dragging the mouse.

807 

808 - `class Keypress`

809 

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

811 

812 - `keys: Array[String]`

813 

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

815 

816 - `type: :keypress`

817 

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

819 

820 - `:keypress`

821 

822 - `class Move`

823 

824 A mouse move action.

825 

826 - `type: :move`

827 

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

829 

830 - `:move`

831 

832 - `x: Integer`

833 

834 The x-coordinate to move to.

835 

836 - `y_: Integer`

837 

838 The y-coordinate to move to.

839 

840 - `keys: Array[String]`

841 

842 The keys being held while moving the mouse.

843 

844 - `class Screenshot`

845 

846 A screenshot action.

847 

848 - `type: :screenshot`

849 

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

851 

852 - `:screenshot`

853 

854 - `class Scroll`

855 

856 A scroll action.

857 

858 - `scroll_x: Integer`

859 

860 The horizontal scroll distance.

861 

862 - `scroll_y: Integer`

863 

864 The vertical scroll distance.

865 

866 - `type: :scroll`

867 

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

869 

870 - `:scroll`

871 

872 - `x: Integer`

873 

874 The x-coordinate where the scroll occurred.

875 

876 - `y_: Integer`

877 

878 The y-coordinate where the scroll occurred.

879 

880 - `keys: Array[String]`

881 

882 The keys being held while scrolling.

883 

884 - `class Type`

885 

886 An action to type in text.

887 

888 - `text: String`

889 

890 The text to type.

891 

892 - `type: :type`

893 

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

895 

896 - `:type`

897 

898 - `class Wait`

899 

900 A wait action.

901 

902 - `type: :wait`

903 

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

905 

906 - `:wait`

907 

908 - `class ComputerCallOutput`

909 

910 The output of a computer tool call.

911 

912 - `call_id: String`

913 

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

915 

916 - `output: ResponseComputerToolCallOutputScreenshot`

917 

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

919 

920 - `type: :computer_screenshot`

921 

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

923 always set to `computer_screenshot`.

924 

925 - `:computer_screenshot`

926 

927 - `file_id: String`

928 

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

930 

931 - `image_url: String`

932 

933 The URL of the screenshot image.

934 

935 - `type: :computer_call_output`

936 

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

938 

939 - `:computer_call_output`

940 

941 - `id: String`

942 

943 The ID of the computer tool call output.

944 

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

946 

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

948 

949 - `id: String`

950 

951 The ID of the pending safety check.

952 

953 - `code: String`

954 

955 The type of the pending safety check.

956 

957 - `message: String`

958 

959 Details about the pending safety check.

960 

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

962 

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

964 

965 - `:in_progress`

966 

967 - `:completed`

968 

969 - `:incomplete`

970 

971 - `class ResponseFunctionWebSearch`

972 

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

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

975 

976 - `id: String`

977 

978 The unique ID of the web search tool call.

979 

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

981 

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

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

984 

985 - `class Search`

986 

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

988 

989 - `type: :search`

990 

991 The action type.

992 

993 - `:search`

994 

995 - `queries: Array[String]`

996 

997 The search queries.

998 

999 - `query: String`

1000 

1001 The search query.

1002 

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

1004 

1005 The sources used in the search.

1006 

1007 - `type: :url`

1008 

1009 The type of source. Always `url`.

1010 

1011 - `:url`

1012 

1013 - `url: String`

1014 

1015 The URL of the source.

1016 

1017 - `class OpenPage`

1018 

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

1020 

1021 - `type: :open_page`

1022 

1023 The action type.

1024 

1025 - `:open_page`

1026 

1027 - `url: String`

1028 

1029 The URL opened by the model.

1030 

1031 - `class FindInPage`

1032 

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

1034 

1035 - `pattern: String`

1036 

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

1038 

1039 - `type: :find_in_page`

1040 

1041 The action type.

1042 

1043 - `:find_in_page`

1044 

1045 - `url: String`

1046 

1047 The URL of the page searched for the pattern.

1048 

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

1050 

1051 The status of the web search tool call.

1052 

1053 - `:in_progress`

1054 

1055 - `:searching`

1056 

1057 - `:completed`

1058 

1059 - `:failed`

1060 

1061 - `type: :web_search_call`

1062 

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

1064 

1065 - `:web_search_call`

1066 

1067 - `class ResponseFunctionToolCall`

1068 

1069 A tool call to run a function. See the

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

1071 

1072 - `arguments: String`

1073 

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

1075 

1076 - `call_id: String`

1077 

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

1079 

1080 - `name: String`

1081 

1082 The name of the function to run.

1083 

1084 - `type: :function_call`

1085 

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

1087 

1088 - `:function_call`

1089 

1090 - `id: String`

1091 

1092 The unique ID of the function tool call.

1093 

1094 - `caller_: Direct{ type} | Program{ caller_id, type}`

1095 

1096 The execution context that produced this tool call.

1097 

1098 - `class Direct`

1099 

1100 - `type: :direct`

1101 

1102 - `:direct`

1103 

1104 - `class Program`

1105 

1106 - `caller_id: String`

1107 

1108 The call ID of the program item that produced this tool call.

1109 

1110 - `type: :program`

1111 

1112 - `:program`

1113 

1114 - `namespace: String`

1115 

1116 The namespace of the function to run.

1117 

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

1119 

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

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

1122 

1123 - `:in_progress`

1124 

1125 - `:completed`

1126 

1127 - `:incomplete`

1128 

1129 - `class FunctionCallOutput`

1130 

1131 The output of a function tool call.

1132 

1133 - `call_id: String`

1134 

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

1136 

1137 - `output: String | ResponseFunctionCallOutputItemList`

1138 

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

1140 

1141 - `String = String`

1142 

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

1144 

1145 - `ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]`

1146 

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

1148 

1149 - `class ResponseInputTextContent`

1150 

1151 A text input to the model.

1152 

1153 - `text: String`

1154 

1155 The text input to the model.

1156 

1157 - `type: :input_text`

1158 

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

1160 

1161 - `:input_text`

1162 

1163 - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}`

1164 

1165 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

1166 

1167 - `mode: :explicit`

1168 

1169 The breakpoint mode. Always `explicit`.

1170 

1171 - `:explicit`

1172 

1173 - `class ResponseInputImageContent`

1174 

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

1176 

1177 - `type: :input_image`

1178 

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

1180 

1181 - `:input_image`

1182 

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

1184 

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

1186 

1187 - `:low`

1188 

1189 - `:high`

1190 

1191 - `:auto`

1192 

1193 - `:original`

1194 

1195 - `file_id: String`

1196 

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

1198 

1199 - `image_url: String`

1200 

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

1202 

1203 - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}`

1204 

1205 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

1206 

1207 - `mode: :explicit`

1208 

1209 The breakpoint mode. Always `explicit`.

1210 

1211 - `:explicit`

1212 

1213 - `class ResponseInputFileContent`

1214 

1215 A file input to the model.

1216 

1217 - `type: :input_file`

1218 

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

1220 

1221 - `:input_file`

1222 

1223 - `detail: :auto | :low | :high`

1224 

1225 The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`.

1226 

1227 - `:auto`

1228 

1229 - `:low`

1230 

1231 - `:high`

1232 

1233 - `file_data: String`

1234 

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

1236 

1237 - `file_id: String`

1238 

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

1240 

1241 - `file_url: String`

1242 

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

1244 

1245 - `filename: String`

1246 

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

1248 

1249 - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}`

1250 

1251 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

1252 

1253 - `mode: :explicit`

1254 

1255 The breakpoint mode. Always `explicit`.

1256 

1257 - `:explicit`

1258 

1259 - `type: :function_call_output`

1260 

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

1262 

1263 - `:function_call_output`

1264 

1265 - `id: String`

1266 

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

1268 

1269 - `caller_: Direct{ type} | Program{ caller_id, type}`

1270 

1271 The execution context that produced this tool call.

1272 

1273 - `class Direct`

1274 

1275 - `type: :direct`

1276 

1277 The caller type. Always `direct`.

1278 

1279 - `:direct`

1280 

1281 - `class Program`

1282 

1283 - `caller_id: String`

1284 

1285 The call ID of the program item that produced this tool call.

1286 

1287 - `type: :program`

1288 

1289 The caller type. Always `program`.

1290 

1291 - `:program`

1292 

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

1294 

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

1296 

1297 - `:in_progress`

1298 

1299 - `:completed`

1300 

1301 - `:incomplete`

1302 

1303 - `class ToolSearchCall`

1304 

1305 - `arguments: untyped`

1306 

1307 The arguments supplied to the tool search call.

1308 

1309 - `type: :tool_search_call`

1310 

1311 The item type. Always `tool_search_call`.

1312 

1313 - `:tool_search_call`

1314 

1315 - `id: String`

1316 

1317 The unique ID of this tool search call.

1318 

1319 - `call_id: String`

1320 

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

1322 

1323 - `execution: :server | :client`

1324 

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

1326 

1327 - `:server`

1328 

1329 - `:client`

1330 

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

1332 

1333 The status of the tool search call.

1334 

1335 - `:in_progress`

1336 

1337 - `:completed`

1338 

1339 - `:incomplete`

1340 

1341 - `class ResponseToolSearchOutputItemParam`

1342 

1343 - `tools: Array[Tool]`

1344 

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

1346 

1347 - `class FunctionTool`

1348 

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

1350 

1351 - `name: String`

1352 

1353 The name of the function to call.

1354 

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

1356 

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

1358 

1359 - `strict: bool`

1360 

1361 Whether strict parameter validation is enforced for this function tool.

1362 

1363 - `type: :function`

1364 

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

1366 

1367 - `:function`

1368 

1369 - `allowed_callers: Array[:direct | :programmatic]`

1370 

1371 The tool invocation context(s).

1372 

1373 - `:direct`

1374 

1375 - `:programmatic`

1376 

1377 - `defer_loading: bool`

1378 

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

1380 

1381 - `description: String`

1382 

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

1384 

1385 - `output_schema: Hash[Symbol, untyped]`

1386 

1387 A JSON schema object describing the JSON value encoded in string outputs for this function.

1388 

1389 - `class FileSearchTool`

1390 

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

1392 

1393 - `type: :file_search`

1394 

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

1396 

1397 - `:file_search`

1398 

1399 - `vector_store_ids: Array[String]`

1400 

1401 The IDs of the vector stores to search.

1402 

1403 - `filters: ComparisonFilter | CompoundFilter`

1404 

1405 A filter to apply.

1406 

1407 - `class ComparisonFilter`

1408 

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

1410 

1411 - `key: String`

1412 

1413 The key to compare against the value.

1414 

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

1416 

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

1418 

1419 - `eq`: equals

1420 - `ne`: not equal

1421 - `gt`: greater than

1422 - `gte`: greater than or equal

1423 - `lt`: less than

1424 - `lte`: less than or equal

1425 - `in`: in

1426 - `nin`: not in

1427 

1428 - `:eq`

1429 

1430 - `:ne`

1431 

1432 - `:gt`

1433 

1434 - `:gte`

1435 

1436 - `:lt`

1437 

1438 - `:lte`

1439 

1440 - `:in`

1441 

1442 - `:nin`

1443 

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

1445 

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

1447 

1448 - `String = String`

1449 

1450 - `Float = Float`

1451 

1452 - `UnionMember2 = bool`

1453 

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

1455 

1456 - `String = String`

1457 

1458 - `Float = Float`

1459 

1460 - `class CompoundFilter`

1461 

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

1463 

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

1465 

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

1467 

1468 - `class ComparisonFilter`

1469 

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

1471 

1472 - `UnionMember1 = untyped`

1473 

1474 - `type: :and | :or`

1475 

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

1477 

1478 - `:and`

1479 

1480 - `:or`

1481 

1482 - `max_num_results: Integer`

1483 

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

1485 

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

1487 

1488 Ranking options for search.

1489 

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

1491 

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

1493 

1494 - `embedding_weight: Float`

1495 

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

1497 

1498 - `text_weight: Float`

1499 

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

1501 

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

1503 

1504 The ranker to use for the file search.

1505 

1506 - `:auto`

1507 

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

1509 

1510 - `score_threshold: Float`

1511 

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

1513 

1514 - `class ComputerTool`

1515 

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

1517 

1518 - `type: :computer`

1519 

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

1521 

1522 - `:computer`

1523 

1524 - `class ComputerUsePreviewTool`

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 - `display_height: Integer`

1529 

1530 The height of the computer display.

1531 

1532 - `display_width: Integer`

1533 

1534 The width of the computer display.

1535 

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

1537 

1538 The type of computer environment to control.

1539 

1540 - `:windows`

1541 

1542 - `:mac`

1543 

1544 - `:linux`

1545 

1546 - `:ubuntu`

1547 

1548 - `:browser`

1549 

1550 - `type: :computer_use_preview`

1551 

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

1553 

1554 - `:computer_use_preview`

1555 

1556 - `class WebSearchTool`

1557 

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

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

1560 

1561 - `type: :web_search | :web_search_2025_08_26`

1562 

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

1564 

1565 - `:web_search`

1566 

1567 - `:web_search_2025_08_26`

1568 

1569 - `filters: Filters{ allowed_domains}`

1570 

1571 Filters for the search.

1572 

1573 - `allowed_domains: Array[String]`

1574 

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

1576 Subdomains of the provided domains are allowed as well.

1577 

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

1579 

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

1581 

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

1583 

1584 - `:low`

1585 

1586 - `:medium`

1587 

1588 - `:high`

1589 

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

1591 

1592 The approximate location of the user.

1593 

1594 - `city: String`

1595 

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

1597 

1598 - `country: String`

1599 

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

1601 

1602 - `region: String`

1603 

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

1605 

1606 - `timezone: String`

1607 

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

1609 

1610 - `type: :approximate`

1611 

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

1613 

1614 - `:approximate`

1615 

1616 - `class Mcp`

1617 

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

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

1620 

1621 - `server_label: String`

1622 

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

1624 

1625 - `type: :mcp`

1626 

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

1628 

1629 - `:mcp`

1630 

1631 - `allowed_callers: Array[:direct | :programmatic]`

1632 

1633 The tool invocation context(s).

1634 

1635 - `:direct`

1636 

1637 - `:programmatic`

1638 

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

1640 

1641 List of allowed tool names or a filter object.

1642 

1643 - `McpAllowedTools = Array[String]`

1644 

1645 A string array of allowed tool names

1646 

1647 - `class McpToolFilter`

1648 

1649 A filter object to specify which tools are allowed.

1650 

1651 - `read_only: bool`

1652 

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

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

1655 it will match this filter.

1656 

1657 - `tool_names: Array[String]`

1658 

1659 List of allowed tool names.

1660 

1661 - `authorization: String`

1662 

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

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

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

1666 

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

1668 

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

1670 `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more

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

1672 

1673 Currently supported `connector_id` values are:

1674 

1675 - Dropbox: `connector_dropbox`

1676 - Gmail: `connector_gmail`

1677 - Google Calendar: `connector_googlecalendar`

1678 - Google Drive: `connector_googledrive`

1679 - Microsoft Teams: `connector_microsoftteams`

1680 - Outlook Calendar: `connector_outlookcalendar`

1681 - Outlook Email: `connector_outlookemail`

1682 - SharePoint: `connector_sharepoint`

1683 

1684 - `:connector_dropbox`

1685 

1686 - `:connector_gmail`

1687 

1688 - `:connector_googlecalendar`

1689 

1690 - `:connector_googledrive`

1691 

1692 - `:connector_microsoftteams`

1693 

1694 - `:connector_outlookcalendar`

1695 

1696 - `:connector_outlookemail`

1697 

1698 - `:connector_sharepoint`

1699 

1700 - `defer_loading: bool`

1701 

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

1703 

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

1705 

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

1707 or other purposes.

1708 

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

1710 

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

1712 

1713 - `class McpToolApprovalFilter`

1714 

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

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

1717 that require approval.

1718 

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

1720 

1721 A filter object to specify which tools are allowed.

1722 

1723 - `read_only: bool`

1724 

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

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

1727 it will match this filter.

1728 

1729 - `tool_names: Array[String]`

1730 

1731 List of allowed tool names.

1732 

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

1734 

1735 A filter object to specify which tools are allowed.

1736 

1737 - `read_only: bool`

1738 

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

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

1741 it will match this filter.

1742 

1743 - `tool_names: Array[String]`

1744 

1745 List of allowed tool names.

1746 

1747 - `McpToolApprovalSetting = :always | :never`

1748 

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

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

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

1752 

1753 - `:always`

1754 

1755 - `:never`

1756 

1757 - `server_description: String`

1758 

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

1760 

1761 - `server_url: String`

1762 

1763 The URL for the MCP server. One of `server_url`, `connector_id`, or

1764 `tunnel_id` must be provided.

1765 

1766 - `tunnel_id: String`

1767 

1768 The Secure MCP Tunnel ID to use instead of a direct server URL. One of

1769 `server_url`, `connector_id`, or `tunnel_id` must be provided.

1770 

1771 - `class CodeInterpreter`

1772 

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

1774 

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

1776 

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

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

1779 optional `memory_limit` setting.

1780 

1781 - `String = String`

1782 

1783 The container ID.

1784 

1785 - `class CodeInterpreterToolAuto`

1786 

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

1788 

1789 - `type: :auto`

1790 

1791 Always `auto`.

1792 

1793 - `:auto`

1794 

1795 - `file_ids: Array[String]`

1796 

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

1798 

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

1800 

1801 The memory limit for the code interpreter container.

1802 

1803 - `:"1g"`

1804 

1805 - `:"4g"`

1806 

1807 - `:"16g"`

1808 

1809 - `:"64g"`

1810 

1811 - `network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist`

1812 

1813 Network access policy for the container.

1814 

1815 - `class ContainerNetworkPolicyDisabled`

1816 

1817 - `type: :disabled`

1818 

1819 Disable outbound network access. Always `disabled`.

1820 

1821 - `:disabled`

1822 

1823 - `class ContainerNetworkPolicyAllowlist`

1824 

1825 - `allowed_domains: Array[String]`

1826 

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

1828 

1829 - `type: :allowlist`

1830 

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

1832 

1833 - `:allowlist`

1834 

1835 - `domain_secrets: Array[ContainerNetworkPolicyDomainSecret]`

1836 

1837 Optional domain-scoped secrets for allowlisted domains.

1838 

1839 - `domain: String`

1840 

1841 The domain associated with the secret.

1842 

1843 - `name: String`

1844 

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

1846 

1847 - `value: String`

1848 

1849 The secret value to inject for the domain.

1850 

1851 - `type: :code_interpreter`

1852 

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

1854 

1855 - `:code_interpreter`

1856 

1857 - `allowed_callers: Array[:direct | :programmatic]`

1858 

1859 The tool invocation context(s).

1860 

1861 - `:direct`

1862 

1863 - `:programmatic`

1864 

1865 - `class ProgrammaticToolCalling`

1866 

1867 - `type: :programmatic_tool_calling`

1868 

1869 The type of the tool. Always `programmatic_tool_calling`.

1870 

1871 - `:programmatic_tool_calling`

1872 

1873 - `class ImageGeneration`

1874 

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

1876 

1877 - `type: :image_generation`

1878 

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

1880 

1881 - `:image_generation`

1882 

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

1884 

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

1886 

1887 - `:generate`

1888 

1889 - `:edit`

1890 

1891 - `:auto`

1892 

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

1894 

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

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

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

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

1899 automatically determine the best background for the image.

1900 

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

1902 transparent backgrounds. Requests with `background` set to

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

1904 `auto` instead.

1905 

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

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

1908 

1909 - `:transparent`

1910 

1911 - `:opaque`

1912 

1913 - `:auto`

1914 

1915 - `input_fidelity: :high | :low`

1916 

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

1918 

1919 - `:high`

1920 

1921 - `:low`

1922 

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

1924 

1925 Optional mask for inpainting. Contains `image_url`

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

1927 

1928 - `file_id: String`

1929 

1930 File ID for the mask image.

1931 

1932 - `image_url: String`

1933 

1934 Base64-encoded mask image.

1935 

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

1937 

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

1939 

1940 - `String = String`

1941 

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

1943 

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

1945 

1946 - `:"gpt-image-1"`

1947 

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

1949 

1950 - `:"gpt-image-2"`

1951 

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

1953 

1954 - `:"gpt-image-1.5"`

1955 

1956 - `:"chatgpt-image-latest"`

1957 

1958 - `moderation: :auto | :low`

1959 

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

1961 

1962 - `:auto`

1963 

1964 - `:low`

1965 

1966 - `output_compression: Integer`

1967 

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

1969 

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

1971 

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

1973 `jpeg`. Default: `png`.

1974 

1975 - `:png`

1976 

1977 - `:webp`

1978 

1979 - `:jpeg`

1980 

1981 - `partial_images: Integer`

1982 

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

1984 

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

1986 

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

1988 or `auto`. Default: `auto`.

1989 

1990 - `:low`

1991 

1992 - `:medium`

1993 

1994 - `:high`

1995 

1996 - `:auto`