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

1## Cancel a response

2 

3`responses.cancel(strresponse_id) -> Response`

4 

5**post** `/responses/{response_id}/cancel`

6 

7Cancels a model response with the given ID. Only responses created with

8the `background` parameter set to `true` can be cancelled.

9[Learn more](https://platform.openai.com/docs/guides/background).

10 

11### Parameters

12 

13- `response_id: str`

14 

15### Returns

16 

17- `class Response: …`

18 

19 - `id: str`

20 

21 Unique identifier for this Response.

22 

23 - `created_at: float`

24 

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

26 

27 - `error: Optional[ResponseError]`

28 

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

30 

31 - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 15 more]`

32 

33 The error code for the response.

34 

35 - `"server_error"`

36 

37 - `"rate_limit_exceeded"`

38 

39 - `"invalid_prompt"`

40 

41 - `"vector_store_timeout"`

42 

43 - `"invalid_image"`

44 

45 - `"invalid_image_format"`

46 

47 - `"invalid_base64_image"`

48 

49 - `"invalid_image_url"`

50 

51 - `"image_too_large"`

52 

53 - `"image_too_small"`

54 

55 - `"image_parse_error"`

56 

57 - `"image_content_policy_violation"`

58 

59 - `"invalid_image_mode"`

60 

61 - `"image_file_too_large"`

62 

63 - `"unsupported_image_media_type"`

64 

65 - `"empty_image_file"`

66 

67 - `"failed_to_download_image"`

68 

69 - `"image_file_not_found"`

70 

71 - `message: str`

72 

73 A human-readable description of the error.

74 

75 - `incomplete_details: Optional[IncompleteDetails]`

76 

77 Details about why the response is incomplete.

78 

79 - `reason: Optional[Literal["max_output_tokens", "content_filter"]]`

80 

81 The reason why the response is incomplete.

82 

83 - `"max_output_tokens"`

84 

85 - `"content_filter"`

86 

87 - `instructions: Union[str, List[ResponseInputItem], null]`

88 

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

90 

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

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

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

94 

95 - `str`

96 

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

98 `developer` role.

99 

100 - `List[ResponseInputItem]`

101 

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

103 different content types.

104 

105 - `class EasyInputMessage: …`

106 

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

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

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

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

111 interactions.

112 

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

114 

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

116 Can also contain previous assistant responses.

117 

118 - `str`

119 

120 A text input to the model.

121 

122 - `List[ResponseInputContent]`

123 

124 - `class ResponseInputText: …`

125 

126 A text input to the model.

127 

128 - `text: str`

129 

130 The text input to the model.

131 

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

133 

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

135 

136 - `"input_text"`

137 

138 - `class ResponseInputImage: …`

139 

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

141 

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

143 

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

145 

146 - `"low"`

147 

148 - `"high"`

149 

150 - `"auto"`

151 

152 - `"original"`

153 

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

155 

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

157 

158 - `"input_image"`

159 

160 - `file_id: Optional[str]`

161 

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

163 

164 - `image_url: Optional[str]`

165 

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

167 

168 - `class ResponseInputFile: …`

169 

170 A file input to the model.

171 

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

173 

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

175 

176 - `"input_file"`

177 

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

179 

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

181 

182 - `"low"`

183 

184 - `"high"`

185 

186 - `file_data: Optional[str]`

187 

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

189 

190 - `file_id: Optional[str]`

191 

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

193 

194 - `file_url: Optional[str]`

195 

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

197 

198 - `filename: Optional[str]`

199 

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

201 

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

203 

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

205 `developer`.

206 

207 - `"user"`

208 

209 - `"assistant"`

210 

211 - `"system"`

212 

213 - `"developer"`

214 

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

216 

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

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

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

220 

221 - `"commentary"`

222 

223 - `"final_answer"`

224 

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

226 

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

228 

229 - `"message"`

230 

231 - `class Message: …`

232 

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

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

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

236 

237 - `content: ResponseInputMessageContentList`

238 

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

240 types.

241 

242 - `class ResponseInputText: …`

243 

244 A text input to the model.

245 

246 - `class ResponseInputImage: …`

247 

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

249 

250 - `class ResponseInputFile: …`

251 

252 A file input to the model.

253 

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

255 

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

257 

258 - `"user"`

259 

260 - `"system"`

261 

262 - `"developer"`

263 

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

265 

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

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

268 

269 - `"in_progress"`

270 

271 - `"completed"`

272 

273 - `"incomplete"`

274 

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

276 

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

278 

279 - `"message"`

280 

281 - `class ResponseOutputMessage: …`

282 

283 An output message from the model.

284 

285 - `id: str`

286 

287 The unique ID of the output message.

288 

289 - `content: List[Content]`

290 

291 The content of the output message.

292 

293 - `class ResponseOutputText: …`

294 

295 A text output from the model.

296 

297 - `annotations: List[Annotation]`

298 

299 The annotations of the text output.

300 

301 - `class AnnotationFileCitation: …`

302 

303 A citation to a file.

304 

305 - `file_id: str`

306 

307 The ID of the file.

308 

309 - `filename: str`

310 

311 The filename of the file cited.

312 

313 - `index: int`

314 

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

316 

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

318 

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

320 

321 - `"file_citation"`

322 

323 - `class AnnotationURLCitation: …`

324 

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

326 

327 - `end_index: int`

328 

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

330 

331 - `start_index: int`

332 

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

334 

335 - `title: str`

336 

337 The title of the web resource.

338 

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

340 

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

342 

343 - `"url_citation"`

344 

345 - `url: str`

346 

347 The URL of the web resource.

348 

349 - `class AnnotationContainerFileCitation: …`

350 

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

352 

353 - `container_id: str`

354 

355 The ID of the container file.

356 

357 - `end_index: int`

358 

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

360 

361 - `file_id: str`

362 

363 The ID of the file.

364 

365 - `filename: str`

366 

367 The filename of the container file cited.

368 

369 - `start_index: int`

370 

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

372 

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

374 

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

376 

377 - `"container_file_citation"`

378 

379 - `class AnnotationFilePath: …`

380 

381 A path to a file.

382 

383 - `file_id: str`

384 

385 The ID of the file.

386 

387 - `index: int`

388 

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

390 

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

392 

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

394 

395 - `"file_path"`

396 

397 - `text: str`

398 

399 The text output from the model.

400 

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

402 

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

404 

405 - `"output_text"`

406 

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

408 

409 - `token: str`

410 

411 - `bytes: List[int]`

412 

413 - `logprob: float`

414 

415 - `top_logprobs: List[LogprobTopLogprob]`

416 

417 - `token: str`

418 

419 - `bytes: List[int]`

420 

421 - `logprob: float`

422 

423 - `class ResponseOutputRefusal: …`

424 

425 A refusal from the model.

426 

427 - `refusal: str`

428 

429 The refusal explanation from the model.

430 

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

432 

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

434 

435 - `"refusal"`

436 

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

438 

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

440 

441 - `"assistant"`

442 

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

444 

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

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

447 

448 - `"in_progress"`

449 

450 - `"completed"`

451 

452 - `"incomplete"`

453 

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

455 

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

457 

458 - `"message"`

459 

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

461 

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

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

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

465 

466 - `"commentary"`

467 

468 - `"final_answer"`

469 

470 - `class ResponseFileSearchToolCall: …`

471 

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

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

474 

475 - `id: str`

476 

477 The unique ID of the file search tool call.

478 

479 - `queries: List[str]`

480 

481 The queries used to search for files.

482 

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

484 

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

486 `searching`, `incomplete` or `failed`,

487 

488 - `"in_progress"`

489 

490 - `"searching"`

491 

492 - `"completed"`

493 

494 - `"incomplete"`

495 

496 - `"failed"`

497 

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

499 

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

501 

502 - `"file_search_call"`

503 

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

505 

506 The results of the file search tool call.

507 

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

509 

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

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

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

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

514 length of 512 characters, booleans, or numbers.

515 

516 - `str`

517 

518 - `float`

519 

520 - `bool`

521 

522 - `file_id: Optional[str]`

523 

524 The unique ID of the file.

525 

526 - `filename: Optional[str]`

527 

528 The name of the file.

529 

530 - `score: Optional[float]`

531 

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

533 

534 - `text: Optional[str]`

535 

536 The text that was retrieved from the file.

537 

538 - `class ResponseComputerToolCall: …`

539 

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

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

542 

543 - `id: str`

544 

545 The unique ID of the computer call.

546 

547 - `call_id: str`

548 

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

550 

551 - `pending_safety_checks: List[PendingSafetyCheck]`

552 

553 The pending safety checks for the computer call.

554 

555 - `id: str`

556 

557 The ID of the pending safety check.

558 

559 - `code: Optional[str]`

560 

561 The type of the pending safety check.

562 

563 - `message: Optional[str]`

564 

565 Details about the pending safety check.

566 

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

568 

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

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

571 

572 - `"in_progress"`

573 

574 - `"completed"`

575 

576 - `"incomplete"`

577 

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

579 

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

581 

582 - `"computer_call"`

583 

584 - `action: Optional[Action]`

585 

586 A click action.

587 

588 - `class ActionClick: …`

589 

590 A click action.

591 

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

593 

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

595 

596 - `"left"`

597 

598 - `"right"`

599 

600 - `"wheel"`

601 

602 - `"back"`

603 

604 - `"forward"`

605 

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

607 

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

609 

610 - `"click"`

611 

612 - `x: int`

613 

614 The x-coordinate where the click occurred.

615 

616 - `y: int`

617 

618 The y-coordinate where the click occurred.

619 

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

621 

622 The keys being held while clicking.

623 

624 - `class ActionDoubleClick: …`

625 

626 A double click action.

627 

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

629 

630 The keys being held while double-clicking.

631 

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

633 

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

635 

636 - `"double_click"`

637 

638 - `x: int`

639 

640 The x-coordinate where the double click occurred.

641 

642 - `y: int`

643 

644 The y-coordinate where the double click occurred.

645 

646 - `class ActionDrag: …`

647 

648 A drag action.

649 

650 - `path: List[ActionDragPath]`

651 

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

653 

654 ```

