python/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(ConversationCreateParams**kwargs) -> Conversation`

4 

5**post** `/conversations`

6 

7Create a conversation.

8 

9### Parameters

10 

11- `items: Optional[Iterable[ResponseInputItemParam]]`

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: Union[str, 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 - `str`

29 

30 A text input to the model.

31 

32 - `List[ResponseInputContent]`

33 

34 - `class ResponseInputText: …`

35 

36 A text input to the model.

37 

38 - `text: str`

39 

40 The text input to the model.

41 

42 - `type: Literal["input_text"]`

43 

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

45 

46 - `"input_text"`

47 

48 - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]`

49 

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

51 

52 - `mode: Literal["explicit"]`

53 

54 The breakpoint mode. Always `explicit`.

55 

56 - `"explicit"`

57 

58 - `class ResponseInputImage: …`

59 

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

61 

62 - `detail: Literal["low", "high", "auto", "original"]`

63 

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

65 

66 - `"low"`

67 

68 - `"high"`

69 

70 - `"auto"`

71 

72 - `"original"`

73 

74 - `type: Literal["input_image"]`

75 

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

77 

78 - `"input_image"`

79 

80 - `file_id: Optional[str]`

81 

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

83 

84 - `image_url: Optional[str]`

85 

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

87 

88 - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]`

89 

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

91 

92 - `mode: Literal["explicit"]`

93 

94 The breakpoint mode. Always `explicit`.

95 

96 - `"explicit"`

97 

98 - `class ResponseInputFile: …`

99 

100 A file input to the model.

101 

102 - `type: Literal["input_file"]`

103 

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

105 

106 - `"input_file"`

107 

108 - `detail: Optional[Literal["auto", "low", "high"]]`

109 

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

111 

112 - `"auto"`

113 

114 - `"low"`

115 

116 - `"high"`

117 

118 - `file_data: Optional[str]`

119 

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

121 

122 - `file_id: Optional[str]`

123 

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

125 

126 - `file_url: Optional[str]`

127 

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

129 

130 - `filename: Optional[str]`

131 

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

133 

134 - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]`

135 

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

137 

138 - `mode: Literal["explicit"]`

139 

140 The breakpoint mode. Always `explicit`.

141 

142 - `"explicit"`

143 

144 - `role: Literal["user", "assistant", "system", "developer"]`

145 

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

147 `developer`.

148 

149 - `"user"`

150 

151 - `"assistant"`

152 

153 - `"system"`

154 

155 - `"developer"`

156 

157 - `phase: Optional[Literal["commentary", "final_answer"]]`

158 

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

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

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

162 

163 - `"commentary"`

164 

165 - `"final_answer"`

166 

167 - `type: Optional[Literal["message"]]`

168 

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

170 

171 - `"message"`

172 

173 - `class Message: …`

174 

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

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

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

178 

179 - `content: ResponseInputMessageContentList`

180 

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

182 types.

183 

184 - `class ResponseInputText: …`

185 

186 A text input to the model.

187 

188 - `class ResponseInputImage: …`

189 

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

191 

192 - `class ResponseInputFile: …`

193 

194 A file input to the model.

195 

196 - `role: Literal["user", "system", "developer"]`

197 

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

199 

200 - `"user"`

201 

202 - `"system"`

203 

204 - `"developer"`

205 

206 - `status: Optional[Literal["in_progress", "completed", "incomplete"]]`

207 

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

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

210 

211 - `"in_progress"`

212 

213 - `"completed"`

214 

215 - `"incomplete"`

216 

217 - `type: Optional[Literal["message"]]`

218 

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

220 

221 - `"message"`

222 

223 - `class ResponseOutputMessage: …`

224 

225 An output message from the model.

226 

227 - `id: str`

228 

229 The unique ID of the output message.

230 

231 - `content: List[Content]`

232 

233 The content of the output message.

234 

235 - `class ResponseOutputText: …`

236 

237 A text output from the model.

238 

239 - `annotations: List[Annotation]`

240 

241 The annotations of the text output.

242 

243 - `class AnnotationFileCitation: …`

244 

245 A citation to a file.

246 

247 - `file_id: str`

248 

249 The ID of the file.

250 

251 - `filename: str`

252 

253 The filename of the file cited.

254 

255 - `index: int`

256 

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

258 

259 - `type: Literal["file_citation"]`

260 

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

262 

263 - `"file_citation"`

264 

265 - `class AnnotationURLCitation: …`

266 

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

268 

269 - `end_index: int`

270 

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

272 

273 - `start_index: int`

274 

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

276 

277 - `title: str`

278 

279 The title of the web resource.

280 

281 - `type: Literal["url_citation"]`

282 

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

284 

285 - `"url_citation"`

286 

287 - `url: str`

288 

289 The URL of the web resource.

290 

291 - `class AnnotationContainerFileCitation: …`

292 

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

