cli/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`$ openai responses cancel`

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: string`

14 

15 The ID of the response to cancel.

16 

17### Returns

18 

19- `response: object { id, created_at, error, 29 more }`

20 

21 - `id: string`

22 

23 Unique identifier for this Response.

24 

25 - `created_at: number`

26 

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

28 

29 - `error: object { code, message }`

30 

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

32 

33 - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 15 more`

34 

35 The error code for the response.

36 

37 - `"server_error"`

38 

39 - `"rate_limit_exceeded"`

40 

41 - `"invalid_prompt"`

42 

43 - `"vector_store_timeout"`

44 

45 - `"invalid_image"`

46 

47 - `"invalid_image_format"`

48 

49 - `"invalid_base64_image"`

50 

51 - `"invalid_image_url"`

52 

53 - `"image_too_large"`

54 

55 - `"image_too_small"`

56 

57 - `"image_parse_error"`

58 

59 - `"image_content_policy_violation"`

60 

61 - `"invalid_image_mode"`

62 

63 - `"image_file_too_large"`

64 

65 - `"unsupported_image_media_type"`

66 

67 - `"empty_image_file"`

68 

69 - `"failed_to_download_image"`

70 

71 - `"image_file_not_found"`

72 

73 - `message: string`

74 

75 A human-readable description of the error.

76 

77 - `incomplete_details: object { reason }`

78 

79 Details about why the response is incomplete.

80 

81 - `reason: optional "max_output_tokens" or "content_filter"`

82 

83 The reason why the response is incomplete.

84 

85 - `"max_output_tokens"`

86 

87 - `"content_filter"`

88 

89 - `instructions: string or array of ResponseInputItem`

90 

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

92 

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

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

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

96 

97 - `union_member_0: string`

98 

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

100 `developer` role.

101 

102 - `Input item list: array of ResponseInputItem`

103 

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

105 different content types.

106 

107 - `easy_input_message: object { content, role, phase, type }`

108 

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

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

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

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

113 interactions.

114 

115 - `content: string or ResponseInputMessageContentList`

116 

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

118 Can also contain previous assistant responses.

119 

120 - `Text input: string`

121 

122 A text input to the model.

123 

124 - `response_input_message_content_list: array of ResponseInputContent`

125 

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

127 types.

128 

129 - `response_input_text: object { text, type }`

130 

131 A text input to the model.

132 

133 - `text: string`

134 

135 The text input to the model.

136 

137 - `type: "input_text"`

138 

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

140 

141 - `response_input_image: object { detail, type, file_id, image_url }`

142 

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

144 

145 - `detail: "low" or "high" or "auto" or "original"`

146 

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

148 

149 - `"low"`

150 

151 - `"high"`

152 

153 - `"auto"`

154 

155 - `"original"`

156 

157 - `type: "input_image"`

158 

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

160 

161 - `file_id: optional string`

162 

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

164 

165 - `image_url: optional string`

166 

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

168 

169 - `response_input_file: object { type, detail, file_data, 3 more }`

170 

171 A file input to the model.

172 

173 - `type: "input_file"`

174 

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

176 

177 - `detail: optional "low" or "high"`

178 

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

180 

181 - `"low"`

182 

183 - `"high"`

184 

185 - `file_data: optional string`

186 

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

188 

189 - `file_id: optional string`

190 

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

192 

193 - `file_url: optional string`

194 

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

196 

197 - `filename: optional string`

198 

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

200 

201 - `role: "user" or "assistant" or "system" or "developer"`

202 

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

204 `developer`.

205 

206 - `"user"`

207 

208 - `"assistant"`

209 

210 - `"system"`

211 

212 - `"developer"`

213 

214 - `phase: optional "commentary" or "final_answer"`

215 

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

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

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

219 

220 - `"commentary"`

221 

222 - `"final_answer"`

223 

224 - `type: optional "message"`

225 

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

227 

228 - `"message"`

229 

230 - `message: object { content, role, status, type }`

231 

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

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

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

235 

236 - `content: array of ResponseInputContent`

237 

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

239 types.

240 

241 - `response_input_text: object { text, type }`

242 

243 A text input to the model.

244 

245 - `response_input_image: object { detail, type, file_id, image_url }`

246 

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

248 

249 - `response_input_file: object { type, detail, file_data, 3 more }`

250 

251 A file input to the model.

252 

253 - `role: "user" or "system" or "developer"`

254 

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

256 

257 - `"user"`

258 

259 - `"system"`

260 

261 - `"developer"`

262 

263 - `status: optional "in_progress" or "completed" or "incomplete"`

264 

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

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

267 

268 - `"in_progress"`

269 

270 - `"completed"`

271 

272 - `"incomplete"`

273 

274 - `type: optional "message"`

275 

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

277 

278 - `"message"`

279 

280 - `response_output_message: object { id, content, role, 3 more }`

