python/resources/responses/subresources/input_tokens/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

1# Input Tokens

2 

3## Get input token counts

4 

5`responses.input_tokens.count(InputTokenCountParams**kwargs) -> InputTokenCountResponse`

6 

7**post** `/responses/input_tokens`

8 

9Returns input token counts of the request.

10 

11Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count.

12 

13### Parameters

14 

15- `conversation: Optional[Conversation]`

16 

17 The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request.

18 Input items and output items from this response are automatically added to this conversation after this response completes.

19 

20 - `str`

21 

22 The unique ID of the conversation.

23 

24 - `class ResponseConversationParam: …`

25 

26 The conversation that this response belongs to.

27 

28 - `id: str`

29 

30 The unique ID of the conversation.

31 

32- `input: Optional[Union[str, Iterable[ResponseInputItemParam], null]]`

33 

34 Text, image, or file inputs to the model, used to generate a response

35 

36 - `str`

37 

38 A text input to the model, equivalent to a text input with the `user` role.

39 

40 - `Iterable[ResponseInputItemParam]`

41 

42 A list of one or many input items to the model, containing different content types.

43 

44 - `class EasyInputMessage: …`

45 

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

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

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

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

50 interactions.

51 

52 - `content: Union[str, ResponseInputMessageContentList]`

53 

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

55 Can also contain previous assistant responses.

56 

57 - `str`

58 

59 A text input to the model.

60 

61 - `List[ResponseInputContent]`

62 

63 - `class ResponseInputText: …`

64 

65 A text input to the model.

66 

67 - `text: str`

68 

69 The text input to the model.

70 

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

72 

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

74 

75 - `"input_text"`

76 

77 - `class ResponseInputImage: …`

78 

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

80 

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

82 

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

84 

85 - `"low"`

86 

87 - `"high"`

88 

89 - `"auto"`

90 

91 - `"original"`

92 

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

94 

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

96 

97 - `"input_image"`

98 

99 - `file_id: Optional[str]`

100 

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

102 

103 - `image_url: Optional[str]`

104 

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

106 

107 - `class ResponseInputFile: …`

108 

109 A file input to the model.

110 

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

112 

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

114 

115 - `"input_file"`

116 

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

118 

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

120 

121 - `"low"`

122 

123 - `"high"`

124 

125 - `file_data: Optional[str]`

126 

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

128 

129 - `file_id: Optional[str]`

130 

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

132 

133 - `file_url: Optional[str]`

134 

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

136 

137 - `filename: Optional[str]`

138 

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

140 

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

142 

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

144 `developer`.

145 

146 - `"user"`

147 

148 - `"assistant"`

149 

150 - `"system"`

151 

152 - `"developer"`

153 

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

155 

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

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

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

159 

160 - `"commentary"`

161 

162 - `"final_answer"`

163 

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

165 

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

167 

168 - `"message"`

169 

170 - `class Message: …`

171 

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

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

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

175 

176 - `content: ResponseInputMessageContentList`

177 

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

179 types.

180 

181 - `class ResponseInputText: …`

182 

183 A text input to the model.

184 

185 - `class ResponseInputImage: …`

186 

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

188 

189 - `class ResponseInputFile: …`

190 

191 A file input to the model.

192 

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

194 

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

196 

197 - `"user"`

198 

199 - `"system"`

200 

201 - `"developer"`

202 

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

204 

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

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

207 

208 - `"in_progress"`

209 

210 - `"completed"`

211 

212 - `"incomplete"`

213 

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

215 

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

217 

218 - `"message"`

219 

220 - `class ResponseOutputMessage: …`

221 

222 An output message from the model.

223 

224 - `id: str`

225 

226 The unique ID of the output message.

227 

228 - `content: List[Content]`

229 

230 The content of the output message.

231 

232 - `class ResponseOutputText: …`

233 

234 A text output from the model.

235 

236 - `annotations: List[Annotation]`

237 

238 The annotations of the text output.

239 

240 - `class AnnotationFileCitation: …`

241 

242 A citation to a file.

243 

244 - `file_id: str`

245 

246 The ID of the file.

247 

248 - `filename: str`

249 