294 

295 - `container_id: str`

296 

297 The ID of the container file.

298 

299 - `end_index: int`

300 

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

302 

303 - `file_id: str`

304 

305 The ID of the file.

306 

307 - `filename: str`

308 

309 The filename of the container file cited.

310 

311 - `start_index: int`

312 

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

314 

315 - `type: Literal["container_file_citation"]`

316 

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

318 

319 - `"container_file_citation"`

320 

321 - `class AnnotationFilePath: …`

322 

323 A path to a file.

324 

325 - `file_id: str`

326 

327 The ID of the file.

328 

329 - `index: int`

330 

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

332 

333 - `type: Literal["file_path"]`

334 

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

336 

337 - `"file_path"`

338 

339 - `text: str`

340 

341 The text output from the model.

342 

343 - `type: Literal["output_text"]`

344 

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

346 

347 - `"output_text"`

348 

349 - `logprobs: Optional[List[Logprob]]`

350 

351 - `token: str`

352 

353 - `bytes: List[int]`

354 

355 - `logprob: float`

356 

357 - `top_logprobs: List[LogprobTopLogprob]`

358 

359 - `token: str`

360 

361 - `bytes: List[int]`

362 

363 - `logprob: float`

364 

365 - `class ResponseOutputRefusal: …`

366 

367 A refusal from the model.

368 

369 - `refusal: str`

370 

371 The refusal explanation from the model.

372 

373 - `type: Literal["refusal"]`

374 

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

376 

377 - `"refusal"`

378 

379 - `role: Literal["assistant"]`

380 

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

382 

383 - `"assistant"`

384 

385 - `status: Literal["in_progress", "completed", "incomplete"]`

386 

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

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

389 

390 - `"in_progress"`

391 

392 - `"completed"`

393 

394 - `"incomplete"`

395 

396 - `type: Literal["message"]`

397 

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

399 

400 - `"message"`

401 

402 - `phase: Optional[Literal["commentary", "final_answer"]]`

403 

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

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

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

407 

408 - `"commentary"`

409 

410 - `"final_answer"`

411 

412 - `class ResponseFileSearchToolCall: …`

413 

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

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

416 

417 - `id: str`

418 

419 The unique ID of the file search tool call.

420 

421 - `queries: List[str]`

422 

423 The queries used to search for files.

424 

425 - `status: Literal["in_progress", "searching", "completed", 2 more]`

426 

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

428 `searching`, `incomplete` or `failed`,

429 

430 - `"in_progress"`

431 

432 - `"searching"`

433 

434 - `"completed"`

435 

436 - `"incomplete"`

437 

438 - `"failed"`

439 

440 - `type: Literal["file_search_call"]`

441 

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

443 

444 - `"file_search_call"`

445 

446 - `results: Optional[List[Result]]`

447 

448 The results of the file search tool call.

449 

450 - `attributes: Optional[Dict[str, Union[str, float, bool]]]`

451 

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

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

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

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

456 length of 512 characters, booleans, or numbers.

457 

458 - `str`

459 

460 - `float`

461 

462 - `bool`

463 

464 - `file_id: Optional[str]`

465 

466 The unique ID of the file.

467 

468 - `filename: Optional[str]`

469 

470 The name of the file.

471 

472 - `score: Optional[float]`

473 

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

475 

476 - `text: Optional[str]`

477 

478 The text that was retrieved from the file.

479 

480 - `class ResponseComputerToolCall: …`

481 

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

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

484 

485 - `id: str`

486 

487 The unique ID of the computer call.

488 

489 - `call_id: str`

490 

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

492 

493 - `pending_safety_checks: List[PendingSafetyCheck]`

494 

495 The pending safety checks for the computer call.

496 

497 - `id: str`

498 

499 The ID of the pending safety check.

500 

501 - `code: Optional[str]`

502 

503 The type of the pending safety check.

504 

505 - `message: Optional[str]`

506 

507 Details about the pending safety check.

508 

509 - `status: Literal["in_progress", "completed", "incomplete"]`

510 

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

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

513 

514 - `"in_progress"`

515 

516 - `"completed"`

517 

518 - `"incomplete"`

519 

520 - `type: Literal["computer_call"]`

521 

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

523 

524 - `"computer_call"`

525 

526 - `action: Optional[Action]`

527 

528 A click action.

529 

530 - `class ActionClick: …`

531 

532 A click action.

533 

534 - `button: Literal["left", "right", "wheel", 2 more]`

535 

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

537 

538 - `"left"`

539 

540 - `"right"`

541 

542 - `"wheel"`

543 

544 - `"back"`

545 

546 - `"forward"`

547 

548 - `type: Literal["click"]`

549 

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

551 

552 - `"click"`

553 

554 - `x: int`

555 

556 The x-coordinate where the click occurred.

557 

558 - `y: int`

559 

560 The y-coordinate where the click occurred.