281 

282 An output message from the model.

283 

284 - `id: string`

285 

286 The unique ID of the output message.

287 

288 - `content: array of ResponseOutputText or ResponseOutputRefusal`

289 

290 The content of the output message.

291 

292 - `response_output_text: object { annotations, text, type, logprobs }`

293 

294 A text output from the model.

295 

296 - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }`

297 

298 The annotations of the text output.

299 

300 - `file_citation: object { file_id, filename, index, type }`

301 

302 A citation to a file.

303 

304 - `file_id: string`

305 

306 The ID of the file.

307 

308 - `filename: string`

309 

310 The filename of the file cited.

311 

312 - `index: number`

313 

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

315 

316 - `type: "file_citation"`

317 

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

319 

320 - `url_citation: object { end_index, start_index, title, 2 more }`

321 

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

323 

324 - `end_index: number`

325 

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

327 

328 - `start_index: number`

329 

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

331 

332 - `title: string`

333 

334 The title of the web resource.

335 

336 - `type: "url_citation"`

337 

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

339 

340 - `url: string`

341 

342 The URL of the web resource.

343 

344 - `container_file_citation: object { container_id, end_index, file_id, 3 more }`

345 

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

347 

348 - `container_id: string`

349 

350 The ID of the container file.

351 

352 - `end_index: number`

353 

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

355 

356 - `file_id: string`

357 

358 The ID of the file.

359 

360 - `filename: string`

361 

362 The filename of the container file cited.

363 

364 - `start_index: number`

365 

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

367 

368 - `type: "container_file_citation"`

369 

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

371 

372 - `file_path: object { file_id, index, type }`

373 

374 A path to a file.

375 

376 - `file_id: string`

377 

378 The ID of the file.

379 

380 - `index: number`

381 

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

383 

384 - `type: "file_path"`

385 

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

387 

388 - `text: string`

389 

390 The text output from the model.

391 

392 - `type: "output_text"`

393 

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

395 

396 - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }`

397 

398 - `token: string`

399 

400 - `bytes: array of number`

401 

402 - `logprob: number`

403 

404 - `top_logprobs: array of object { token, bytes, logprob }`

405 

406 - `token: string`

407 

408 - `bytes: array of number`

409 

410 - `logprob: number`

411 

412 - `response_output_refusal: object { refusal, type }`

413 

414 A refusal from the model.

415 

416 - `refusal: string`

417 

418 The refusal explanation from the model.

419 

420 - `type: "refusal"`

421 

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

423 

424 - `role: "assistant"`

425 

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

427 

428 - `status: "in_progress" or "completed" or "incomplete"`

429 

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

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

432 

433 - `"in_progress"`

434 

435 - `"completed"`

436 

437 - `"incomplete"`

438 

439 - `type: "message"`

440 

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

442 

443 - `phase: optional "commentary" or "final_answer"`

444 

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

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

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

448 

449 - `"commentary"`

450 

451 - `"final_answer"`

452 

453 - `response_file_search_tool_call: object { id, queries, status, 2 more }`

454 

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

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

457 

458 - `id: string`

459 

460 The unique ID of the file search tool call.

461 

462 - `queries: array of string`

463 

464 The queries used to search for files.

465 

466 - `status: "in_progress" or "searching" or "completed" or 2 more`

467 

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

469 `searching`, `incomplete` or `failed`,

470 

471 - `"in_progress"`

472 

473 - `"searching"`

474 

475 - `"completed"`

476 

477 - `"incomplete"`

478 

479 - `"failed"`

480 

481 - `type: "file_search_call"`

482 

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

484 

485 - `results: optional array of object { attributes, file_id, filename, 2 more }`

486 

487 The results of the file search tool call.

488 

489 - `attributes: optional map[string or number or boolean]`

490 

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

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

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

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

495 length of 512 characters, booleans, or numbers.

496 

497 - `union_member_0: string`

498 

499 - `union_member_1: number`

500 

501 - `union_member_2: boolean`

502 

503 - `file_id: optional string`

504 

505 The unique ID of the file.

506 

507 - `filename: optional string`

508 

509 The name of the file.

510 

511 - `score: optional number`

512 

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

514 

515 - `text: optional string`

516 

517 The text that was retrieved from the file.

518 

519 - `response_computer_tool_call: object { id, call_id, pending_safety_checks, 4 more }`

520 

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

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

523 

524 - `id: string`

525 

526 The unique ID of the computer call.

527 

528 - `call_id: string`

529 

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

531 

532 - `pending_safety_checks: array of object { id, code, message }`

533 

534 The pending safety checks for the computer call.

535 

536 - `id: string`

537 

538 The ID of the pending safety check.

539 

540 - `code: optional string`

541 

542 The type of the pending safety check.

543 

544 - `message: optional string`

545 

546 Details about the pending safety check.

547 