250 The filename of the file cited.

251 

252 - `index: int`

253 

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

255 

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

257 

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

259 

260 - `"file_citation"`

261 

262 - `class AnnotationURLCitation: …`

263 

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

265 

266 - `end_index: int`

267 

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

269 

270 - `start_index: int`

271 

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

273 

274 - `title: str`

275 

276 The title of the web resource.

277 

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

279 

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

281 

282 - `"url_citation"`

283 

284 - `url: str`

285 

286 The URL of the web resource.

287 

288 - `class AnnotationContainerFileCitation: …`

289 

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

291 

292 - `container_id: str`

293 

294 The ID of the container file.

295 

296 - `end_index: int`

297 

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

299 

300 - `file_id: str`

301 

302 The ID of the file.

303 

304 - `filename: str`

305 

306 The filename of the container file cited.

307 

308 - `start_index: int`

309 

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

311 

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

313 

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

315 

316 - `"container_file_citation"`

317 

318 - `class AnnotationFilePath: …`

319 

320 A path to a file.

321 

322 - `file_id: str`

323 

324 The ID of the file.

325 

326 - `index: int`

327 

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

329 

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

331 

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

333 

334 - `"file_path"`

335 

336 - `text: str`

337 

338 The text output from the model.

339 

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

341 

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

343 

344 - `"output_text"`

345 

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

347 

348 - `token: str`

349 

350 - `bytes: List[int]`

351 

352 - `logprob: float`

353 

354 - `top_logprobs: List[LogprobTopLogprob]`

355 

356 - `token: str`

357 

358 - `bytes: List[int]`

359 

360 - `logprob: float`

361 

362 - `class ResponseOutputRefusal: …`

363 

364 A refusal from the model.

365 

366 - `refusal: str`

367 

368 The refusal explanation from the model.

369 

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

371 

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

373 

374 - `"refusal"`

375 

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

377 

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

379 

380 - `"assistant"`

381 

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

383 

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

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

386 

387 - `"in_progress"`

388 

389 - `"completed"`

390 

391 - `"incomplete"`

392 

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

394 

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

396 

397 - `"message"`

398 

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

400 

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

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

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

404 

405 - `"commentary"`

406 

407 - `"final_answer"`

408 

409 - `class ResponseFileSearchToolCall: …`

410 

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

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

413 

414 - `id: str`

415 

416 The unique ID of the file search tool call.

417 

418 - `queries: List[str]`

419 

420 The queries used to search for files.

421 

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

423 

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

425 `searching`, `incomplete` or `failed`,

426 

427 - `"in_progress"`

428 

429 - `"searching"`

430 

431 - `"completed"`

432 

433 - `"incomplete"`

434 

435 - `"failed"`

436 

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

438 

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

440 

441 - `"file_search_call"`

442 

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

444 

445 The results of the file search tool call.

446 

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

448 

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

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

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

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

453 length of 512 characters, booleans, or numbers.

454 

455 - `str`

456 

457 - `float`

458 

459 - `bool`

460 

461 - `file_id: Optional[str]`

462 

463 The unique ID of the file.

464 

465 - `filename: Optional[str]`

466 

467 The name of the file.

468 

469 - `score: Optional[float]`

470 

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

472 

473 - `text: Optional[str]`

474 

475 The text that was retrieved from the file.

476 

477 - `class ResponseComputerToolCall: …`

478 

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

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

481 

482 - `id: str`

483 

484 The unique ID of the computer call.

485 

486 - `call_id: str`

487 

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

489 

490 - `pending_safety_checks: List[PendingSafetyCheck]`

491 

492 The pending safety checks for the computer call.

493 

494 - `id: str`

495 

496 The ID of the pending safety check.

497 

498 - `code: Optional[str]`

499 

500 The type of the pending safety check.

501 

502 - `message: Optional[str]`

503 

504 Details about the pending safety check.

505 

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

507 

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

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

510 

511 - `"in_progress"`

512 

513 - `"completed"`

514 

515 - `"incomplete"`

516 

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

518 

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

520 

521 - `"computer_call"`

522 

523 - `action: Optional[Action]`

524 

525 A click action.