561 

562 - `keys: Optional[List[str]]`

563 

564 The keys being held while clicking.

565 

566 - `class ActionDoubleClick: …`

567 

568 A double click action.

569 

570 - `keys: Optional[List[str]]`

571 

572 The keys being held while double-clicking.

573 

574 - `type: Literal["double_click"]`

575 

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

577 

578 - `"double_click"`

579 

580 - `x: int`

581 

582 The x-coordinate where the double click occurred.

583 

584 - `y: int`

585 

586 The y-coordinate where the double click occurred.

587 

588 - `class ActionDrag: …`

589 

590 A drag action.

591 

592 - `path: List[ActionDragPath]`

593 

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

595 

596 ```

597 [

598 { x: 100, y: 200 },

599 { x: 200, y: 300 }

600 ]

601 ```

602 

603 - `x: int`

604 

605 The x-coordinate.

606 

607 - `y: int`

608 

609 The y-coordinate.

610 

611 - `type: Literal["drag"]`

612 

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

614 

615 - `"drag"`

616 

617 - `keys: Optional[List[str]]`

618 

619 The keys being held while dragging the mouse.

620 

621 - `class ActionKeypress: …`

622 

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

624 

625 - `keys: List[str]`

626 

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

628 

629 - `type: Literal["keypress"]`

630 

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

632 

633 - `"keypress"`

634 

635 - `class ActionMove: …`

636 

637 A mouse move action.

638 

639 - `type: Literal["move"]`

640 

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

642 

643 - `"move"`

644 

645 - `x: int`

646 

647 The x-coordinate to move to.

648 

649 - `y: int`

650 

651 The y-coordinate to move to.

652 

653 - `keys: Optional[List[str]]`

654 

655 The keys being held while moving the mouse.

656 

657 - `class ActionScreenshot: …`

658 

659 A screenshot action.

660 

661 - `type: Literal["screenshot"]`

662 

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

664 

665 - `"screenshot"`

666 

667 - `class ActionScroll: …`

668 

669 A scroll action.

670 

671 - `scroll_x: int`

672 

673 The horizontal scroll distance.

674 

675 - `scroll_y: int`

676 

677 The vertical scroll distance.

678 

679 - `type: Literal["scroll"]`

680 

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

682 

683 - `"scroll"`

684 

685 - `x: int`

686 

687 The x-coordinate where the scroll occurred.

688 

689 - `y: int`

690 

691 The y-coordinate where the scroll occurred.

692 

693 - `keys: Optional[List[str]]`

694 

695 The keys being held while scrolling.

696 

697 - `class ActionType: …`

698 

699 An action to type in text.

700 

701 - `text: str`

702 

703 The text to type.

704 

705 - `type: Literal["type"]`

706 

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

708 

709 - `"type"`

710 

711 - `class ActionWait: …`

712 

713 A wait action.

714 

715 - `type: Literal["wait"]`

716 

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

718 

719 - `"wait"`

720 

721 - `actions: Optional[ComputerActionList]`

722 

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

724 `type` discriminator and action-specific fields.

725 

726 - `class Click: …`

727 

728 A click action.

729 

730 - `button: Literal["left", "right", "wheel", 2 more]`

731 

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

733 

734 - `"left"`

735 

736 - `"right"`

737 

738 - `"wheel"`

739 

740 - `"back"`

741 

742 - `"forward"`

743 

744 - `type: Literal["click"]`

745 

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

747 

748 - `"click"`

749 

750 - `x: int`

751 

752 The x-coordinate where the click occurred.

753 

754 - `y: int`

755 

756 The y-coordinate where the click occurred.

757 

758 - `keys: Optional[List[str]]`

759 

760 The keys being held while clicking.

761 

762 - `class DoubleClick: …`

763 

764 A double click action.

765 

766 - `keys: Optional[List[str]]`

767 

768 The keys being held while double-clicking.

769 

770 - `type: Literal["double_click"]`

771 

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

773 

774 - `"double_click"`

775 

776 - `x: int`

777 

778 The x-coordinate where the double click occurred.

779 

780 - `y: int`

781 

782 The y-coordinate where the double click occurred.

783 

784 - `class Drag: …`

785 

786 A drag action.

787 

788 - `path: List[DragPath]`

789 

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

791 

792 ```

793 [

794 { x: 100, y: 200 },

795 { x: 200, y: 300 }

796 ]

797 ```

798 

799 - `x: int`

800 

801 The x-coordinate.

802 

803 - `y: int`

804 

805 The y-coordinate.

806 

807 - `type: Literal["drag"]`

808 

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

810 

811 - `"drag"`

812 

813 - `keys: Optional[List[str]]`

814 

815 The keys being held while dragging the mouse.

816 

817 - `class Keypress: …`

818 

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

820 

821 - `keys: List[str]`

822 

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

824 

825 - `type: Literal["keypress"]`