655 [

656 { x: 100, y: 200 },

657 { x: 200, y: 300 }

658 ]

659 ```

660 

661 - `x: int`

662 

663 The x-coordinate.

664 

665 - `y: int`

666 

667 The y-coordinate.

668 

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

670 

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

672 

673 - `"drag"`

674 

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

676 

677 The keys being held while dragging the mouse.

678 

679 - `class ActionKeypress: …`

680 

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

682 

683 - `keys: List[str]`

684 

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

686 

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

688 

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

690 

691 - `"keypress"`

692 

693 - `class ActionMove: …`

694 

695 A mouse move action.

696 

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

698 

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

700 

701 - `"move"`

702 

703 - `x: int`

704 

705 The x-coordinate to move to.

706 

707 - `y: int`

708 

709 The y-coordinate to move to.

710 

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

712 

713 The keys being held while moving the mouse.

714 

715 - `class ActionScreenshot: …`

716 

717 A screenshot action.

718 

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

720 

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

722 

723 - `"screenshot"`

724 

725 - `class ActionScroll: …`

726 

727 A scroll action.

728 

729 - `scroll_x: int`

730 

731 The horizontal scroll distance.

732 

733 - `scroll_y: int`

734 

735 The vertical scroll distance.

736 

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

738 

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

740 

741 - `"scroll"`

742 

743 - `x: int`

744 

745 The x-coordinate where the scroll occurred.

746 

747 - `y: int`

748 

749 The y-coordinate where the scroll occurred.

750 

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

752 

753 The keys being held while scrolling.

754 

755 - `class ActionType: …`

756 

757 An action to type in text.

758 

759 - `text: str`

760 

761 The text to type.

762 

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

764 

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

766 

767 - `"type"`

768 

769 - `class ActionWait: …`

770 

771 A wait action.

772 

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

774 

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

776 

777 - `"wait"`

778 

779 - `actions: Optional[ComputerActionList]`

780 

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

782 `type` discriminator and action-specific fields.

783 

784 - `class Click: …`

785 

786 A click action.

787 

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

789 

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

791 

792 - `"left"`

793 

794 - `"right"`

795 

796 - `"wheel"`

797 

798 - `"back"`

799 

800 - `"forward"`

801 

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

803 

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

805 

806 - `"click"`

807 

808 - `x: int`

809 

810 The x-coordinate where the click occurred.

811 

812 - `y: int`

813 

814 The y-coordinate where the click occurred.

815 

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

817 

818 The keys being held while clicking.

819 

820 - `class DoubleClick: …`

821 

822 A double click action.

823 

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

825 

826 The keys being held while double-clicking.

827 

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

829 

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

831 

832 - `"double_click"`

833 

834 - `x: int`

835 

836 The x-coordinate where the double click occurred.

837 

838 - `y: int`

839 

840 The y-coordinate where the double click occurred.

841 

842 - `class Drag: …`

843 

844 A drag action.

845 

846 - `path: List[DragPath]`

847 

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

849 

850 ```