526 

527 - `class ActionClick: …`

528 

529 A click action.

530 

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

532 

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

534 

535 - `"left"`

536 

537 - `"right"`

538 

539 - `"wheel"`

540 

541 - `"back"`

542 

543 - `"forward"`

544 

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

546 

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

548 

549 - `"click"`

550 

551 - `x: int`

552 

553 The x-coordinate where the click occurred.

554 

555 - `y: int`

556 

557 The y-coordinate where the click occurred.

558 

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

560 

561 The keys being held while clicking.

562 

563 - `class ActionDoubleClick: …`

564 

565 A double click action.

566 

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

568 

569 The keys being held while double-clicking.

570 

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

572 

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

574 

575 - `"double_click"`

576 

577 - `x: int`

578 

579 The x-coordinate where the double click occurred.

580 

581 - `y: int`

582 

583 The y-coordinate where the double click occurred.

584 

585 - `class ActionDrag: …`

586 

587 A drag action.

588 

589 - `path: List[ActionDragPath]`

590 

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

592 

593 ```

594 [

595 { x: 100, y: 200 },

596 { x: 200, y: 300 }

597 ]

598 ```

599 

600 - `x: int`

601 

602 The x-coordinate.

603 

604 - `y: int`

605 

606 The y-coordinate.

607 

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

609 

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

611 

612 - `"drag"`

613 

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

615 

616 The keys being held while dragging the mouse.

617 

618 - `class ActionKeypress: …`

619 

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

621 

622 - `keys: List[str]`

623 

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

625 

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

627 

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

629 

630 - `"keypress"`

631 

632 - `class ActionMove: …`

633 

634 A mouse move action.

635 

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

637 

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

639 

640 - `"move"`

641 

642 - `x: int`

643 

644 The x-coordinate to move to.

645 

646 - `y: int`

647 

648 The y-coordinate to move to.

649 

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

651 

652 The keys being held while moving the mouse.

653 

654 - `class ActionScreenshot: …`

655 

656 A screenshot action.

657 

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

659 

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

661 

662 - `"screenshot"`

663 

664 - `class ActionScroll: …`

665 

666 A scroll action.

667 

668 - `scroll_x: int`

669 

670 The horizontal scroll distance.

671 

672 - `scroll_y: int`

673 

674 The vertical scroll distance.

675 

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

677 

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

679 

680 - `"scroll"`

681 

682 - `x: int`

683 

684 The x-coordinate where the scroll occurred.

685 

686 - `y: int`

687 

688 The y-coordinate where the scroll occurred.

689 

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

691 

692 The keys being held while scrolling.

693 

694 - `class ActionType: …`

695 

696 An action to type in text.

697 

698 - `text: str`

699 

700 The text to type.

701 

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

703 

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

705 

706 - `"type"`

707 

708 - `class ActionWait: …`

709 

710 A wait action.

711 

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

713 

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

715 

716 - `"wait"`

717 

718 - `actions: Optional[ComputerActionList]`

719 

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

721 `type` discriminator and action-specific fields.

722 

723 - `class Click: …`

724 

725 A click action.

726 

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

728 

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

730 

731 - `"left"`

732 

733 - `"right"`

734 

735 - `"wheel"`

736 

737 - `"back"`

738 

739 - `"forward"`

740 

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

742 

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

744 

745 - `"click"`

746 

747 - `x: int`

748 

749 The x-coordinate where the click occurred.

750 

751 - `y: int`

752 

753 The y-coordinate where the click occurred.

754 

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

756 

757 The keys being held while clicking.

758 

759 - `class DoubleClick: …`

760 

761 A double click action.

762 

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

764 

765 The keys being held while double-clicking.

766 

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

768 

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

770 

771 - `"double_click"`

772 

773 - `x: int`

774 

775 The x-coordinate where the double click occurred.

776 

777 - `y: int`

778 

779 The y-coordinate where the double click occurred.

780 

781 - `class Drag: …`

782 

783 A drag action.

784 

785 - `path: List[DragPath]`

786 

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

788 

789 ```

790 [

791 { x: 100, y: 200 },

792 { x: 200, y: 300 }

793 ]

794 ```

