python/resources/conversations/methods/create/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 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 - `class ResponseInputImage: …`

49 

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

51 

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

53 

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

55 

56 - `"low"`

57 

58 - `"high"`

59 

60 - `"auto"`

61 

62 - `"original"`

63 

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

65 

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

67 

68 - `"input_image"`

69 

70 - `file_id: Optional[str]`

71 

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

73 

74 - `image_url: Optional[str]`

75 

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

77 

78 - `class ResponseInputFile: …`

79 

80 A file input to the model.

81 

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

83 

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

85 

86 - `"input_file"`

87 

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

89 

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

91 

92 - `"low"`

93 

94 - `"high"`

95 

96 - `file_data: Optional[str]`

97 

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

99 

100 - `file_id: Optional[str]`

101 

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

103 

104 - `file_url: Optional[str]`

105 

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

107 

108 - `filename: Optional[str]`

109 

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

111 

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

113 

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

115 `developer`.

116 

117 - `"user"`

118 

119 - `"assistant"`

120 

121 - `"system"`

122 

123 - `"developer"`

124 

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

126 

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

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

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

130 

131 - `"commentary"`

132 

133 - `"final_answer"`

134 

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

136 

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

138 

139 - `"message"`

140 

141 - `class Message: …`

142 

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

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

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

146 

147 - `content: ResponseInputMessageContentList`

148 

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

150 types.

151 

152 - `class ResponseInputText: …`

153 

154 A text input to the model.

155 

156 - `class ResponseInputImage: …`

157 

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

159 

160 - `class ResponseInputFile: …`

161 

162 A file input to the model.

163 

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

165 

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

167 

168 - `"user"`

169 

170 - `"system"`

171 

172 - `"developer"`

173 

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

175 

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

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

178 

179 - `"in_progress"`

180 

181 - `"completed"`

182 

183 - `"incomplete"`

184 

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

186 

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

188 

189 - `"message"`

190 

191 - `class ResponseOutputMessage: …`

192 

193 An output message from the model.

194 

195 - `id: str`

196 

197 The unique ID of the output message.

198 

199 - `content: List[Content]`

200 

201 The content of the output message.

202 

203 - `class ResponseOutputText: …`

204 

205 A text output from the model.

206 

207 - `annotations: List[Annotation]`

208 

209 The annotations of the text output.

210 

211 - `class AnnotationFileCitation: …`

212 

213 A citation to a file.

214 

215 - `file_id: str`

216 

217 The ID of the file.

218 

219 - `filename: str`

220 

221 The filename of the file cited.

222 

223 - `index: int`

224 

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

226 

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

228 

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

230 

231 - `"file_citation"`

232 

233 - `class AnnotationURLCitation: …`

234 

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

236 

237 - `end_index: int`

238 

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

240 

241 - `start_index: int`

242 

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

244 

245 - `title: str`

246 

247 The title of the web resource.

248 

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

250 

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

252 

253 - `"url_citation"`

254 

255 - `url: str`

256 

257 The URL of the web resource.

258 

259 - `class AnnotationContainerFileCitation: …`

260 

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

262 

263 - `container_id: str`

264 

265 The ID of the container file.

266 

267 - `end_index: int`

268 

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

270 

271 - `file_id: str`

272 

273 The ID of the file.

274 

275 - `filename: str`

276 

277 The filename of the container file cited.

278 

279 - `start_index: int`

280 

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

282 

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

284 

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

286 

287 - `"container_file_citation"`

288 

289 - `class AnnotationFilePath: …`

290 

291 A path to a file.

292 

293 - `file_id: str`

294 

295 The ID of the file.

296 

297 - `index: int`

298 

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

300 

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

302 

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

304 

305 - `"file_path"`

306 

307 - `text: str`

308 

309 The text output from the model.

310 

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

312 

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

314 

315 - `"output_text"`

316 

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

318 

319 - `token: str`

320 

321 - `bytes: List[int]`

322 

323 - `logprob: float`

324 

325 - `top_logprobs: List[LogprobTopLogprob]`

326 

327 - `token: str`

328 