548 - `status: "in_progress" or "completed" or "incomplete"`

549 

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

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

552 

553 - `"in_progress"`

554 

555 - `"completed"`

556 

557 - `"incomplete"`

558 

559 - `type: "computer_call"`

560 

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

562 

563 - `"computer_call"`

564 

565 - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more`

566 

567 A click action.

568 

569 - `click: object { button, type, x, 2 more }`

570 

571 A click action.

572 

573 - `button: "left" or "right" or "wheel" or 2 more`

574 

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

576 

577 - `"left"`

578 

579 - `"right"`

580 

581 - `"wheel"`

582 

583 - `"back"`

584 

585 - `"forward"`

586 

587 - `type: "click"`

588 

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

590 

591 - `x: number`

592 

593 The x-coordinate where the click occurred.

594 

595 - `y: number`

596 

597 The y-coordinate where the click occurred.

598 

599 - `keys: optional array of string`

600 

601 The keys being held while clicking.

602 

603 - `double_click: object { keys, type, x, y }`

604 

605 A double click action.

606 

607 - `keys: array of string`

608 

609 The keys being held while double-clicking.

610 

611 - `type: "double_click"`

612 

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

614 

615 - `x: number`

616 

617 The x-coordinate where the double click occurred.

618 

619 - `y: number`

620 

621 The y-coordinate where the double click occurred.

622 

623 - `drag: object { path, type, keys }`

624 

625 A drag action.

626 

627 - `path: array of object { x, y }`

628 

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

630 

631 ```

632 [

633 { x: 100, y: 200 },

634 { x: 200, y: 300 }

635 ]

636 ```

637 

638 - `x: number`

639 

640 The x-coordinate.

641 

642 - `y: number`

643 

644 The y-coordinate.

645 

646 - `type: "drag"`

647 

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

649 

650 - `keys: optional array of string`

651 

652 The keys being held while dragging the mouse.

653 

654 - `keypress: object { keys, type }`

655 

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

657 

658 - `keys: array of string`

659 

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

661 

662 - `type: "keypress"`

663 

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

665 

666 - `move: object { type, x, y, keys }`

667 

668 A mouse move action.

669 

670 - `type: "move"`

671 

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

673 

674 - `x: number`

675 

676 The x-coordinate to move to.

677 

678 - `y: number`

679 

680 The y-coordinate to move to.

681 

682 - `keys: optional array of string`

683 

684 The keys being held while moving the mouse.

685 

686 - `screenshot: object { type }`

687 

688 A screenshot action.

689 

690 - `scroll: object { scroll_x, scroll_y, type, 3 more }`

691 

692 A scroll action.

693 

694 - `scroll_x: number`

695 

696 The horizontal scroll distance.

697 

698 - `scroll_y: number`

699 

700 The vertical scroll distance.

701 

702 - `type: "scroll"`

703 

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

705 

706 - `x: number`

707 

708 The x-coordinate where the scroll occurred.

709 

710 - `y: number`

711 

712 The y-coordinate where the scroll occurred.

713 

714 - `keys: optional array of string`

715 

716 The keys being held while scrolling.

717 

718 - `type: object { text, type }`

719 

720 An action to type in text.

721 

722 - `text: string`

723 

724 The text to type.

725 

726 - `type: "type"`

727 

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

729 

730 - `wait: object { type }`

731 

732 A wait action.

733 

734 - `actions: optional array of ComputerAction`

735 

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

737 `type` discriminator and action-specific fields.

738 

739 - `click: object { button, type, x, 2 more }`

740 

741 A click action.

742 

743 - `button: "left" or "right" or "wheel" or 2 more`

744 

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

746 

747 - `"left"`

748 

749 - `"right"`

750 

751 - `"wheel"`

752 

753 - `"back"`

754 

755 - `"forward"`

756 

757 - `type: "click"`

758 

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

760 

761 - `x: number`

762 

763 The x-coordinate where the click occurred.

764 

765 - `y: number`

766 

767 The y-coordinate where the click occurred.

768 

769 - `keys: optional array of string`

770 

771 The keys being held while clicking.

772 

773 - `double_click: object { keys, type, x, y }`

774 

775 A double click action.

776 

777 - `keys: array of string`

778 

779 The keys being held while double-clicking.

780 

781 - `type: "double_click"`

782 

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

784 

785 - `x: number`

786 

787 The x-coordinate where the double click occurred.

788 

789 - `y: number`

790 

791 The y-coordinate where the double click occurred.

792 

793 - `drag: object { path, type, keys }`

794 

795 A drag action.

796 

797 - `path: array of object { x, y }`

798 

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

800 

801 ```

802 [

803 { x: 100, y: 200 },

804 { x: 200, y: 300 }

805 ]