795 

796 - `x: int`

797 

798 The x-coordinate.

799 

800 - `y: int`

801 

802 The y-coordinate.

803 

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

805 

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

807 

808 - `"drag"`

809 

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

811 

812 The keys being held while dragging the mouse.

813 

814 - `class Keypress: …`

815 

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

817 

818 - `keys: List[str]`

819 

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

821 

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

823 

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

825 

826 - `"keypress"`

827 

828 - `class Move: …`

829 

830 A mouse move action.

831 

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

833 

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

835 

836 - `"move"`

837 

838 - `x: int`

839 

840 The x-coordinate to move to.

841 

842 - `y: int`

843 

844 The y-coordinate to move to.

845 

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

847 

848 The keys being held while moving the mouse.

849 

850 - `class Screenshot: …`

851 

852 A screenshot action.

853 

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

855 

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

857 

858 - `"screenshot"`

859 

860 - `class Scroll: …`

861 

862 A scroll action.

863 

864 - `scroll_x: int`

865 

866 The horizontal scroll distance.

867 

868 - `scroll_y: int`

869 

870 The vertical scroll distance.

871 

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

873 

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

875 

876 - `"scroll"`

877 

878 - `x: int`

879 

880 The x-coordinate where the scroll occurred.

881 

882 - `y: int`

883 

884 The y-coordinate where the scroll occurred.

885 

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

887 

888 The keys being held while scrolling.

889 

890 - `class Type: …`

891 

892 An action to type in text.

893 

894 - `text: str`

895 

896 The text to type.

897 

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

899 

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

901 

902 - `"type"`

903 

904 - `class Wait: …`

905 

906 A wait action.

907 

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

909 

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

911 

912 - `"wait"`

913 

914 - `class ComputerCallOutput: …`

915 

916 The output of a computer tool call.

917 

918 - `call_id: str`

919 

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

921 

922 - `output: ResponseComputerToolCallOutputScreenshot`

923 

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

925 

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

927 

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

929 always set to `computer_screenshot`.

930 

931 - `"computer_screenshot"`

932 

933 - `file_id: Optional[str]`

934 

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

936 

937 - `image_url: Optional[str]`

938 

939 The URL of the screenshot image.

940 

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

942 

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

944 

945 - `"computer_call_output"`

946 

947 - `id: Optional[str]`

948 

949 The ID of the computer tool call output.

950 

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

952 

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

954 

955 - `id: str`

956 

957 The ID of the pending safety check.

958 

959 - `code: Optional[str]`

960 

961 The type of the pending safety check.

962 

963 - `message: Optional[str]`

964 

965 Details about the pending safety check.

966 

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

968 

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

970 

971 - `"in_progress"`

972 

973 - `"completed"`

974 

975 - `"incomplete"`

976 

977 - `class ResponseFunctionWebSearch: …`

978 

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

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

981 

982 - `id: str`

983 

984 The unique ID of the web search tool call.

985 

986 - `action: Action`

987 

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

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

990 

991 - `class ActionSearch: …`

992 

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

994 

995 - `query: str`

996 

997 [DEPRECATED] The search query.

998 

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

1000 

1001 The action type.

1002 

1003 - `"search"`

1004 

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

1006 

1007 The search queries.

1008 

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

1010 

1011 The sources used in the search.

1012 

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

1014 

1015 The type of source. Always `url`.

1016 

1017 - `"url"`

1018 

1019 - `url: str`

1020 

1021 The URL of the source.

1022 

1023 - `class ActionOpenPage: …`

1024 

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

1026 

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

1028 

1029 The action type.

1030 

1031 - `"open_page"`

1032 

1033 - `url: Optional[str]`

1034 

1035 The URL opened by the model.

1036 

1037 - `class ActionFindInPage: …`

1038 

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

1040 

1041 - `pattern: str`

1042 

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

1044 

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

1046 

1047 The action type.

1048 

1049 - `"find_in_page"`

1050 

1051 - `url: str`

1052 

1053 The URL of the page searched for the pattern.

1054 

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

1056 

1057 The status of the web search tool call.

1058 

1059 - `"in_progress"`