329 - `bytes: List[int]`

330 

331 - `logprob: float`

332 

333 - `class ResponseOutputRefusal: …`

334 

335 A refusal from the model.

336 

337 - `refusal: str`

338 

339 The refusal explanation from the model.

340 

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

342 

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

344 

345 - `"refusal"`

346 

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

348 

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

350 

351 - `"assistant"`

352 

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

354 

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

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

357 

358 - `"in_progress"`

359 

360 - `"completed"`

361 

362 - `"incomplete"`

363 

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

365 

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

367 

368 - `"message"`

369 

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

371 

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

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

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

375 

376 - `"commentary"`

377 

378 - `"final_answer"`

379 

380 - `class ResponseFileSearchToolCall: …`

381 

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

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

384 

385 - `id: str`

386 

387 The unique ID of the file search tool call.

388 

389 - `queries: List[str]`

390 

391 The queries used to search for files.

392 

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

394 

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

396 `searching`, `incomplete` or `failed`,

397 

398 - `"in_progress"`

399 

400 - `"searching"`

401 

402 - `"completed"`

403 

404 - `"incomplete"`

405 

406 - `"failed"`

407 

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

409 

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

411 

412 - `"file_search_call"`

413 

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

415 

416 The results of the file search tool call.

417 

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

419 

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

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

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

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

424 length of 512 characters, booleans, or numbers.

425 

426 - `str`

427 

428 - `float`

429 

430 - `bool`

431 

432 - `file_id: Optional[str]`

433 

434 The unique ID of the file.

435 

436 - `filename: Optional[str]`

437 

438 The name of the file.

439 

440 - `score: Optional[float]`

441 

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

443 

444 - `text: Optional[str]`

445 

446 The text that was retrieved from the file.

447 

448 - `class ResponseComputerToolCall: …`

449 

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

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

452 

453 - `id: str`

454 

455 The unique ID of the computer call.

456 

457 - `call_id: str`

458 

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

460 

461 - `pending_safety_checks: List[PendingSafetyCheck]`

462 

463 The pending safety checks for the computer call.

464 

465 - `id: str`

466 

467 The ID of the pending safety check.

468 

469 - `code: Optional[str]`

470 

471 The type of the pending safety check.

472 

473 - `message: Optional[str]`

474 

475 Details about the pending safety check.

476 

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

478 

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

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

481 

482 - `"in_progress"`

483 

484 - `"completed"`

485 

486 - `"incomplete"`

487 

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

489 

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

491 

492 - `"computer_call"`

493 

494 - `action: Optional[Action]`

495 

496 A click action.

497 

498 - `class ActionClick: …`

499 

500 A click action.

501 

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

503 

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

505 

506 - `"left"`

507 

508 - `"right"`

509 

510 - `"wheel"`

511 

512 - `"back"`

513 

514 - `"forward"`

515 

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

517 

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

519 

520 - `"click"`

521 

522 - `x: int`

523 

524 The x-coordinate where the click occurred.

525 

526 - `y: int`

527 

528 The y-coordinate where the click occurred.

529 

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

531 

532 The keys being held while clicking.

533 

534 - `class ActionDoubleClick: …`

535 

536 A double click action.

537 

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

539 

540 The keys being held while double-clicking.

541 

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

543 

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

545 

546 - `"double_click"`

547 

548 - `x: int`

549 

550 The x-coordinate where the double click occurred.

551 

552 - `y: int`

553 

554 The y-coordinate where the double click occurred.

555 

556 - `class ActionDrag: …`

557 

558 A drag action.

559 

560 - `path: List[ActionDragPath]`

561 

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

563 

564 ```

565 [

566 { x: 100, y: 200 },

567 { x: 200, y: 300 }

568 ]

569 ```

570 

571 - `x: int`

572 

573 The x-coordinate.

574 

575 - `y: int`

576 

577 The y-coordinate.

578 

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

580 

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

582 

583 - `"drag"`

584 

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

586 

587 The keys being held while dragging the mouse.

588 

589 - `class ActionKeypress: …`

590 

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

592 