806 ```

807 

808 - `x: number`

809 

810 The x-coordinate.

811 

812 - `y: number`

813 

814 The y-coordinate.

815 

816 - `type: "drag"`

817 

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

819 

820 - `keys: optional array of string`

821 

822 The keys being held while dragging the mouse.

823 

824 - `keypress: object { keys, type }`

825 

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

827 

828 - `keys: array of string`

829 

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

831 

832 - `type: "keypress"`

833 

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

835 

836 - `move: object { type, x, y, keys }`

837 

838 A mouse move action.

839 

840 - `type: "move"`

841 

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

843 

844 - `x: number`

845 

846 The x-coordinate to move to.

847 

848 - `y: number`

849 

850 The y-coordinate to move to.

851 

852 - `keys: optional array of string`

853 

854 The keys being held while moving the mouse.

855 

856 - `screenshot: object { type }`

857 

858 A screenshot action.

859 

860 - `scroll: object { scroll_x, scroll_y, type, 3 more }`

861 

862 A scroll action.

863 

864 - `scroll_x: number`

865 

866 The horizontal scroll distance.

867 

868 - `scroll_y: number`

869 

870 The vertical scroll distance.

871 

872 - `type: "scroll"`

873 

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

875 

876 - `x: number`

877 

878 The x-coordinate where the scroll occurred.

879 

880 - `y: number`

881 

882 The y-coordinate where the scroll occurred.

883 

884 - `keys: optional array of string`

885 

886 The keys being held while scrolling.

887 

888 - `type: object { text, type }`

889 

890 An action to type in text.

891 

892 - `text: string`

893 

894 The text to type.

895 

896 - `type: "type"`

897 

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

899 

900 - `wait: object { type }`

901 

902 A wait action.

903 

904 - `computer_call_output: object { call_id, output, type, 3 more }`

905 

906 The output of a computer tool call.

907 

908 - `call_id: string`

909 

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

911 

912 - `output: object { type, file_id, image_url }`

913 

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

915 

916 - `type: "computer_screenshot"`

917 

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

919 always set to `computer_screenshot`.

920 

921 - `file_id: optional string`

922 

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

924 

925 - `image_url: optional string`

926 

927 The URL of the screenshot image.

928 

929 - `type: "computer_call_output"`

930 

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

932 

933 - `id: optional string`

934 

935 The ID of the computer tool call output.

936 

937 - `acknowledged_safety_checks: optional array of object { id, code, message }`

938 

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

940 

941 - `id: string`

942 

943 The ID of the pending safety check.

944 

945 - `code: optional string`

946 

947 The type of the pending safety check.

948 

949 - `message: optional string`

950 

951 Details about the pending safety check.

952 

953 - `status: optional "in_progress" or "completed" or "incomplete"`

954 

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

956 

957 - `"in_progress"`

958 

959 - `"completed"`

960 

961 - `"incomplete"`

962 

963 - `response_function_web_search: object { id, action, status, type }`

964 

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

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

967 

968 - `id: string`

969 

970 The unique ID of the web search tool call.

971 

972 - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }`

973 

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

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

976 

977 - `search: object { query, type, queries, sources }`

978 

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

980 

981 - `query: string`

982 

983 [DEPRECATED] The search query.

984 

985 - `type: "search"`

986 

987 The action type.

988 

989 - `queries: optional array of string`

990 

991 The search queries.

992 

993 - `sources: optional array of object { type, url }`

994 

995 The sources used in the search.

996 

997 - `type: "url"`

998 

999 The type of source. Always `url`.

1000 

1001 - `url: string`

1002 

1003 The URL of the source.

1004 

1005 - `open_page: object { type, url }`

1006 

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

1008 

1009 - `type: "open_page"`

1010 

1011 The action type.

1012 

1013 - `url: optional string`

1014 

1015 The URL opened by the model.

1016 

1017 - `find_in_page: object { pattern, type, url }`

1018 

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

1020 

1021 - `pattern: string`

1022 

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

1024 

1025 - `type: "find_in_page"`

1026 

1027 The action type.

1028 

1029 - `url: string`

1030 

1031 The URL of the page searched for the pattern.

1032 

1033 - `status: "in_progress" or "searching" or "completed" or "failed"`

1034 

1035 The status of the web search tool call.

1036 

1037 - `"in_progress"`

1038 

1039 - `"searching"`

1040 

1041 - `"completed"`

1042 

1043 - `"failed"`

1044 

1045 - `type: "web_search_call"`

1046 

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

1048 

1049 - `response_function_tool_call: object { arguments, call_id, name, 4 more }`

1050 

1051 A tool call to run a function. See the

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

1053 

1054 - `arguments: string`

1055 

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

1057 

1058 - `call_id: string`

1059 

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

1061 

1062 - `name: string`

1063 

1064 The name of the function to run.

1065 

1066 - `type: "function_call"`

1067 

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

1069 

1070 - `id: optional string`

1071 

1072 The unique ID of the function tool call.