1060 

1061 - `"searching"`

1062 

1063 - `"completed"`

1064 

1065 - `"failed"`

1066 

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

1068 

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

1070 

1071 - `"web_search_call"`

1072 

1073 - `class ResponseFunctionToolCall: …`

1074 

1075 A tool call to run a function. See the

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

1077 

1078 - `arguments: str`

1079 

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

1081 

1082 - `call_id: str`

1083 

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

1085 

1086 - `name: str`

1087 

1088 The name of the function to run.

1089 

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

1091 

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

1093 

1094 - `"function_call"`

1095 

1096 - `id: Optional[str]`

1097 

1098 The unique ID of the function tool call.

1099 

1100 - `namespace: Optional[str]`

1101 

1102 The namespace of the function to run.

1103 

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

1105 

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

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

1108 

1109 - `"in_progress"`

1110 

1111 - `"completed"`

1112 

1113 - `"incomplete"`

1114 

1115 - `class FunctionCallOutput: …`

1116 

1117 The output of a function tool call.

1118 

1119 - `call_id: str`

1120 

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

1122 

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

1124 

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

1126 

1127 - `str`

1128 

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

1130 

1131 - `List[ResponseFunctionCallOutputItem]`

1132 

1133 - `class ResponseInputTextContent: …`

1134 

1135 A text input to the model.

1136 

1137 - `text: str`

1138 

1139 The text input to the model.

1140 

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

1142 

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

1144 

1145 - `"input_text"`

1146 

1147 - `class ResponseInputImageContent: …`

1148 

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

1150 

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

1152 

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

1154 

1155 - `"input_image"`

1156 

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

1158 

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

1160 

1161 - `"low"`

1162 

1163 - `"high"`

1164 

1165 - `"auto"`

1166 

1167 - `"original"`

1168 

1169 - `file_id: Optional[str]`

1170 

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

1172 

1173 - `image_url: Optional[str]`

1174 

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

1176 

1177 - `class ResponseInputFileContent: …`

1178 

1179 A file input to the model.

1180 

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

1182 

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

1184 

1185 - `"input_file"`

1186 

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

1188 

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

1190 

1191 - `"low"`

1192 

1193 - `"high"`

1194 

1195 - `file_data: Optional[str]`

1196 

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

1198 

1199 - `file_id: Optional[str]`

1200 

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

1202 

1203 - `file_url: Optional[str]`

1204 

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

1206 

1207 - `filename: Optional[str]`

1208 

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

1210 

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

1212 

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

1214 

1215 - `"function_call_output"`

1216 

1217 - `id: Optional[str]`

1218 

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

1220 

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

1222 

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

1224 

1225 - `"in_progress"`

1226 

1227 - `"completed"`

1228 

1229 - `"incomplete"`

1230 

1231 - `class ToolSearchCall: …`

1232 

1233 - `arguments: object`

1234 

1235 The arguments supplied to the tool search call.

1236 

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

1238 

1239 The item type. Always `tool_search_call`.

1240 

1241 - `"tool_search_call"`

1242 

1243 - `id: Optional[str]`

1244 

1245 The unique ID of this tool search call.

1246 

1247 - `call_id: Optional[str]`

1248 

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

1250 

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

1252 

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

1254 

1255 - `"server"`

1256 

1257 - `"client"`

1258 

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

1260 

1261 The status of the tool search call.

1262 

1263 - `"in_progress"`

1264 

1265 - `"completed"`

1266 

1267 - `"incomplete"`

1268 

1269 - `class ResponseToolSearchOutputItemParam: …`

1270 

1271 - `tools: List[Tool]`

1272 

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

1274 

1275 - `class FunctionTool: …`

1276 

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

1278 

1279 - `name: str`

1280 

1281 The name of the function to call.

1282 

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

1284 

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

1286 

1287 - `strict: Optional[bool]`

1288 

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

1290 

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

1292 

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

1294 

1295 - `"function"`

1296 

1297 - `defer_loading: Optional[bool]`

1298 

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

1300 

1301 - `description: Optional[str]`

1302 

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

1304 

1305 - `class FileSearchTool: …`

1306 

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