851 [

852 { x: 100, y: 200 },

853 { x: 200, y: 300 }

854 ]

855 ```

856 

857 - `x: int`

858 

859 The x-coordinate.

860 

861 - `y: int`

862 

863 The y-coordinate.

864 

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

866 

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

868 

869 - `"drag"`

870 

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

872 

873 The keys being held while dragging the mouse.

874 

875 - `class Keypress: …`

876 

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

878 

879 - `keys: List[str]`

880 

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

882 

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

884 

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

886 

887 - `"keypress"`

888 

889 - `class Move: …`

890 

891 A mouse move action.

892 

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

894 

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

896 

897 - `"move"`

898 

899 - `x: int`

900 

901 The x-coordinate to move to.

902 

903 - `y: int`

904 

905 The y-coordinate to move to.

906 

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

908 

909 The keys being held while moving the mouse.

910 

911 - `class Screenshot: …`

912 

913 A screenshot action.

914 

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

916 

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

918 

919 - `"screenshot"`

920 

921 - `class Scroll: …`

922 

923 A scroll action.

924 

925 - `scroll_x: int`

926 

927 The horizontal scroll distance.

928 

929 - `scroll_y: int`

930 

931 The vertical scroll distance.

932 

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

934 

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

936 

937 - `"scroll"`

938 

939 - `x: int`

940 

941 The x-coordinate where the scroll occurred.

942 

943 - `y: int`

944 

945 The y-coordinate where the scroll occurred.

946 

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

948 

949 The keys being held while scrolling.

950 

951 - `class Type: …`

952 

953 An action to type in text.

954 

955 - `text: str`

956 

957 The text to type.

958 

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

960 

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

962 

963 - `"type"`

964 

965 - `class Wait: …`

966 

967 A wait action.

968 

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

970 

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

972 

973 - `"wait"`

974 

975 - `class ComputerCallOutput: …`

976 

977 The output of a computer tool call.

978 

979 - `call_id: str`

980 

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

982 

983 - `output: ResponseComputerToolCallOutputScreenshot`

984 

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

986 

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

988 

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

990 always set to `computer_screenshot`.

991 

992 - `"computer_screenshot"`

993 

994 - `file_id: Optional[str]`

995 

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

997 

998 - `image_url: Optional[str]`

999 

1000 The URL of the screenshot image.

1001 

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

1003 

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

1005 

1006 - `"computer_call_output"`

1007 

1008 - `id: Optional[str]`

1009 

1010 The ID of the computer tool call output.

1011 

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

1013 

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

1015 

1016 - `id: str`

1017 

1018 The ID of the pending safety check.

1019 

1020 - `code: Optional[str]`

1021 

1022 The type of the pending safety check.

1023 

1024 - `message: Optional[str]`

1025 

1026 Details about the pending safety check.

1027 

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

1029 

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

1031 

1032 - `"in_progress"`

1033 

1034 - `"completed"`

1035 

1036 - `"incomplete"`

1037 

1038 - `class ResponseFunctionWebSearch: …`

1039 

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

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

1042 

1043 - `id: str`

1044 

1045 The unique ID of the web search tool call.

1046 

1047 - `action: Action`

1048 

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

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

1051 

1052 - `class ActionSearch: …`

1053 

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

1055 

1056 - `query: str`

1057 

1058 [DEPRECATED] The search query.

1059 

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

1061 

1062 The action type.

1063 

1064 - `"search"`

1065 

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

1067 

1068 The search queries.

1069 

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

1071 

1072 The sources used in the search.

1073 

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

1075 

1076 The type of source. Always `url`.

1077 

1078 - `"url"`

1079 

1080 - `url: str`

1081 

1082 The URL of the source.

1083 

1084 - `class ActionOpenPage: …`

1085 

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

1087 

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

1089 

1090 The action type.

1091 

1092 - `"open_page"`

1093 

1094 - `url: Optional[str]`

1095 

1096 The URL opened by the model.

1097 

1098 - `class ActionFindInPage: …`

1099 

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

1101 

1102 - `pattern: str`

1103 

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

1105 

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

1107 

1108 The action type.

1109 

1110 - `"find_in_page"`

1111 

1112 - `url: str`

1113 

1114 The URL of the page searched for the pattern.

1115 

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

1117 

1118 The status of the web search tool call.

1119 

1120 - `"in_progress"`

1121 

1122 - `"searching"`

1123 

1124 - `"completed"`

1125 

1126 - `"failed"`

1127 

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

1129 

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

1131 

1132 - `"web_search_call"`

1133 

1134 - `class ResponseFunctionToolCall: …`

1135 

1136 A tool call to run a function. See the

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

1138 

1139 - `arguments: str`

1140 

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

1142 

1143 - `call_id: str`

1144 

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

1146 

1147 - `name: str`

1148 

1149 The name of the function to run.

1150 

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

1152 

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

1154 

1155 - `"function_call"`

1156 

1157 - `id: Optional[str]`

1158 

1159 The unique ID of the function tool call.

1160 

1161 - `namespace: Optional[str]`

1162 

1163 The namespace of the function to run.

1164 

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

1166 

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

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

1169 

1170 - `"in_progress"`

1171 

1172 - `"completed"`

1173 

1174 - `"incomplete"`

1175 

1176 - `class FunctionCallOutput: …`

1177 

1178 The output of a function tool call.

1179 

1180 - `call_id: str`

1181 

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

1183 

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

1185 

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

1187 

1188 - `str`

1189 

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

1191 

1192 - `List[ResponseFunctionCallOutputItem]`

1193 

1194 - `class ResponseInputTextContent: …`

1195 

1196 A text input to the model.

1197 

1198 - `text: str`

1199 

1200 The text input to the model.

1201 

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

1203 

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

1205 

1206 - `"input_text"`

1207 

1208 - `class ResponseInputImageContent: …`

1209 

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

1211 

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

1213 

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

1215 

1216 - `"input_image"`

1217 

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

1219 

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

1221 

1222 - `"low"`

1223 

1224 - `"high"`

1225 

1226 - `"auto"`

1227 

1228 - `"original"`

1229 

1230 - `file_id: Optional[str]`

1231 

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

1233 

1234 - `image_url: Optional[str]`

1235 

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

1237 

1238 - `class ResponseInputFileContent: …`

1239 

1240 A file input to the model.

1241 

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

1243 

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

1245 

1246 - `"input_file"`

1247 

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

1249 

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

1251 

1252 - `"low"`

1253 

1254 - `"high"`

1255 

1256 - `file_data: Optional[str]`

1257 

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

1259 

1260 - `file_id: Optional[str]`

1261 

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

1263 

1264 - `file_url: Optional[str]`

1265 

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

1267 

1268 - `filename: Optional[str]`

1269 

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

1271 

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

1273 

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

1275 

1276 - `"function_call_output"`

1277 

1278 - `id: Optional[str]`

1279 

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

1281 

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

1283 

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

1285 

1286 - `"in_progress"`

1287 

1288 - `"completed"`

1289 

1290 - `"incomplete"`

1291 

1292 - `class ToolSearchCall: …`

1293 

1294 - `arguments: object`

1295 

1296 The arguments supplied to the tool search call.

1297 

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

1299 

1300 The item type. Always `tool_search_call`.

1301 

1302 - `"tool_search_call"`

1303 

1304 - `id: Optional[str]`

1305 

1306 The unique ID of this tool search call.

1307 

1308 - `call_id: Optional[str]`

1309 

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

1311 

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

1313 

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

1315 

1316 - `"server"`

1317 

1318 - `"client"`

1319 

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

1321 

1322 The status of the tool search call.

1323 

1324 - `"in_progress"`

1325 

1326 - `"completed"`

1327 

1328 - `"incomplete"`

1329 

1330 - `class ResponseToolSearchOutputItemParam: …`

1331 

1332 - `tools: List[Tool]`

1333 

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

1335 

1336 - `class FunctionTool: …`

1337 

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

1339 

1340 - `name: str`

1341 

1342 The name of the function to call.

1343 

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

1345 

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

1347 

1348 - `strict: Optional[bool]`

1349 

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

1351 

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

1353 

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

1355 

1356 - `"function"`

1357 

1358 - `defer_loading: Optional[bool]`

1359 

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

1361 

1362 - `description: Optional[str]`

1363 

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

1365 

1366 - `class FileSearchTool: …`

1367 

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

1369 

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

1371 

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

1373 

1374 - `"file_search"`

1375 

1376 - `vector_store_ids: List[str]`

1377 

1378 The IDs of the vector stores to search.

1379 

1380 - `filters: Optional[Filters]`

1381 

1382 A filter to apply.

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 - `key: str`

1389 

1390 The key to compare against the value.

1391 

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

1393 

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

1395 

1396 - `eq`: equals

1397 - `ne`: not equal

1398 - `gt`: greater than

1399 - `gte`: greater than or equal

1400 - `lt`: less than

1401 - `lte`: less than or equal

1402 - `in`: in

1403 - `nin`: not in

1404 

1405 - `"eq"`

1406 

1407 - `"ne"`

1408 

1409 - `"gt"`

1410 

1411 - `"gte"`

1412 

1413 - `"lt"`

1414 

1415 - `"lte"`

1416 

1417 - `"in"`

1418 

1419 - `"nin"`

1420 

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

1422 

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

1424 

1425 - `str`

1426 

1427 - `float`

1428 

1429 - `bool`

1430 

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

1432 

1433 - `str`

1434 

1435 - `float`

1436 

1437 - `class CompoundFilter: …`

1438 

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

1440 

1441 - `filters: List[Filter]`

1442 

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

1444 

1445 - `class ComparisonFilter: …`

1446 

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

1448 

1449 - `object`

1450 

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

1452 

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

1454 

1455 - `"and"`

1456 

1457 - `"or"`

1458 

1459 - `max_num_results: Optional[int]`

1460 

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

1462 

1463 - `ranking_options: Optional[RankingOptions]`

1464 

1465 Ranking options for search.

1466 

1467 - `hybrid_search: Optional[RankingOptionsHybridSearch]`

1468 

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

1470 

1471 - `embedding_weight: float`

1472 

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

1474 

1475 - `text_weight: float`

1476 

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

1478 

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

1480 

1481 The ranker to use for the file search.

1482 

1483 - `"auto"`

1484 

1485 - `"default-2024-11-15"`

1486 

1487 - `score_threshold: Optional[float]`

1488 

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

1490 

1491 - `class ComputerTool: …`

1492 

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

1494 

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

1496 

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

1498 

1499 - `"computer"`

1500 

1501 - `class ComputerUsePreviewTool: …`

1502 

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

1504 

1505 - `display_height: int`

1506 

1507 The height of the computer display.

1508 

1509 - `display_width: int`

1510 

1511 The width of the computer display.

1512 

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

1514 

1515 The type of computer environment to control.

1516 

1517 - `"windows"`

1518 

1519 - `"mac"`

1520 

1521 - `"linux"`

1522 

1523 - `"ubuntu"`

1524 

1525 - `"browser"`

1526 

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

1528 

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

1530 

1531 - `"computer_use_preview"`

1532 

1533 - `class WebSearchTool: …`

1534 

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

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

1537 

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

1539 

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

1541 

1542 - `"web_search"`

1543 

1544 - `"web_search_2025_08_26"`

1545 

1546 - `filters: Optional[Filters]`

1547 

1548 Filters for the search.

1549 

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

1551 

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

1553 Subdomains of the provided domains are allowed as well.

1554 

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

1556 

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

1558 

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

1560 

1561 - `"low"`

1562 

1563 - `"medium"`

1564 

1565 - `"high"`

1566 

1567 - `user_location: Optional[UserLocation]`

1568 

1569 The approximate location of the user.

1570 

1571 - `city: Optional[str]`

1572 

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

1574 

1575 - `country: Optional[str]`

1576 

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

1578 

1579 - `region: Optional[str]`

1580 

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

1582 

1583 - `timezone: Optional[str]`

1584 

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

1586 

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

1588 

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

1590 

1591 - `"approximate"`

1592 

1593 - `class Mcp: …`

1594 

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

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

1597 

1598 - `server_label: str`

1599 

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

1601 

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

1603 

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

1605 

1606 - `"mcp"`

1607 

1608 - `allowed_tools: Optional[McpAllowedTools]`

1609 

1610 List of allowed tool names or a filter object.

1611 

1612 - `List[str]`

1613 

1614 A string array of allowed tool names

1615 

1616 - `class McpAllowedToolsMcpToolFilter: …`

1617 

1618 A filter object to specify which tools are allowed.

1619 

1620 - `read_only: Optional[bool]`

1621 

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

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

1624 it will match this filter.

1625 

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

1627 

1628 List of allowed tool names.

1629 

1630 - `authorization: Optional[str]`

1631 

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

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

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

1635 

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

1637 

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

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

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

1641 

1642 Currently supported `connector_id` values are:

1643 

1644 - Dropbox: `connector_dropbox`

1645 - Gmail: `connector_gmail`

1646 - Google Calendar: `connector_googlecalendar`

1647 - Google Drive: `connector_googledrive`

1648 - Microsoft Teams: `connector_microsoftteams`

1649 - Outlook Calendar: `connector_outlookcalendar`

1650 - Outlook Email: `connector_outlookemail`

1651 - SharePoint: `connector_sharepoint`

1652 

1653 - `"connector_dropbox"`

1654 

1655 - `"connector_gmail"`

1656 

1657 - `"connector_googlecalendar"`

1658 

1659 - `"connector_googledrive"`

1660 

1661 - `"connector_microsoftteams"`

1662 

1663 - `"connector_outlookcalendar"`

1664 

1665 - `"connector_outlookemail"`

1666 

1667 - `"connector_sharepoint"`

1668 

1669 - `defer_loading: Optional[bool]`

1670 

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

1672 

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

1674 

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

1676 or other purposes.

1677 

1678 - `require_approval: Optional[McpRequireApproval]`

1679 

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

1681 

1682 - `class McpRequireApprovalMcpToolApprovalFilter: …`

1683 

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

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

1686 that require approval.

1687 

1688 - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]`