593 - `keys: List[str]`

594 

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

596 

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

598 

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

600 

601 - `"keypress"`

602 

603 - `class ActionMove: …`

604 

605 A mouse move action.

606 

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

608 

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

610 

611 - `"move"`

612 

613 - `x: int`

614 

615 The x-coordinate to move to.

616 

617 - `y: int`

618 

619 The y-coordinate to move to.

620 

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

622 

623 The keys being held while moving the mouse.

624 

625 - `class ActionScreenshot: …`

626 

627 A screenshot action.

628 

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

630 

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

632 

633 - `"screenshot"`

634 

635 - `class ActionScroll: …`

636 

637 A scroll action.

638 

639 - `scroll_x: int`

640 

641 The horizontal scroll distance.

642 

643 - `scroll_y: int`

644 

645 The vertical scroll distance.

646 

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

648 

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

650 

651 - `"scroll"`

652 

653 - `x: int`

654 

655 The x-coordinate where the scroll occurred.

656 

657 - `y: int`

658 

659 The y-coordinate where the scroll occurred.

660 

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

662 

663 The keys being held while scrolling.

664 

665 - `class ActionType: …`

666 

667 An action to type in text.

668 

669 - `text: str`

670 

671 The text to type.

672 

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

674 

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

676 

677 - `"type"`

678 

679 - `class ActionWait: …`

680 

681 A wait action.

682 

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

684 

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

686 

687 - `"wait"`

688 

689 - `actions: Optional[ComputerActionList]`

690 

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

692 `type` discriminator and action-specific fields.

693 

694 - `class Click: …`

695 

696 A click action.

697 

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

699 

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

701 

702 - `"left"`

703 

704 - `"right"`

705 

706 - `"wheel"`

707 

708 - `"back"`

709 

710 - `"forward"`

711 

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

713 

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

715 

716 - `"click"`

717 

718 - `x: int`

719 

720 The x-coordinate where the click occurred.

721 

722 - `y: int`

723 

724 The y-coordinate where the click occurred.

725 

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

727 

728 The keys being held while clicking.

729 

730 - `class DoubleClick: …`

731 

732 A double click action.

733 

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

735 

736 The keys being held while double-clicking.

737 

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

739 

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

741 

742 - `"double_click"`

743 

744 - `x: int`

745 

746 The x-coordinate where the double click occurred.

747 

748 - `y: int`

749 

750 The y-coordinate where the double click occurred.

751 

752 - `class Drag: …`

753 

754 A drag action.

755 

756 - `path: List[DragPath]`

757 

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

759 

760 ```

761 [

762 { x: 100, y: 200 },

763 { x: 200, y: 300 }

764 ]

765 ```

766 

767 - `x: int`

768 

769 The x-coordinate.

770 

771 - `y: int`

772 

773 The y-coordinate.

774 

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

776 

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

778 

779 - `"drag"`

780 

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

782 

783 The keys being held while dragging the mouse.

784 

785 - `class Keypress: …`

786 

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

788 

789 - `keys: List[str]`

790 

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

792 

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

794 

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

796 

797 - `"keypress"`

798 

799 - `class Move: …`

800 

801 A mouse move action.

802 

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

804 

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

806 

807 - `"move"`

808 

809 - `x: int`

810 

811 The x-coordinate to move to.

812 

813 - `y: int`

814 

815 The y-coordinate to move to.

816 

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

818 

819 The keys being held while moving the mouse.

820 

821 - `class Screenshot: …`

822 

823 A screenshot action.

824 

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

826 

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

828 

829 - `"screenshot"`

830 

831 - `class Scroll: …`

832 

833 A scroll action.

834 

835 - `scroll_x: int`

836 

837 The horizontal scroll distance.

838 

839 - `scroll_y: int`

840 

841 The vertical scroll distance.

842 

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

844 

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

846 

847 - `"scroll"`

848 

849 - `x: int`

850 

851 The x-coordinate where the scroll occurred.

852 

853 - `y: int`

854 

855 The y-coordinate where the scroll occurred.

856 

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

858 

859 The keys being held while scrolling.