1308 

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

1310 

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

1312 

1313 - `"file_search"`

1314 

1315 - `vector_store_ids: List[str]`

1316 

1317 The IDs of the vector stores to search.

1318 

1319 - `filters: Optional[Filters]`

1320 

1321 A filter to apply.

1322 

1323 - `class ComparisonFilter: …`

1324 

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

1326 

1327 - `key: str`

1328 

1329 The key to compare against the value.

1330 

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

1332 

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

1334 

1335 - `eq`: equals

1336 - `ne`: not equal

1337 - `gt`: greater than

1338 - `gte`: greater than or equal

1339 - `lt`: less than

1340 - `lte`: less than or equal

1341 - `in`: in

1342 - `nin`: not in

1343 

1344 - `"eq"`

1345 

1346 - `"ne"`

1347 

1348 - `"gt"`

1349 

1350 - `"gte"`

1351 

1352 - `"lt"`

1353 

1354 - `"lte"`

1355 

1356 - `"in"`

1357 

1358 - `"nin"`

1359 

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

1361 

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

1363 

1364 - `str`

1365 

1366 - `float`

1367 

1368 - `bool`

1369 

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

1371 

1372 - `str`

1373 

1374 - `float`

1375 

1376 - `class CompoundFilter: …`

1377 

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

1379 

1380 - `filters: List[Filter]`

1381 

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

1383 

1384 - `class ComparisonFilter: …`

1385 

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

1387 

1388 - `object`

1389 

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

1391 

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

1393 

1394 - `"and"`

1395 

1396 - `"or"`

1397 

1398 - `max_num_results: Optional[int]`

1399 

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

1401 

1402 - `ranking_options: Optional[RankingOptions]`

1403 

1404 Ranking options for search.

1405 

1406 - `hybrid_search: Optional[RankingOptionsHybridSearch]`

1407 

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

1409 

1410 - `embedding_weight: float`

1411 

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

1413 

1414 - `text_weight: float`

1415 

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

1417 

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

1419 

1420 The ranker to use for the file search.

1421 

1422 - `"auto"`

1423 

1424 - `"default-2024-11-15"`

1425 

1426 - `score_threshold: Optional[float]`

1427 

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

1429 

1430 - `class ComputerTool: …`

1431 

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

1433 

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

1435 

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

1437 

1438 - `"computer"`

1439 

1440 - `class ComputerUsePreviewTool: …`

1441 

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

1443 

1444 - `display_height: int`

1445 

1446 The height of the computer display.

1447 

1448 - `display_width: int`

1449 

1450 The width of the computer display.

1451 

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

1453 

1454 The type of computer environment to control.

1455 

1456 - `"windows"`

1457 

1458 - `"mac"`

1459 

1460 - `"linux"`

1461 

1462 - `"ubuntu"`

1463 

1464 - `"browser"`

1465 

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

1467 

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

1469 

1470 - `"computer_use_preview"`

1471 

1472 - `class WebSearchTool: …`

1473 

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

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

1476 

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

1478 

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

1480 

1481 - `"web_search"`

1482 

1483 - `"web_search_2025_08_26"`

1484 

1485 - `filters: Optional[Filters]`

1486 

1487 Filters for the search.

1488 

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

1490 

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

1492 Subdomains of the provided domains are allowed as well.

1493 

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

1495 

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

1497 

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

1499 

1500 - `"low"`

1501 

1502 - `"medium"`

1503 

1504 - `"high"`

1505 

1506 - `user_location: Optional[UserLocation]`

1507 

1508 The approximate location of the user.

1509 

1510 - `city: Optional[str]`

1511 

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

1513 

1514 - `country: Optional[str]`

1515 

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

1517 

1518 - `region: Optional[str]`

1519 

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

1521 

1522 - `timezone: Optional[str]`

1523 

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

1525 

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

1527 

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

1529 

1530 - `"approximate"`

1531 

1532 - `class Mcp: …`

1533 

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

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

1536 

1537 - `server_label: str`

1538 

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

1540 

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

1542 

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

1544 

1545 - `"mcp"`

1546 

1547 - `allowed_tools: Optional[McpAllowedTools]`