1689 

1690 A filter object to specify which tools are allowed.

1691 

1692 - `read_only: Optional[bool]`

1693 

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

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

1696 it will match this filter.

1697 

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

1699 

1700 List of allowed tool names.

1701 

1702 - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]`

1703 

1704 A filter object to specify which tools are allowed.

1705 

1706 - `read_only: Optional[bool]`

1707 

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

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

1710 it will match this filter.

1711 

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

1713 

1714 List of allowed tool names.

1715 

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

1717 

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

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

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

1721 

1722 - `"always"`

1723 

1724 - `"never"`

1725 

1726 - `server_description: Optional[str]`

1727 

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

1729 

1730 - `server_url: Optional[str]`

1731 

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

1733 provided.

1734 

1735 - `class CodeInterpreter: …`

1736 

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

1738 

1739 - `container: CodeInterpreterContainer`

1740 

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

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

1743 optional `memory_limit` setting.

1744 

1745 - `str`

1746 

1747 The container ID.

1748 

1749 - `class CodeInterpreterContainerCodeInterpreterToolAuto: …`

1750 

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

1752 

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

1754 

1755 Always `auto`.

1756 

1757 - `"auto"`

1758 

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

1760 

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

1762 

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

1764 

1765 The memory limit for the code interpreter container.

1766 

1767 - `"1g"`

1768 

1769 - `"4g"`

1770 

1771 - `"16g"`

1772 

1773 - `"64g"`

1774 

1775 - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]`