826 

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

828 

829 - `"keypress"`

830 

831 - `class Move: …`

832 

833 A mouse move action.

834 

835 - `type: Literal["move"]`

836 

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

838 

839 - `"move"`

840 

841 - `x: int`

842 

843 The x-coordinate to move to.

844 

845 - `y: int`

846 

847 The y-coordinate to move to.

848 

849 - `keys: Optional[List[str]]`

850 

851 The keys being held while moving the mouse.

852 

853 - `class Screenshot: …`

854 

855 A screenshot action.

856 

857 - `type: Literal["screenshot"]`

858 

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

860 

861 - `"screenshot"`

862 

863 - `class Scroll: …`

864 

865 A scroll action.

866 

867 - `scroll_x: int`

868 

869 The horizontal scroll distance.

870 

871 - `scroll_y: int`

872 

873 The vertical scroll distance.

874 

875 - `type: Literal["scroll"]`

876 

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

878 

879 - `"scroll"`

880 

881 - `x: int`

882 

883 The x-coordinate where the scroll occurred.

884 

885 - `y: int`

886 

887 The y-coordinate where the scroll occurred.

888 

889 - `keys: Optional[List[str]]`

890 

891 The keys being held while scrolling.

892 

893 - `class Type: …`

894 

895 An action to type in text.

896 

897 - `text: str`

898 

899 The text to type.

900 

901 - `type: Literal["type"]`

902 

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

904 

905 - `"type"`

906 

907 - `class Wait: …`

908 

909 A wait action.

910 

911 - `type: Literal["wait"]`

912 

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

914 

915 - `"wait"`

916 

917 - `class ComputerCallOutput: …`

918 

919 The output of a computer tool call.

920 

921 - `call_id: str`

922 

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

924 

925 - `output: ResponseComputerToolCallOutputScreenshot`

926 

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

928 

929 - `type: Literal["computer_screenshot"]`

930 

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

932 always set to `computer_screenshot`.

933 

934 - `"computer_screenshot"`

935 

936 - `file_id: Optional[str]`

937 

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

939 

940 - `image_url: Optional[str]`

941 

942 The URL of the screenshot image.

943 

944 - `type: Literal["computer_call_output"]`

945 

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

947 

948 - `"computer_call_output"`

949 

950 - `id: Optional[str]`

951 

952 The ID of the computer tool call output.

953 

954 - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]`

955 

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

957 

958 - `id: str`

959 

960 The ID of the pending safety check.

961 

962 - `code: Optional[str]`

963 

964 The type of the pending safety check.

965 

966 - `message: Optional[str]`

967 

968 Details about the pending safety check.

969 

970 - `status: Optional[Literal["in_progress", "completed", "incomplete"]]`

971 

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

973 

974 - `"in_progress"`

975 

976 - `"completed"`

977 

978 - `"incomplete"`

979 

980 - `class ResponseFunctionWebSearch: …`

981 

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

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

984 

985 - `id: str`

986 

987 The unique ID of the web search tool call.

988 

989 - `action: Action`

990 

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

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

993 

994 - `class ActionSearch: …`

995 

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

997 

998 - `type: Literal["search"]`

999 

1000 The action type.

1001 

1002 - `"search"`

1003 

1004 - `queries: Optional[List[str]]`

1005 

1006 The search queries.

1007 

1008 - `query: Optional[str]`

1009 

1010 The search query.

1011 

1012 - `sources: Optional[List[ActionSearchSource]]`

1013 

1014 The sources used in the search.

1015 

1016 - `type: Literal["url"]`

1017 

1018 The type of source. Always `url`.

1019 

1020 - `"url"`

1021 

1022 - `url: str`

1023 

1024 The URL of the source.

1025 

1026 - `class ActionOpenPage: …`

1027 

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

1029 

1030 - `type: Literal["open_page"]`

1031 

1032 The action type.

1033 

1034 - `"open_page"`

1035 

1036 - `url: Optional[str]`

1037 

1038 The URL opened by the model.

1039 

1040 - `class ActionFindInPage: …`

1041 

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

1043 

1044 - `pattern: str`

1045 

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

1047 

1048 - `type: Literal["find_in_page"]`

1049 

1050 The action type.

1051 

1052 - `"find_in_page"`

1053 

1054 - `url: str`

1055 

1056 The URL of the page searched for the pattern.

1057 

1058 - `status: Literal["in_progress", "searching", "completed", "failed"]`

1059 

1060 The status of the web search tool call.

1061 

1062 - `"in_progress"`

1063 

1064 - `"searching"`

1065 

1066 - `"completed"`

1067 

1068 - `"failed"`

1069 

1070 - `type: Literal["web_search_call"]`

1071 

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

1073 

1074 - `"web_search_call"`

1075 

1076 - `class ResponseFunctionToolCall: …`

1077 

1078 A tool call to run a function. See the

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

1080 

1081 - `arguments: str`

1082 

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

1084 

1085 - `call_id: str`

1086 

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

1088 

1089 - `name: str`

1090 

1091 The name of the function to run.

1092 

1093 - `type: Literal["function_call"]`

1094 

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

1096 

1097 - `"function_call"`

1098 

1099 - `id: Optional[str]`

1100 

1101 The unique ID of the function tool call.

1102 

1103 - `caller: Optional[Caller]`

1104 

1105 The execution context that produced this tool call.

1106 

1107 - `class CallerDirect: …`

1108 

1109 - `type: Literal["direct"]`

1110 

1111 - `"direct"`

1112 

1113 - `class CallerProgram: …`

1114 

1115 - `caller_id: str`

1116 

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

1118 

1119 - `type: Literal["program"]`

1120 

1121 - `"program"`

1122 

1123 - `namespace: Optional[str]`

1124 

1125 The namespace of the function to run.

1126 

1127 - `status: Optional[Literal["in_progress", "completed", "incomplete"]]`

1128 

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

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

1131 

1132 - `"in_progress"`

1133 

1134 - `"completed"`

1135 

1136 - `"incomplete"`

1137 

1138 - `class FunctionCallOutput: …`

1139 

1140 The output of a function tool call.

1141 

1142 - `call_id: str`

1143 

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

1145 

1146 - `output: Union[str, ResponseFunctionCallOutputItemList]`

1147 

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

1149 

1150 - `str`

1151 

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

1153 

1154 - `List[ResponseFunctionCallOutputItem]`

1155 

1156 - `class ResponseInputTextContent: …`

1157 

1158 A text input to the model.

1159 

1160 - `text: str`

1161 

1162 The text input to the model.

1163 

1164 - `type: Literal["input_text"]`

1165 

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

1167 

1168 - `"input_text"`

1169 

1170 - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]`