1548 

1549 List of allowed tool names or a filter object.

1550 

1551 - `List[str]`

1552 

1553 A string array of allowed tool names

1554 

1555 - `class McpAllowedToolsMcpToolFilter: …`

1556 

1557 A filter object to specify which tools are allowed.

1558 

1559 - `read_only: Optional[bool]`

1560 

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

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

1563 it will match this filter.

1564 

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

1566 

1567 List of allowed tool names.

1568 

1569 - `authorization: Optional[str]`

1570 

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

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

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

1574 

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

1576 

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

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

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

1580 

1581 Currently supported `connector_id` values are:

1582 

1583 - Dropbox: `connector_dropbox`

1584 - Gmail: `connector_gmail`

1585 - Google Calendar: `connector_googlecalendar`

1586 - Google Drive: `connector_googledrive`

1587 - Microsoft Teams: `connector_microsoftteams`

1588 - Outlook Calendar: `connector_outlookcalendar`

1589 - Outlook Email: `connector_outlookemail`

1590 - SharePoint: `connector_sharepoint`

1591 

1592 - `"connector_dropbox"`

1593 

1594 - `"connector_gmail"`

1595 

1596 - `"connector_googlecalendar"`

1597 

1598 - `"connector_googledrive"`

1599 

1600 - `"connector_microsoftteams"`

1601 

1602 - `"connector_outlookcalendar"`

1603 

1604 - `"connector_outlookemail"`

1605 

1606 - `"connector_sharepoint"`

1607 

1608 - `defer_loading: Optional[bool]`

1609 

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

1611 

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

1613 

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

1615 or other purposes.

1616 

1617 - `require_approval: Optional[McpRequireApproval]`

1618 

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

1620 

1621 - `class McpRequireApprovalMcpToolApprovalFilter: …`

1622 

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

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

1625 that require approval.

1626 

1627 - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]`

1628 

1629 A filter object to specify which tools are allowed.

1630 

1631 - `read_only: Optional[bool]`

1632 

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

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

1635 it will match this filter.

1636 

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

1638 

1639 List of allowed tool names.

1640 

1641 - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]`

1642 

1643 A filter object to specify which tools are allowed.

1644 

1645 - `read_only: Optional[bool]`

1646 

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

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

1649 it will match this filter.

1650 

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

1652 

1653 List of allowed tool names.

1654 

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

1656 

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

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

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

1660 

1661 - `"always"`

1662 

1663 - `"never"`

1664 

1665 - `server_description: Optional[str]`

1666 

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

1668 

1669 - `server_url: Optional[str]`

1670 

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

1672 provided.

1673 

1674 - `class CodeInterpreter: …`

1675 

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

1677 

1678 - `container: CodeInterpreterContainer`

1679 

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

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

1682 optional `memory_limit` setting.

1683 

1684 - `str`

1685 

1686 The container ID.

1687 

1688 - `class CodeInterpreterContainerCodeInterpreterToolAuto: …`

1689 

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

1691 

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

1693 

1694 Always `auto`.

1695 

1696 - `"auto"`

1697 

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

1699 

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

1701 

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

1703 

1704 The memory limit for the code interpreter container.

1705 

1706 - `"1g"`

1707 

1708 - `"4g"`

1709 

1710 - `"16g"`

1711 

1712 - `"64g"`

1713 