1776 

1777 Network access policy for the container.

1778 

1779 - `class ContainerNetworkPolicyDisabled: …`

1780 

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

1782 

1783 Disable outbound network access. Always `disabled`.

1784 

1785 - `"disabled"`

1786 

1787 - `class ContainerNetworkPolicyAllowlist: …`

1788 

1789 - `allowed_domains: List[str]`

1790 

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

1792 

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

1794 

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

1796 

1797 - `"allowlist"`

1798 

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

1800 

1801 Optional domain-scoped secrets for allowlisted domains.

1802 

1803 - `domain: str`

1804 

1805 The domain associated with the secret.

1806 

1807 - `name: str`

1808 

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

1810 

1811 - `value: str`

1812 

1813 The secret value to inject for the domain.

1814 

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

1816 

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

1818 

1819 - `"code_interpreter"`

1820 

1821 - `class ImageGeneration: …`

1822 

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

1824 

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

1826 

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

1828 

1829 - `"image_generation"`

1830 

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

1832 

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

1834 

1835 - `"generate"`

1836 

1837 - `"edit"`

1838 

1839 - `"auto"`

1840 

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

1842 

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

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

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

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

1847 automatically determine the best background for the image.

1848 

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

1850 transparent backgrounds. Requests with `background` set to

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