1171 

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

1173 

1174 - `mode: Literal["explicit"]`

1175 

1176 The breakpoint mode. Always `explicit`.

1177 

1178 - `"explicit"`

1179 

1180 - `class ResponseInputImageContent: …`

1181 

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

1183 

1184 - `type: Literal["input_image"]`

1185 

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

1187 

1188 - `"input_image"`

1189 

1190 - `detail: Optional[Literal["low", "high", "auto", "original"]]`

1191 

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

1193 

1194 - `"low"`

1195 

1196 - `"high"`

1197 

1198 - `"auto"`

1199 

1200 - `"original"`

1201 

1202 - `file_id: Optional[str]`

1203 

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

1205 

1206 - `image_url: Optional[str]`

1207 

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

1209 

1210 - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]`

1211 

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

1213 

1214 - `mode: Literal["explicit"]`

1215 

1216 The breakpoint mode. Always `explicit`.

1217 

1218 - `"explicit"`

1219 

1220 - `class ResponseInputFileContent: …`

1221 

1222 A file input to the model.

1223 

1224 - `type: Literal["input_file"]`

1225 

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

1227 

1228 - `"input_file"`

1229 

1230 - `detail: Optional[Literal["auto", "low", "high"]]`

1231 

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

1233 

1234 - `"auto"`

1235 

1236 - `"low"`

1237 

1238 - `"high"`

1239 

1240 - `file_data: Optional[str]`

1241 

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

1243 

1244 - `file_id: Optional[str]`

1245 

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

1247 

1248 - `file_url: Optional[str]`

1249 

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

1251 

1252 - `filename: Optional[str]`

1253 

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

1255 

1256 - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]`

1257 

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

1259 

1260 - `mode: Literal["explicit"]`

1261 

1262 The breakpoint mode. Always `explicit`.

1263 

1264 - `"explicit"`

1265 

1266 - `type: Literal["function_call_output"]`

1267 

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

1269 

1270 - `"function_call_output"`

1271 

1272 - `id: Optional[str]`

1273 

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

1275 

1276 - `caller: Optional[FunctionCallOutputCaller]`

1277 

1278 The execution context that produced this tool call.

1279 

1280 - `class FunctionCallOutputCallerDirect: …`

1281 

1282 - `type: Literal["direct"]`

1283 

1284 The caller type. Always `direct`.

1285 

1286 - `"direct"`

1287 

1288 - `class FunctionCallOutputCallerProgram: …`

1289 

1290 - `caller_id: str`

1291 

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

1293 

1294 - `type: Literal["program"]`

1295 

1296 The caller type. Always `program`.

1297 

1298 - `"program"`

1299 

1300 - `status: Optional[Literal["in_progress", "completed", "incomplete"]]`

1301 

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

1303 

1304 - `"in_progress"`

1305 

1306 - `"completed"`

1307 

1308 - `"incomplete"`

1309 

1310 - `class ToolSearchCall: …`

1311 

1312 - `arguments: object`

1313 

1314 The arguments supplied to the tool search call.