860 

861 - `class Type: …`

862 

863 An action to type in text.

864 

865 - `text: str`

866 

867 The text to type.

868 

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

870 

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

872 

873 - `"type"`

874 

875 - `class Wait: …`

876 

877 A wait action.

878 

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

880 

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

882 

883 - `"wait"`

884 

885 - `class ComputerCallOutput: …`

886 

887 The output of a computer tool call.

888 

889 - `call_id: str`

890 

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

892 

893 - `output: ResponseComputerToolCallOutputScreenshot`

894 

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

896 

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

898 

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

900 always set to `computer_screenshot`.

901 

902 - `"computer_screenshot"`

903 

904 - `file_id: Optional[str]`

905 

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

907 

908 - `image_url: Optional[str]`

909 

910 The URL of the screenshot image.

911 

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

913 

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

915 

916 - `"computer_call_output"`

917 

918 - `id: Optional[str]`

919 

920 The ID of the computer tool call output.

921 

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

923 

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

925 

926 - `id: str`

927 

928 The ID of the pending safety check.

929 

930 - `code: Optional[str]`

931 

932 The type of the pending safety check.

933 

934 - `message: Optional[str]`

935 

936 Details about the pending safety check.

937 

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

939 

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

941 

942 - `"in_progress"`

943 

944 - `"completed"`

945 

946 - `"incomplete"`

947 

948 - `class ResponseFunctionWebSearch: …`

949 

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

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

952 

953 - `id: str`

954 

955 The unique ID of the web search tool call.

956 

957 - `action: Action`

958 

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

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

961 

962 - `class ActionSearch: …`

963 

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

965 

966 - `query: str`

967 

968 [DEPRECATED] The search query.

969 

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

971 

972 The action type.

973 

974 - `"search"`

975 

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

977 

978 The search queries.

979 

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

981 

982 The sources used in the search.

983 

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

985 

986 The type of source. Always `url`.

987 

988 - `"url"`

989 

990 - `url: str`

991 

992 The URL of the source.

993 

994 - `class ActionOpenPage: …`

995 

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

997 

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

999 

1000 The action type.

1001 

1002 - `"open_page"`

1003 

1004 - `url: Optional[str]`

1005 

1006 The URL opened by the model.

1007 

1008 - `class ActionFindInPage: …`

1009 

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

1011 

1012 - `pattern: str`

1013 

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

1015 

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

1017 

1018 The action type.

1019 

1020 - `"find_in_page"`

1021 

1022 - `url: str`

1023 

1024 The URL of the page searched for the pattern.

1025 

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

1027 

1028 The status of the web search tool call.

1029 

1030 - `"in_progress"`

1031 

1032 - `"searching"`

1033 

1034 - `"completed"`

1035 

1036 - `"failed"`

1037 

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

1039 

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

1041 

1042 - `"web_search_call"`

1043 

1044 - `class ResponseFunctionToolCall: …`

1045 

1046 A tool call to run a function. See the

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

1048 

1049 - `arguments: str`

1050 

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

1052 

1053 - `call_id: str`

1054 

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

1056 

1057 - `name: str`

1058 

1059 The name of the function to run.

1060 

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

1062 

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

1064 

1065 - `"function_call"`

1066 

1067 - `id: Optional[str]`

1068 

1069 The unique ID of the function tool call.

1070 

1071 - `namespace: Optional[str]`

1072 

1073 The namespace of the function to run.

1074 

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

1076 

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

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

1079 

1080 - `"in_progress"`

1081 

1082 - `"completed"`

1083 

1084 - `"incomplete"`

1085 

1086 - `class FunctionCallOutput: …`

1087 

1088 The output of a function tool call.

1089 

1090 - `call_id: str`

1091 

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

1093 

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

1095 

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

1097 

1098 - `str`

1099 

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

1101 

1102 - `List[ResponseFunctionCallOutputItem]`

1103 

1104 - `class ResponseInputTextContent: …`

1105 

1106 A text input to the model.

1107 

1108 - `text: str`

1109 

1110 The text input to the model.

1111 

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

1113 

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