1714 - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]`

1715 

1716 Network access policy for the container.

1717 

1718 - `class ContainerNetworkPolicyDisabled: …`

1719 

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

1721 

1722 Disable outbound network access. Always `disabled`.

1723 

1724 - `"disabled"`

1725 

1726 - `class ContainerNetworkPolicyAllowlist: …`

1727 

1728 - `allowed_domains: List[str]`

1729 

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

1731 

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

1733 

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

1735 

1736 - `"allowlist"`

1737 

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

1739 

1740 Optional domain-scoped secrets for allowlisted domains.

1741 

1742 - `domain: str`

1743 

1744 The domain associated with the secret.

1745 

1746 - `name: str`

1747 

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

1749 

1750 - `value: str`

1751 

1752 The secret value to inject for the domain.

1753 

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

1755 

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

1757 

1758 - `"code_interpreter"`

1759 

1760 - `class ImageGeneration: …`

1761 

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

1763 

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

1765 

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

1767 

1768 - `"image_generation"`

1769 

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

1771 

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

1773 

1774 - `"generate"`

1775 

1776 - `"edit"`

1777 

1778 - `"auto"`

1779 

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

1781 

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

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

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

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

1786 automatically determine the best background for the image.

1787 

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

1789 transparent backgrounds. Requests with `background` set to

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

1791 `auto` instead.

1792 

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

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

1795 

1796 - `"transparent"`

1797 

1798 - `"opaque"`

1799 

1800 - `"auto"`

1801 

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

1803 

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

1805 

1806 - `"high"`

1807 

1808 - `"low"`

1809 

1810 - `input_image_mask: Optional[ImageGenerationInputImageMask]`

1811 

1812 Optional mask for inpainting. Contains `image_url`

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

1814 

1815 - `file_id: Optional[str]`

1816 

1817 File ID for the mask image.

1818 

1819 - `image_url: Optional[str]`

1820 

1821 Base64-encoded mask image.

1822 

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

1824 

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

1826 

1827 - `str`

1828 

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

1830 

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

1832 

1833 - `"gpt-image-1"`

1834 

1835 - `"gpt-image-1-mini"`

1836 

1837 - `"gpt-image-2"`

1838 

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

1840 

1841 - `"gpt-image-1.5"`

1842 

1843 - `"chatgpt-image-latest"`

1844 

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

1846 

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

1848 

1849 - `"auto"`

1850 

1851 - `"low"`

1852 

1853 - `output_compression: Optional[int]`

1854 

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

1856 

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

1858 

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

1860 `jpeg`. Default: `png`.

1861 

1862 - `"png"`

1863 

1864 - `"webp"`

1865 

1866 - `"jpeg"`

1867 

1868 - `partial_images: Optional[int]`

1869 

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

1871 

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

1873 

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

1875 or `auto`. Default: `auto`.

1876 

1877 - `"low"`

1878 

1879 - `"medium"`

1880 

1881 - `"high"`

1882 

1883 - `"auto"`

1884 

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

1886 

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

1888 

1889 - `str`

1890 

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

1892 

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

1894 

1895 - `"1024x1024"`

1896 

1897 - `"1024x1536"`

1898 

1899 - `"1536x1024"`

1900 

1901 - `"auto"`

1902 

1903 - `class LocalShell: …`

1904 

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

1906 

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

1908 

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

1910 

1911 - `"local_shell"`

1912 

1913 - `class FunctionShellTool: …`

1914 

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

1916 

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

1918 

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

1920 

1921 - `"shell"`

1922 

1923 - `environment: Optional[Environment]`

1924 

1925 - `class ContainerAuto: …`

1926 

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

1928 

1929 Automatically creates a container for this request

1930 

1931 - `"container_auto"`

1932 

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

1934 

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

1936 

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

1938 

1939 The memory limit for the container.

1940 

1941 - `"1g"`

1942 

1943 - `"4g"`

1944 

1945 - `"16g"`

1946 

1947 - `"64g"`

1948 

1949 - `network_policy: Optional[NetworkPolicy]`

1950 

1951 Network access policy for the container.

1952 

1953 - `class ContainerNetworkPolicyDisabled: …`

1954 

1955 - `class ContainerNetworkPolicyAllowlist: …`

1956 

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

1958 

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

1960 

1961 - `class SkillReference: …`

1962 

1963 - `skill_id: str`

1964 

1965 The ID of the referenced skill.

1966 

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

1968 

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

1970 

1971 - `"skill_reference"`

1972 

1973 - `version: Optional[str]`

1974 

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

1976 

1977 - `class InlineSkill: …`

1978 

1979 - `description: str`

1980 

1981 The description of the skill.

1982 

1983 - `name: str`

1984 

1985 The name of the skill.

1986 

1987 - `source: InlineSkillSource`

1988 

1989 Inline skill payload

1990 

1991 - `data: str`

1992 

1993 Base64-encoded skill zip bundle.

1994 

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

1996