1315 

1316 - `type: Literal["tool_search_call"]`

1317 

1318 The item type. Always `tool_search_call`.

1319 

1320 - `"tool_search_call"`

1321 

1322 - `id: Optional[str]`

1323 

1324 The unique ID of this tool search call.

1325 

1326 - `call_id: Optional[str]`

1327 

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

1329 

1330 - `execution: Optional[Literal["server", "client"]]`

1331 

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

1333 

1334 - `"server"`

1335 

1336 - `"client"`

1337 

1338 - `status: Optional[Literal["in_progress", "completed", "incomplete"]]`

1339 

1340 The status of the tool search call.

1341 

1342 - `"in_progress"`

1343 

1344 - `"completed"`

1345 

1346 - `"incomplete"`

1347 

1348 - `class ResponseToolSearchOutputItemParam: …`

1349 

1350 - `tools: List[Tool]`

1351 

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

1353 

1354 - `class FunctionTool: …`

1355 

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

1357 

1358 - `name: str`

1359 

1360 The name of the function to call.

1361 

1362 - `parameters: Optional[Dict[str, object]]`

1363 

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

1365 

1366 - `strict: Optional[bool]`

1367 

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

1369 

1370 - `type: Literal["function"]`

1371 

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

1373 

1374 - `"function"`

1375 

1376 - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]`

1377 

1378 The tool invocation context(s).

1379 

1380 - `"direct"`

1381 

1382 - `"programmatic"`

1383 

1384 - `defer_loading: Optional[bool]`

1385 

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

1387 

1388 - `description: Optional[str]`

1389 

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

1391 

1392 - `output_schema: Optional[Dict[str, object]]`

1393 

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

1395 

1396 - `class FileSearchTool: …`

1397 

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

1399 

1400 - `type: Literal["file_search"]`

1401 

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

1403 

1404 - `"file_search"`

1405 

1406 - `vector_store_ids: List[str]`

1407 

1408 The IDs of the vector stores to search.

1409 

1410 - `filters: Optional[Filters]`

1411 

1412 A filter to apply.

1413 

1414 - `class ComparisonFilter: …`

1415 

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

1417 

1418 - `key: str`

1419 

1420 The key to compare against the value.

1421 

1422 - `type: Literal["eq", "ne", "gt", 5 more]`

1423 

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

1425 

1426 - `eq`: equals

1427 - `ne`: not equal

1428 - `gt`: greater than

1429 - `gte`: greater than or equal

1430 - `lt`: less than

1431 - `lte`: less than or equal

1432 - `in`: in

1433 - `nin`: not in

1434 

1435 - `"eq"`

1436 

1437 - `"ne"`

1438 

1439 - `"gt"`

1440 

1441 - `"gte"`

1442 

1443 - `"lt"`

1444 

1445 - `"lte"`

1446 

1447 - `"in"`

1448 

1449 - `"nin"`

1450 

1451 - `value: Union[str, float, bool, List[Union[str, float]]]`

1452 

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

1454 

1455 - `str`

1456 

1457 - `float`

1458 

1459 - `bool`

1460 

1461 - `List[Union[str, float]]`

1462 

1463 - `str`

1464 

1465 - `float`

1466 

1467 - `class CompoundFilter: …`

1468 

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

1470 

1471 - `filters: List[Filter]`

1472 

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

1474 

1475 - `class ComparisonFilter: …`

1476 

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

1478 

1479 - `object`

1480 

1481 - `type: Literal["and", "or"]`

1482 

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

1484 

1485 - `"and"`

1486 

1487 - `"or"`

1488 

1489 - `max_num_results: Optional[int]`

1490 

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

1492 

1493 - `ranking_options: Optional[RankingOptions]`

1494 

1495 Ranking options for search.

1496 

1497 - `hybrid_search: Optional[RankingOptionsHybridSearch]`

1498 

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

1500 

1501 - `embedding_weight: float`

1502 

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

1504 

1505 - `text_weight: float`

1506 

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

1508 

1509 - `ranker: Optional[Literal["auto", "default-2024-11-15"]]`

1510 

1511 The ranker to use for the file search.

1512 

1513 - `"auto"`

1514 

1515 - `"default-2024-11-15"`

1516 

1517 - `score_threshold: Optional[float]`

1518 

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

1520 

1521 - `class ComputerTool: …`

1522 

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

1524 

1525 - `type: Literal["computer"]`

1526 

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

1528 

1529 - `"computer"`

1530 

1531 - `class ComputerUsePreviewTool: …`

1532 

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

1534 

1535 - `display_height: int`

1536 

1537 The height of the computer display.

1538 

1539 - `display_width: int`

1540 

1541 The width of the computer display.

1542 

1543 - `environment: Literal["windows", "mac", "linux", 2 more]`

1544 

1545 The type of computer environment to control.

1546 

1547 - `"windows"`

1548 

1549 - `"mac"`

1550 

1551 - `"linux"`

1552 

1553 - `"ubuntu"`

1554 

1555 - `"browser"`

1556 

1557 - `type: Literal["computer_use_preview"]`

1558 

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

1560 

1561 - `"computer_use_preview"`

1562 

1563 - `class WebSearchTool: …`

1564 

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

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

1567 

1568 - `type: Literal["web_search", "web_search_2025_08_26"]`

1569 

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

1571 

1572 - `"web_search"`

1573 

1574 - `"web_search_2025_08_26"`

1575 

1576 - `filters: Optional[Filters]`

1577 

1578 Filters for the search.

1579 

1580 - `allowed_domains: Optional[List[str]]`

1581 

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

1583 Subdomains of the provided domains are allowed as well.

1584 

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

1586 

1587 - `search_context_size: Optional[Literal["low", "medium", "high"]]`

1588 

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

1590 

1591 - `"low"`

1592 

1593 - `"medium"`

1594 

1595 - `"high"`

1596 

1597 - `user_location: Optional[UserLocation]`

1598 

1599 The approximate location of the user.

1600 

1601 - `city: Optional[str]`

1602 

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

1604 

1605 - `country: Optional[str]`

1606 

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

1608 

1609 - `region: Optional[str]`

1610 

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

1612 

1613 - `timezone: Optional[str]`

1614 

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

1616 

1617 - `type: Optional[Literal["approximate"]]`

1618 

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

1620 

1621 - `"approximate"`

1622 

1623 - `class Mcp: …`

1624 

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

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

1627 

1628 - `server_label: str`

1629 

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

1631 

1632 - `type: Literal["mcp"]`

1633 

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

1635 

1636 - `"mcp"`

1637 

1638 - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]`