1115 

1116 - `"input_text"`

1117 

1118 - `class ResponseInputImageContent: …`

1119 

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

1121 

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

1123 

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

1125 

1126 - `"input_image"`

1127 

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

1129 

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

1131 

1132 - `"low"`

1133 

1134 - `"high"`

1135 

1136 - `"auto"`

1137 

1138 - `"original"`

1139 

1140 - `file_id: Optional[str]`

1141 

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

1143 

1144 - `image_url: Optional[str]`

1145 

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

1147 

1148 - `class ResponseInputFileContent: …`

1149 

1150 A file input to the model.

1151 

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

1153 

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

1155 

1156 - `"input_file"`

1157 

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

1159 

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

1161 

1162 - `"low"`

1163 

1164 - `"high"`

1165 

1166 - `file_data: Optional[str]`

1167 

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

1169 

1170 - `file_id: Optional[str]`

1171 

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

1173 

1174 - `file_url: Optional[str]`

1175 

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

1177 

1178 - `filename: Optional[str]`

1179 

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

1181 

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

1183 

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

1185 

1186 - `"function_call_output"`

1187 

1188 - `id: Optional[str]`

1189 

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

1191 

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

1193 

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

1195 

1196 - `"in_progress"`

1197 

1198 - `"completed"`

1199 

1200 - `"incomplete"`

1201 

1202 - `class ToolSearchCall: …`

1203 

1204 - `arguments: object`

1205 

1206 The arguments supplied to the tool search call.

1207 

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

1209 

1210 The item type. Always `tool_search_call`.

1211 

1212 - `"tool_search_call"`

1213 

1214 - `id: Optional[str]`

1215 

1216 The unique ID of this tool search call.

1217 

1218 - `call_id: Optional[str]`

1219 

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

1221 

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

1223 

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

1225 

1226 - `"server"`

1227 

1228 - `"client"`

1229 

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

1231 

1232 The status of the tool search call.

1233 

1234 - `"in_progress"`

1235 

1236 - `"completed"`

1237 

1238 - `"incomplete"`

1239 

1240 - `class ResponseToolSearchOutputItemParam: …`

1241 

1242 - `tools: List[Tool]`

1243 

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

1245 

1246 - `class FunctionTool: …`

1247 

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

1249 

1250 - `name: str`

1251 

1252 The name of the function to call.

1253 

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

1255 

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

1257 

1258 - `strict: Optional[bool]`

1259 

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

1261 

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

1263 

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

1265 

1266 - `"function"`

1267 

1268 - `defer_loading: Optional[bool]`

1269 

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

1271 

1272 - `description: Optional[str]`

1273 

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

1275 

1276 - `class FileSearchTool: …`

1277 

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

1279 

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

1281 

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

1283 

1284 - `"file_search"`

1285 

1286 - `vector_store_ids: List[str]`

1287 

1288 The IDs of the vector stores to search.

1289 

1290 - `filters: Optional[Filters]`

1291 

1292 A filter to apply.

1293 

1294 - `class ComparisonFilter: …`

1295 

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

1297 

1298 - `key: str`

1299 

1300 The key to compare against the value.

1301 

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

1303 

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

1305 

1306 - `eq`: equals

1307 - `ne`: not equal

1308 - `gt`: greater than

1309 - `gte`: greater than or equal

1310 - `lt`: less than

1311 - `lte`: less than or equal

1312 - `in`: in

1313 - `nin`: not in

1314 

1315 - `"eq"`

1316 

1317 - `"ne"`

1318 

1319 - `"gt"`

1320 

1321 - `"gte"`

1322 

1323 - `"lt"`

1324 

1325 - `"lte"`

1326 

1327 - `"in"`

1328 

1329 - `"nin"`

1330 

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

1332 

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

1334 

1335 - `str`

1336 

1337 - `float`

1338 

1339 - `bool`

1340 

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

1342 

1343 - `str`

1344 

1345 - `float`

1346 

1347 - `class CompoundFilter: …`

1348 

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

1350 

1351 - `filters: List[Filter]`

1352 

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

1354 