1073 

1074 - `namespace: optional string`

1075 

1076 The namespace of the function to run.

1077 

1078 - `status: optional "in_progress" or "completed" or "incomplete"`

1079 

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

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

1082 

1083 - `"in_progress"`

1084 

1085 - `"completed"`

1086 

1087 - `"incomplete"`

1088 

1089 - `function_call_output: object { call_id, output, type, 2 more }`

1090 

1091 The output of a function tool call.

1092 

1093 - `call_id: string`

1094 

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

1096 

1097 - `output: string or ResponseFunctionCallOutputItemList`

1098 

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

1100 

1101 - `union_member_0: string`

1102 

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

1104 

1105 - `response_function_call_output_item_list: array of ResponseFunctionCallOutputItem`

1106 

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

1108 

1109 - `response_input_text_content: object { text, type }`

1110 

1111 A text input to the model.

1112 

1113 - `text: string`

1114 

1115 The text input to the model.

1116 

1117 - `type: "input_text"`

1118 

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

1120 

1121 - `response_input_image_content: object { type, detail, file_id, image_url }`

1122 

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

1124 

1125 - `type: "input_image"`

1126 

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

1128 

1129 - `detail: optional "low" or "high" or "auto" or "original"`

1130 

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

1132 

1133 - `"low"`

1134 

1135 - `"high"`

1136 

1137 - `"auto"`

1138 

1139 - `"original"`

1140 

1141 - `file_id: optional string`

1142 

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

1144 

1145 - `image_url: optional string`

1146 

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

1148 

1149 - `response_input_file_content: object { type, detail, file_data, 3 more }`

1150 

1151 A file input to the model.

1152 

1153 - `type: "input_file"`

1154 

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

1156 

1157 - `detail: optional "low" or "high"`

1158 

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

1160 

1161 - `"low"`

1162 

1163 - `"high"`

1164 

1165 - `file_data: optional string`

1166 

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

1168 

1169 - `file_id: optional string`

1170 

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

1172 

1173 - `file_url: optional string`

1174 

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

1176 

1177 - `filename: optional string`

1178 

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

1180 

1181 - `type: "function_call_output"`

1182 

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

1184 

1185 - `id: optional string`

1186 

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

1188 

1189 - `status: optional "in_progress" or "completed" or "incomplete"`

1190 

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

1192 

1193 - `"in_progress"`

1194 

1195 - `"completed"`

1196 

1197 - `"incomplete"`

1198 

1199 - `tool_search_call: object { arguments, type, id, 3 more }`

1200 

1201 - `arguments: unknown`

1202 

1203 The arguments supplied to the tool search call.

1204 

1205 - `type: "tool_search_call"`

1206 

1207 The item type. Always `tool_search_call`.

1208 

1209 - `id: optional string`

1210 

1211 The unique ID of this tool search call.

1212 

1213 - `call_id: optional string`

1214 

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

1216 

1217 - `execution: optional "server" or "client"`

1218 

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

1220 

1221 - `"server"`

1222 

1223 - `"client"`

1224 

1225 - `status: optional "in_progress" or "completed" or "incomplete"`

1226 

1227 The status of the tool search call.

1228 

1229 - `"in_progress"`

1230 

1231 - `"completed"`

1232 

1233 - `"incomplete"`

1234 

1235 - `response_tool_search_output_item_param: object { tools, type, id, 3 more }`

1236 

1237 - `tools: array of Tool`

1238 

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

1240 

1241 - `function_tool: object { name, parameters, strict, 3 more }`

1242 

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

1244 

1245 - `name: string`

1246 

1247 The name of the function to call.

1248 

1249 - `parameters: map[unknown]`

1250 

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

1252 

1253 - `strict: boolean`

1254 

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

1256 

1257 - `type: "function"`

1258 

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

1260 

1261 - `defer_loading: optional boolean`

1262 

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

1264 

1265 - `description: optional string`

1266 

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

1268 

1269 - `file_search_tool: object { type, vector_store_ids, filters, 2 more }`

1270 

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

1272 

1273 - `type: "file_search"`

1274 

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

1276 

1277 - `vector_store_ids: array of string`

1278 

1279 The IDs of the vector stores to search.

1280 

1281 - `filters: optional ComparisonFilter or CompoundFilter`

1282 

1283 A filter to apply.

1284 

1285 - `comparison_filter: object { key, type, value }`

1286 

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

1288 

1289 - `key: string`

1290 

1291 The key to compare against the value.

1292 

1293 - `type: "eq" or "ne" or "gt" or 5 more`

1294 

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

1296 

1297 - `eq`: equals

1298 - `ne`: not equal

1299 - `gt`: greater than

1300 - `gte`: greater than or equal

1301 - `lt`: less than

1302 - `lte`: less than or equal

1303 - `in`: in

1304 - `nin`: not in

1305 