1852 `auto` instead.

1853 

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

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

1856 

1857 - `"transparent"`

1858 

1859 - `"opaque"`

1860 

1861 - `"auto"`

1862 

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

1864 

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

1866 

1867 - `"high"`

1868 

1869 - `"low"`

1870 

1871 - `input_image_mask: Optional[ImageGenerationInputImageMask]`

1872 

1873 Optional mask for inpainting. Contains `image_url`

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

1875 

1876 - `file_id: Optional[str]`

1877 

1878 File ID for the mask image.

1879 

1880 - `image_url: Optional[str]`

1881 

1882 Base64-encoded mask image.

1883 

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

1885 

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

1887 

1888 - `str`

1889 

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

1891 

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

1893 

1894 - `"gpt-image-1"`

1895 

1896 - `"gpt-image-1-mini"`

1897 

1898 - `"gpt-image-2"`

1899 

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

1901 

1902 - `"gpt-image-1.5"`

1903 

1904 - `"chatgpt-image-latest"`

1905 

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

1907 

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

1909 

1910 - `"auto"`

1911 

1912 - `"low"`

1913 

1914 - `output_compression: Optional[int]`

1915 

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

1917 

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

1919 

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

1921 `jpeg`. Default: `png`.

1922 

1923 - `"png"`

1924 

1925 - `"webp"`

1926 

1927 - `"jpeg"`

1928 

1929 - `partial_images: Optional[int]`

1930 

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

1932 

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

1934 

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

1936 or `auto`. Default: `auto`.

1937 

1938 - `"low"`

1939 

1940 - `"medium"`

1941 

1942 - `"high"`

1943 

1944 - `"auto"`

1945 

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

1947 

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

1949 

1950 - `str`

1951 

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

1953 

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

1955 

1956 - `"1024x1024"`

1957 

1958 - `"1024x1536"`

1959 

1960 - `"1536x1024"`

1961 

1962 - `"auto"`

1963 

1964 - `class LocalShell: …`

1965 

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

1967 

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

1969 

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

1971 

1972 - `"local_shell"`

1973 

1974 - `class FunctionShellTool: …`

1975 

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

1977 

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

1979 

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

1981 

1982 - `"shell"`

1983 

1984 - `environment: Optional[Environment]`

1985 

1986 - `class ContainerAuto: …`

1987 

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

1989 

1990 Automatically creates a container for this request

1991 

1992 - `"container_auto"`

1993 

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

1995 

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