1355 - `class ComparisonFilter: …`

1356 

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

1358 

1359 - `object`

1360 

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

1362 

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

1364 

1365 - `"and"`

1366 

1367 - `"or"`

1368 

1369 - `max_num_results: Optional[int]`

1370 

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

1372 

1373 - `ranking_options: Optional[RankingOptions]`

1374 

1375 Ranking options for search.

1376 

1377 - `hybrid_search: Optional[RankingOptionsHybridSearch]`

1378 

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

1380 

1381 - `embedding_weight: float`

1382 

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

1384 

1385 - `text_weight: float`

1386 

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

1388 

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

1390 

1391 The ranker to use for the file search.

1392 

1393 - `"auto"`

1394 

1395 - `"default-2024-11-15"`

1396 

1397 - `score_threshold: Optional[float]`

1398 

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

1400 

1401 - `class ComputerTool: …`

1402 

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

1404 

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

1406 

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

1408 

1409 - `"computer"`

1410 

1411 - `class ComputerUsePreviewTool: …`

1412 

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

1414 

1415 - `display_height: int`

1416 

1417 The height of the computer display.

1418 

1419 - `display_width: int`

1420 

1421 The width of the computer display.

1422 

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

1424 

1425 The type of computer environment to control.

1426 

1427 - `"windows"`

1428 

1429 - `"mac"`

1430 

1431 - `"linux"`

1432 

1433 - `"ubuntu"`

1434 

1435 - `"browser"`

1436 

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

1438 

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

1440 

1441 - `"computer_use_preview"`

1442 

1443 - `class WebSearchTool: …`

1444 

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

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

1447 

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

1449 

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

1451 

1452 - `"web_search"`

1453 

1454 - `"web_search_2025_08_26"`

1455 

1456 - `filters: Optional[Filters]`

1457 

1458 Filters for the search.

1459 

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

1461 

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

1463 Subdomains of the provided domains are allowed as well.

1464 

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

1466 

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

1468 

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

1470 

1471 - `"low"`

1472 

1473 - `"medium"`

1474 

1475 - `"high"`

1476 

1477 - `user_location: Optional[UserLocation]`

1478 

1479 The approximate location of the user.

1480 

1481 - `city: Optional[str]`

1482 

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

1484 

1485 - `country: Optional[str]`

1486 

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

1488 

1489 - `region: Optional[str]`

1490 

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

1492 

1493 - `timezone: Optional[str]`

1494 

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

1496 

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

1498 

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

1500 

1501 - `"approximate"`

1502 

1503 - `class Mcp: …`

1504 

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

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

1507 

1508 - `server_label: str`

1509 

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

1511 

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

1513 

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

1515 

1516 - `"mcp"`

1517 

1518 - `allowed_tools: Optional[McpAllowedTools]`

1519 

1520 List of allowed tool names or a filter object.

1521 

1522 - `List[str]`

1523 

1524 A string array of allowed tool names

1525 

1526 - `class McpAllowedToolsMcpToolFilter: …`

1527 

1528 A filter object to specify which tools are allowed.

1529 

1530 - `read_only: Optional[bool]`

1531 

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

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

1534 it will match this filter.

1535 

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

1537 

1538 List of allowed tool names.

1539 

1540 - `authorization: Optional[str]`

1541 

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

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

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

1545 

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

1547 

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

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

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

1551 

1552 Currently supported `connector_id` values are:

1553 

1554 - Dropbox: `connector_dropbox`

1555 - Gmail: `connector_gmail`

1556 - Google Calendar: `connector_googlecalendar`

1557 - Google Drive: `connector_googledrive`

1558 - Microsoft Teams: `connector_microsoftteams`

1559 - Outlook Calendar: `connector_outlookcalendar`

1560 - Outlook Email: `connector_outlookemail`

1561 - SharePoint: `connector_sharepoint`

1562 

1563 - `"connector_dropbox"`

1564 

1565 - `"connector_gmail"`

1566 

1567 - `"connector_googlecalendar"`

1568 

1569 - `"connector_googledrive"`

1570 