1306 - `"eq"`

1307 

1308 - `"ne"`

1309 

1310 - `"gt"`

1311 

1312 - `"gte"`

1313 

1314 - `"lt"`

1315 

1316 - `"lte"`

1317 

1318 - `"in"`

1319 

1320 - `"nin"`

1321 

1322 - `value: string or number or boolean or array of string or number`

1323 

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

1325 

1326 - `union_member_0: string`

1327 

1328 - `union_member_1: number`

1329 

1330 - `union_member_2: boolean`

1331 

1332 - `union_member_3: array of string or number`

1333 

1334 - `union_member_0: string`

1335 

1336 - `union_member_1: number`

1337 

1338 - `compound_filter: object { filters, type }`

1339 

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

1341 

1342 - `filters: array of ComparisonFilter or unknown`

1343 

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

1345 

1346 - `comparison_filter: object { key, type, value }`

1347 

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

1349 

1350 - `union_member_1: unknown`

1351 

1352 - `type: "and" or "or"`

1353 

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

1355 

1356 - `"and"`

1357 

1358 - `"or"`

1359 

1360 - `max_num_results: optional number`

1361 

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

1363 

1364 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }`

1365 

1366 Ranking options for search.

1367 

1368 - `hybrid_search: optional object { embedding_weight, text_weight }`

1369 

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

1371 

1372 - `embedding_weight: number`

1373 

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

1375 

1376 - `text_weight: number`

1377 

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

1379 

1380 - `ranker: optional "auto" or "default-2024-11-15"`

1381 

1382 The ranker to use for the file search.

1383 

1384 - `"auto"`

1385 

1386 - `"default-2024-11-15"`

1387 

1388 - `score_threshold: optional number`

1389 

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

1391 

1392 - `computer_tool: object { type }`

1393 

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

1395 

1396 - `type: "computer"`

1397 

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

1399 

1400 - `computer_use_preview_tool: object { display_height, display_width, environment, type }`

1401 

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

1403 

1404 - `display_height: number`

1405 

1406 The height of the computer display.

1407 

1408 - `display_width: number`

1409 

1410 The width of the computer display.

1411 

1412 - `environment: "windows" or "mac" or "linux" or 2 more`

1413 

1414 The type of computer environment to control.

1415 

1416 - `"windows"`

1417 

1418 - `"mac"`

1419 

1420 - `"linux"`

1421 

1422 - `"ubuntu"`

1423 

1424 - `"browser"`

1425 

1426 - `type: "computer_use_preview"`

1427 

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

1429 

1430 - `web_search_tool: object { type, filters, search_context_size, user_location }`

1431 

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

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

1434 

1435 - `type: "web_search" or "web_search_2025_08_26"`

1436 

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

1438 

1439 - `"web_search"`

1440 

1441 - `"web_search_2025_08_26"`

1442 

1443 - `filters: optional object { allowed_domains }`

1444 

1445 Filters for the search.

1446 

1447 - `allowed_domains: optional array of string`

1448 

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

1450 Subdomains of the provided domains are allowed as well.

1451 

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

1453 

1454 - `search_context_size: optional "low" or "medium" or "high"`

1455 

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

1457 

1458 - `"low"`

1459 

1460 - `"medium"`

1461 

1462 - `"high"`

1463 

1464 - `user_location: optional object { city, country, region, 2 more }`

1465 

1466 The approximate location of the user.

1467 

1468 - `city: optional string`

1469 

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

1471 

1472 - `country: optional string`

1473 

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

1475 

1476 - `region: optional string`

1477 

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

1479 

1480 - `timezone: optional string`

1481 

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

1483 

1484 - `type: optional "approximate"`

1485 

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

1487 

1488 - `"approximate"`

1489 

1490 - `mcp: object { server_label, type, allowed_tools, 7 more }`

1491 

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

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

1494 

1495 - `server_label: string`

1496 

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

1498 

1499 - `type: "mcp"`

1500 

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

1502 

1503 - `allowed_tools: optional array of string or object { read_only, tool_names }`

1504 

1505 List of allowed tool names or a filter object.

1506 

1507 - `MCP allowed tools: array of string`

1508 

1509 A string array of allowed tool names

1510 

1511 - `MCP tool filter: object { read_only, tool_names }`

1512 

1513 A filter object to specify which tools are allowed.

1514 

1515 - `read_only: optional boolean`

1516 

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

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

1519 it will match this filter.

1520 

1521 - `tool_names: optional array of string`

1522 

1523 List of allowed tool names.

1524 

1525 - `authorization: optional string`

1526 

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

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

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

1530 

1531 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more`

1532 

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

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

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

1536 

1537 Currently supported `connector_id` values are:

1538 

1539 - Dropbox: `connector_dropbox`

1540 - Gmail: `connector_gmail`

1541 - Google Calendar: `connector_googlecalendar`