1639 

1640 The tool invocation context(s).

1641 

1642 - `"direct"`

1643 

1644 - `"programmatic"`

1645 

1646 - `allowed_tools: Optional[McpAllowedTools]`

1647 

1648 List of allowed tool names or a filter object.

1649 

1650 - `List[str]`

1651 

1652 A string array of allowed tool names

1653 

1654 - `class McpAllowedToolsMcpToolFilter: …`

1655 

1656 A filter object to specify which tools are allowed.

1657 

1658 - `read_only: Optional[bool]`

1659 

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

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

1662 it will match this filter.

1663 

1664 - `tool_names: Optional[List[str]]`

1665 

1666 List of allowed tool names.

1667 

1668 - `authorization: Optional[str]`

1669 

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

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

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

1673 

1674 - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]`

1675 

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

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

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

1679 

1680 Currently supported `connector_id` values are:

1681 

1682 - Dropbox: `connector_dropbox`

1683 - Gmail: `connector_gmail`

1684 - Google Calendar: `connector_googlecalendar`

1685 - Google Drive: `connector_googledrive`

1686 - Microsoft Teams: `connector_microsoftteams`

1687 - Outlook Calendar: `connector_outlookcalendar`

1688 - Outlook Email: `connector_outlookemail`

1689 - SharePoint: `connector_sharepoint`

1690 

1691 - `"connector_dropbox"`

1692 

1693 - `"connector_gmail"`

1694 

1695 - `"connector_googlecalendar"`

1696 

1697 - `"connector_googledrive"`

1698 

1699 - `"connector_microsoftteams"`

1700 

1701 - `"connector_outlookcalendar"`

1702 

1703 - `"connector_outlookemail"`

1704 

1705 - `"connector_sharepoint"`

1706 

1707 - `defer_loading: Optional[bool]`

1708 

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

1710 

1711 - `headers: Optional[Dict[str, str]]`

1712 

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

1714 or other purposes.

1715 

1716 - `require_approval: Optional[McpRequireApproval]`

1717 

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

1719 

1720 - `class McpRequireApprovalMcpToolApprovalFilter: …`

1721 

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

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

1724 that require approval.

1725 

1726 - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]`

1727 

1728 A filter object to specify which tools are allowed.

1729 

1730 - `read_only: Optional[bool]`

1731 

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

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

1734 it will match this filter.

1735 

1736 - `tool_names: Optional[List[str]]`

1737 

1738 List of allowed tool names.

1739 