1571 - `"connector_microsoftteams"`

1572 

1573 - `"connector_outlookcalendar"`

1574 

1575 - `"connector_outlookemail"`

1576 

1577 - `"connector_sharepoint"`

1578 

1579 - `defer_loading: Optional[bool]`

1580 

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

1582 

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

1584 

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

1586 or other purposes.

1587 

1588 - `require_approval: Optional[McpRequireApproval]`

1589 

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

1591 

1592 - `class McpRequireApprovalMcpToolApprovalFilter: …`

1593 

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

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

1596 that require approval.

1597 

1598 - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]`

1599 

1600 A filter object to specify which tools are allowed.

1601 

1602 - `read_only: Optional[bool]`

1603 

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

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

1606 it will match this filter.

1607 

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

1609 

1610 List of allowed tool names.

1611 

1612 - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]`

1613 

1614 A filter object to specify which tools are allowed.

1615 

1616 - `read_only: Optional[bool]`

1617 

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

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

1620 it will match this filter.

1621 

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

1623 

1624 List of allowed tool names.

1625 

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

1627 

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

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

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

1631 

1632 - `"always"`

1633 

1634 - `"never"`

1635 

1636 - `server_description: Optional[str]`

1637 

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

1639 

1640 - `server_url: Optional[str]`

1641 

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

1643 provided.

1644 

1645 - `class CodeInterpreter: …`

1646 

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

1648 

1649 - `container: CodeInterpreterContainer`

1650 

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

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

1653 optional `memory_limit` setting.

1654 

1655 - `str`

1656 

1657 The container ID.

1658 

1659 - `class CodeInterpreterContainerCodeInterpreterToolAuto: …`

1660 

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

1662 

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

1664 

1665 Always `auto`.

1666 

1667 - `"auto"`

1668 

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

1670 

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

1672 

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

1674 

1675 The memory limit for the code interpreter container.

1676 

1677 - `"1g"`

1678 

1679 - `"4g"`

1680 

1681 - `"16g"`

1682 

1683 - `"64g"`

1684 

1685 - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]`

1686 

1687 Network access policy for the container.

1688 

1689 - `class ContainerNetworkPolicyDisabled: …`

1690 

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

1692 

1693 Disable outbound network access. Always `disabled`.

1694 

1695 - `"disabled"`

1696 

1697 - `class ContainerNetworkPolicyAllowlist: …`

1698 

1699 - `allowed_domains: List[str]`

1700 

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

1702 

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

1704 

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

1706 

1707 - `"allowlist"`

1708 

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

1710 

1711 Optional domain-scoped secrets for allowlisted domains.

1712 

1713 - `domain: str`

1714 

1715 The domain associated with the secret.

1716 

1717 - `name: str`

1718 

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

1720 

1721 - `value: str`

1722 

1723 The secret value to inject for the domain.

1724 

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

1726 

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

1728 

1729 - `"code_interpreter"`

1730 

1731 - `class ImageGeneration: …`

1732 

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

1734 

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

1736 

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

1738 

1739 - `"image_generation"`

1740 

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

1742 

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

1744 

1745 - `"generate"`

1746 

1747 - `"edit"`

1748 

1749 - `"auto"`

1750 

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

1752 

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

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

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

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

1757 automatically determine the best background for the image.

1758 

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

1760 transparent backgrounds. Requests with `background` set to

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

1762 `auto` instead.

1763 

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

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

1766 

1767 - `"transparent"`

1768 

1769 - `"opaque"`

1770 

1771 - `"auto"`

1772 

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

1774 

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

1776 

1777 - `"high"`

1778 

1779 - `"low"`

1780 

1781 - `input_image_mask: Optional[ImageGenerationInputImageMask]`

1782 

1783 Optional mask for inpainting. Contains `image_url`

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

1785 

1786 - `file_id: Optional[str]`

1787 

1788 File ID for the mask image.

1789 

1790 - `image_url: Optional[str]`

1791 

1792 Base64-encoded mask image.

1793 

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

1795 

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

1797 

1798 - `str`

1799 

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

1801 

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

1803 

1804 - `"gpt-image-1"`

1805 

1806 - `"gpt-image-1-mini"`

1807 

1808 - `"gpt-image-2"`

1809 

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

1811 

1812 - `"gpt-image-1.5"`

1813 

1814 - `"chatgpt-image-latest"`

1815 

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

1817 

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

1819 

1820 - `"auto"`

1821 

1822 - `"low"`

1823 

1824 - `output_compression: Optional[int]`

1825 

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

1827 

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

1829 

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

1831 `jpeg`. Default: `png`.

1832 

1833 - `"png"`

1834 

1835 - `"webp"`

1836 

1837 - `"jpeg"`

1838 

1839 - `partial_images: Optional[int]`

1840 

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

1842 

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

1844 

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

1846 or `auto`. Default: `auto`.

1847 

1848 - `"low"`

1849 

1850 - `"medium"`

1851 

1852 - `"high"`

1853 

1854 - `"auto"`

1855 

1856 - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]`