1542 - Google Drive: `connector_googledrive`

1543 - Microsoft Teams: `connector_microsoftteams`

1544 - Outlook Calendar: `connector_outlookcalendar`

1545 - Outlook Email: `connector_outlookemail`

1546 - SharePoint: `connector_sharepoint`

1547 

1548 - `"connector_dropbox"`

1549 

1550 - `"connector_gmail"`

1551 

1552 - `"connector_googlecalendar"`

1553 

1554 - `"connector_googledrive"`

1555 

1556 - `"connector_microsoftteams"`

1557 

1558 - `"connector_outlookcalendar"`

1559 

1560 - `"connector_outlookemail"`

1561 

1562 - `"connector_sharepoint"`

1563 

1564 - `defer_loading: optional boolean`

1565 

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

1567 

1568 - `headers: optional map[string]`

1569 

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

1571 or other purposes.

1572 

1573 - `require_approval: optional object { always, never } or "always" or "never"`

1574 

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

1576 

1577 - `MCP tool approval filter: object { always, never }`

1578 

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

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

1581 that require approval.

1582 

1583 - `always: optional object { read_only, tool_names }`

1584 

1585 A filter object to specify which tools are allowed.

1586 

1587 - `read_only: optional boolean`

1588 

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

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

1591 it will match this filter.

1592 

1593 - `tool_names: optional array of string`

1594 

1595 List of allowed tool names.

1596 

1597 - `never: optional object { read_only, tool_names }`

1598 

1599 A filter object to specify which tools are allowed.

1600 

1601 - `read_only: optional boolean`

1602 

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

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

1605 it will match this filter.

1606 

1607 - `tool_names: optional array of string`

1608 

1609 List of allowed tool names.

1610 

1611 - `MCP tool approval setting: "always" or "never"`

1612 

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

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

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

1616 

1617 - `"always"`

1618 

1619 - `"never"`

1620 

1621 - `server_description: optional string`

1622 

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

1624 

1625 - `server_url: optional string`

1626 

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

1628 provided.

1629 

1630 - `code_interpreter: object { container, type }`

1631 

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

1633 

1634 - `container: string or object { type, file_ids, memory_limit, network_policy }`

1635 

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

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

1638 optional `memory_limit` setting.

1639 

1640 - `union_member_0: string`

1641 

1642 The container ID.

1643 

1644 - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }`

1645 

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

1647 

1648 - `type: "auto"`

1649 

1650 Always `auto`.

1651 

1652 - `file_ids: optional array of string`

1653 

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

1655 

1656 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"`

1657 

1658 The memory limit for the code interpreter container.

1659 

1660 - `"1g"`

1661 

1662 - `"4g"`

1663 

1664 - `"16g"`

1665 

1666 - `"64g"`

1667 

1668 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1669 

1670 Network access policy for the container.

1671 

1672 - `container_network_policy_disabled: object { type }`

1673 

1674 - `type: "disabled"`

1675 

1676 Disable outbound network access. Always `disabled`.

1677 

1678 - `container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }`

1679 

1680 - `allowed_domains: array of string`

1681 

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

1683 

1684 - `type: "allowlist"`

1685 

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

1687 

1688 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1689 

1690 Optional domain-scoped secrets for allowlisted domains.

1691 

1692 - `domain: string`

1693 

1694 The domain associated with the secret.

1695 

1696 - `name: string`

1697 

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

1699 

1700 - `value: string`

1701 

1702 The secret value to inject for the domain.

1703 

1704 - `type: "code_interpreter"`

1705 

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

1707 

1708 - `image_generation: object { type, action, background, 9 more }`

1709 

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

1711 

1712 - `type: "image_generation"`

1713 

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

1715 

1716 - `action: optional "generate" or "edit" or "auto"`

1717 

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

1719 

1720 - `"generate"`

1721 

1722 - `"edit"`

1723 

1724 - `"auto"`

1725 

1726 - `background: optional "transparent" or "opaque" or "auto"`

1727 

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

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

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

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

1732 automatically determine the best background for the image.

1733 

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

1735 transparent backgrounds. Requests with `background` set to

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

1737 `auto` instead.

1738 

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

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

1741 

1742 - `"transparent"`

1743 

1744 - `"opaque"`

1745 

1746 - `"auto"`

1747 

1748 - `input_fidelity: optional "high" or "low"`

1749 

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

1751 

1752 - `"high"`

1753 

1754 - `"low"`

1755 

1756 - `input_image_mask: optional object { file_id, image_url }`

1757 

1758 Optional mask for inpainting. Contains `image_url`

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

1760 

1761 - `file_id: optional string`

1762 

1763 File ID for the mask image.

1764 

1765 - `image_url: optional string`

1766 

1767 Base64-encoded mask image.

1768 