1740 - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]`

1741 

1742 A filter object to specify which tools are allowed.

1743 

1744 - `read_only: Optional[bool]`

1745 

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

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

1748 it will match this filter.

1749 

1750 - `tool_names: Optional[List[str]]`

1751 

1752 List of allowed tool names.

1753 

1754 - `Literal["always", "never"]`

1755 

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

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

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

1759 

1760 - `"always"`

1761 

1762 - `"never"`

1763 

1764 - `server_description: Optional[str]`

1765 

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

1767 

1768 - `server_url: Optional[str]`

1769 

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

1771 `tunnel_id` must be provided.

1772 

1773 - `tunnel_id: Optional[str]`

1774 

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

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

1777 

1778 - `class CodeInterpreter: …`

1779 

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

1781 

1782 - `container: CodeInterpreterContainer`

1783 

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

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

1786 optional `memory_limit` setting.

1787 

1788 - `str`

1789 

1790 The container ID.

1791 

1792 - `class CodeInterpreterContainerCodeInterpreterToolAuto: …`

1793 

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

1795 

1796 - `type: Literal["auto"]`

1797 

1798 Always `auto`.

1799 

1800 - `"auto"`

1801 

1802 - `file_ids: Optional[List[str]]`

1803 

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

1805 

1806 - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]`

1807 

1808 The memory limit for the code interpreter container.

1809 

1810 - `"1g"`

1811 

1812 - `"4g"`

1813 

1814 - `"16g"`

1815 

1816 - `"64g"`

1817 

1818 - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]`

1819 

1820 Network access policy for the container.

1821 

1822 - `class ContainerNetworkPolicyDisabled: …`

1823 

1824 - `type: Literal["disabled"]`

1825 

1826 Disable outbound network access. Always `disabled`.

1827 

1828 - `"disabled"`

1829 

1830 - `class ContainerNetworkPolicyAllowlist: …`

1831 

1832 - `allowed_domains: List[str]`

1833 

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

1835 

1836 - `type: Literal["allowlist"]`

1837 

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

1839 

1840 - `"allowlist"`

1841 

1842 - `domain_secrets: Optional[List[ContainerNetworkPolicyDomainSecret]]`

1843 

1844 Optional domain-scoped secrets for allowlisted domains.

1845 

1846 - `domain: str`

1847 

1848 The domain associated with the secret.

1849 

1850 - `name: str`

1851 

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

1853 

1854 - `value: str`

1855 

1856 The secret value to inject for the domain.

1857 

1858 - `type: Literal["code_interpreter"]`

1859 

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

1861 

1862 - `"code_interpreter"`

1863 

1864 - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]`

1865 

1866 The tool invocation context(s).

1867 

1868 - `"direct"`

1869 

1870 - `"programmatic"`

1871 

1872 - `class ProgrammaticToolCalling: …`

1873 

1874 - `type: Literal["programmatic_tool_calling"]`

1875 

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

1877 

1878 - `"programmatic_tool_calling"`

1879 

1880 - `class ImageGeneration: …`

1881 

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

1883 

1884 - `type: Literal["image_generation"]`

1885 

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

1887 

1888 - `"image_generation"`

1889 

1890 - `action: Optional[Literal["generate", "edit", "auto"]]`

1891 

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

1893 

1894 - `"generate"`

1895 

1896 - `"edit"`

1897 

1898 - `"auto"`

1899 

1900 - `background: Optional[Literal["transparent", "opaque", "auto"]]`

1901 

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

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

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

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

1906 automatically determine the best background for the image.

1907 

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

1909 transparent backgrounds. Requests with `background` set to

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

1911 `auto` instead.

1912 

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

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

1915 

1916 - `"transparent"`

1917 

1918 - `"opaque"`

1919 

1920 - `"auto"`

1921 

1922 - `input_fidelity: Optional[Literal["high", "low"]]`

1923 

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

1925 

1926 - `"high"`

1927 

1928 - `"low"`

1929 

1930 - `input_image_mask: Optional[ImageGenerationInputImageMask]`

1931 

1932 Optional mask for inpainting. Contains `image_url`

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

1934 

1935 - `file_id: Optional[str]`

1936 

1937 File ID for the mask image.

1938 

1939 - `image_url: Optional[str]`

1940 

1941 Base64-encoded mask image.

1942 

1943 - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]`

1944 

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

1946 

1947 - `str`

1948 

1949 - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]`

1950 

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

1952 

1953 - `"gpt-image-1"`

1954 

1955 - `"gpt-image-1-mini"`

1956 

1957 - `"gpt-image-2"`

1958 

1959 - `"gpt-image-2-2026-04-21"`

1960 

1961 - `"gpt-image-1.5"`

1962 

1963 - `"chatgpt-image-latest"`

1964 

1965 - `moderation: Optional[Literal["auto", "low"]]`

1966 

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

1968 

1969 - `"auto"`

1970 

1971 - `"low"`

1972 

1973 - `output_compression: Optional[int]`

1974 

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

1976 

1977 - `output_format: Optional[Literal["png", "webp", "jpeg"]]`

1978 

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

1980 `jpeg`. Default: `png`.

1981 

1982 - `"png"`

1983 

1984 - `"webp"`

1985 

1986 - `"jpeg"`

1987 

1988 - `partial_images: Optional[int]`

1989 

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

1991 

1992 - `quality: Optional[Literal["low", "medium", "high", "auto"]]`

1993 

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

1995 or `auto`. Default: `auto`.

1996