1857 

1858 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1859 

1860 - `str`

1861 

1862 - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]`

1863 

1864 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1865 

1866 - `"1024x1024"`

1867 

1868 - `"1024x1536"`

1869 

1870 - `"1536x1024"`

1871 

1872 - `"auto"`

1873 

1874 - `class LocalShell: …`

1875 

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

1877 

1878 - `type: Literal["local_shell"]`

1879 

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

1881 

1882 - `"local_shell"`

1883 

1884 - `class FunctionShellTool: …`

1885 

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

1887 

1888 - `type: Literal["shell"]`

1889 

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

1891 

1892 - `"shell"`

1893 

1894 - `environment: Optional[Environment]`

1895 

1896 - `class ContainerAuto: …`

1897 

1898 - `type: Literal["container_auto"]`

1899 

1900 Automatically creates a container for this request

1901 

1902 - `"container_auto"`

1903 

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

1905 

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

1907 

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

1909 

1910 The memory limit for the container.

1911 

1912 - `"1g"`

1913 

1914 - `"4g"`

1915 

1916 - `"16g"`

1917 

1918 - `"64g"`

1919 

1920 - `network_policy: Optional[NetworkPolicy]`

1921 

1922 Network access policy for the container.

1923 

1924 - `class ContainerNetworkPolicyDisabled: …`

1925 

1926 - `class ContainerNetworkPolicyAllowlist: …`

1927 

1928 - `skills: Optional[List[Skill]]`

1929 

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

1931 

1932 - `class SkillReference: …`

1933 

1934 - `skill_id: str`

1935 

1936 The ID of the referenced skill.

1937 

1938 - `type: Literal["skill_reference"]`

1939 

1940 References a skill created with the /v1/skills endpoint.

1941 

1942 - `"skill_reference"`

1943 

1944 - `version: Optional[str]`

1945 

1946 Optional skill version. Use a positive integer or 'latest'. Omit for default.

1947 

1948 - `class InlineSkill: …`

1949 

1950 - `description: str`

1951 

1952 The description of the skill.

1953 

1954 - `name: str`

1955 

1956 The name of the skill.

1957 

1958 - `source: InlineSkillSource`

1959 

1960 Inline skill payload

1961 

1962 - `data: str`

1963 

1964 Base64-encoded skill zip bundle.

1965 

1966 - `media_type: Literal["application/zip"]`

1967 

1968 The media type of the inline skill payload. Must be `application/zip`.

1969 

1970 - `"application/zip"`

1971 

1972 - `type: Literal["base64"]`

1973 

1974 The type of the inline skill source. Must be `base64`.

1975 

1976 - `"base64"`

1977 

1978 - `type: Literal["inline"]`

1979 

1980 Defines an inline skill for this request.

1981 

1982 - `"inline"`

1983 

1984 - `class LocalEnvironment: …`

1985 

1986 - `type: Literal["local"]`

1987 

1988 Use a local computer environment.

1989 

1990 - `"local"`

1991 

1992 - `skills: Optional[List[LocalSkill]]`

1993 

1994 An optional list of skills.

1995 

1996 - `description: str`