1769 - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more`

1770 

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

1772 

1773 - `"gpt-image-1"`

1774 

1775 - `"gpt-image-1-mini"`

1776 

1777 - `"gpt-image-2"`

1778 

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

1780 

1781 - `"gpt-image-1.5"`

1782 

1783 - `"chatgpt-image-latest"`

1784 

1785 - `moderation: optional "auto" or "low"`

1786 

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

1788 

1789 - `"auto"`

1790 

1791 - `"low"`

1792 

1793 - `output_compression: optional number`

1794 

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

1796 

1797 - `output_format: optional "png" or "webp" or "jpeg"`

1798 

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

1800 `jpeg`. Default: `png`.

1801 

1802 - `"png"`

1803 

1804 - `"webp"`

1805 

1806 - `"jpeg"`

1807 

1808 - `partial_images: optional number`

1809 

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

1811 

1812 - `quality: optional "low" or "medium" or "high" or "auto"`

1813 

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

1815 or `auto`. Default: `auto`.

1816 

1817 - `"low"`

1818 

1819 - `"medium"`

1820 

1821 - `"high"`

1822 

1823 - `"auto"`

1824 

1825 - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1826 

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

1828 

1829 - `"1024x1024"`

1830 

1831 - `"1024x1536"`

1832 

1833 - `"1536x1024"`

1834 

1835 - `"auto"`

1836 

1837 - `local_shell: object { type }`

1838 

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

1840 

1841 - `function_shell_tool: object { type, environment }`

1842 

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

1844 

1845 - `type: "shell"`

1846 

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

1848 

1849 - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference`

1850 

1851 - `container_auto: object { type, file_ids, memory_limit, 2 more }`

1852 

1853 - `type: "container_auto"`

1854 

1855 Automatically creates a container for this request

1856 

1857 - `file_ids: optional array of string`

1858 

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

1860 

1861 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"`

1862 

1863 The memory limit for the container.

1864 

1865 - `"1g"`

1866 

1867 - `"4g"`

1868 

1869 - `"16g"`

1870 

1871 - `"64g"`

1872 

1873 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1874 

1875 Network access policy for the container.

1876 

1877 - `container_network_policy_disabled: object { type }`

1878 

1879 - `container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }`

1880 

1881 - `skills: optional array of SkillReference or InlineSkill`

1882 

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

1884 

1885 - `skill_reference: object { skill_id, type, version }`

1886 

1887 - `skill_id: string`

1888 

1889 The ID of the referenced skill.

1890 

1891 - `type: "skill_reference"`

1892 

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

1894 

1895 - `version: optional string`

1896 

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

1898 

1899 - `inline_skill: object { description, name, source, type }`

1900 

1901 - `description: string`

1902 

1903 The description of the skill.

1904 

1905 - `name: string`

1906 

1907 The name of the skill.

1908 

1909 - `source: object { data, media_type, type }`

1910 

1911 Inline skill payload

1912 

1913 - `data: string`

1914 

1915 Base64-encoded skill zip bundle.

1916 

1917 - `media_type: "application/zip"`

1918 

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

1920 

1921 - `type: "base64"`

1922 

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

1924 

1925 - `type: "inline"`

1926 

1927 Defines an inline skill for this request.

1928 

1929 - `local_environment: object { type, skills }`

1930 

1931 - `type: "local"`

1932 

1933 Use a local computer environment.

1934 

1935 - `skills: optional array of LocalSkill`

1936 

1937 An optional list of skills.

1938 

1939 - `description: string`

1940 

1941 The description of the skill.

1942 

1943 - `name: string`

1944 

1945 The name of the skill.

1946 

1947 - `path: string`

1948 

1949 The path to the directory containing the skill.

1950 

1951 - `container_reference: object { container_id, type }`

1952 

1953 - `container_id: string`

1954 

1955 The ID of the referenced container.

1956 

1957 - `type: "container_reference"`

1958 

1959 References a container created with the /v1/containers endpoint

1960 

1961 - `custom_tool: object { name, type, defer_loading, 2 more }`

1962 

1963 A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)

1964 

1965 - `name: string`

1966 

1967 The name of the custom tool, used to identify it in tool calls.

1968 

1969 - `type: "custom"`

1970 

1971 The type of the custom tool. Always `custom`.

1972 

1973 - `defer_loading: optional boolean`

1974 

1975 Whether this tool should be deferred and discovered via tool search.

1976 

1977 - `description: optional string`

1978 

1979 Optional description of the custom tool, used to provide more context.

1980 

1981 - `format: optional object { type } or object { definition, syntax, type }`

1982 

1983 The input format for the custom tool. Default is unconstrained text.

1984 

1985 - `text: object { type }`

1986 

1987 Unconstrained free-form text.

1988 

1989 - `grammar: object { definition, syntax, type }`

1990 

1991 A grammar defined by the user.

1992 

1993 - `definition: string`

1994 

1995 The grammar definition.

1996