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

1## Get a model response

2 

3`$ openai responses retrieve`

4 

5**get** `/responses/{response_id}`

6 

7Retrieves a model response with the given ID.

8 

9### Parameters

10 

11- `--response-id: string`

12 

13 The ID of the response to retrieve.

14 

15- `--include: optional array of ResponseIncludable`

16 

17 Additional fields to include in the response. See the `include`

18 parameter for Response creation above for more information.

19 

20- `--include-obfuscation: optional boolean`

21 

22 When true, stream obfuscation will be enabled. Stream obfuscation adds

23 random characters to an `obfuscation` field on streaming delta events

24 to normalize payload sizes as a mitigation to certain side-channel

25 attacks. These obfuscation fields are included by default, but add a

26 small amount of overhead to the data stream. You can set

27 `include_obfuscation` to false to optimize for bandwidth if you trust

28 the network links between your application and the OpenAI API.

29 

30- `--starting-after: optional number`

31 

32 The sequence number of the event after which to start streaming.

33 

34### Returns

35 

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

37 

38 - `id: string`

39 

40 Unique identifier for this Response.

41 

42 - `created_at: number`

43 

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

45 

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

47 

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

49 

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

51 

52 The error code for the response.

53 

54 - `"server_error"`

55 

56 - `"rate_limit_exceeded"`

57 

58 - `"invalid_prompt"`

59 

60 - `"vector_store_timeout"`

61 

62 - `"invalid_image"`

63 

64 - `"invalid_image_format"`

65 

66 - `"invalid_base64_image"`

67 

68 - `"invalid_image_url"`

69 

70 - `"image_too_large"`

71 

72 - `"image_too_small"`

73 

74 - `"image_parse_error"`

75 

76 - `"image_content_policy_violation"`

77 

78 - `"invalid_image_mode"`

79 

80 - `"image_file_too_large"`

81 

82 - `"unsupported_image_media_type"`

83 

84 - `"empty_image_file"`

85 

86 - `"failed_to_download_image"`

87 

88 - `"image_file_not_found"`

89 

90 - `message: string`

91 

92 A human-readable description of the error.

93 

94 - `incomplete_details: object { reason }`

95 

96 Details about why the response is incomplete.

97 

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

99 

100 The reason why the response is incomplete.

101 

102 - `"max_output_tokens"`

103 

104 - `"content_filter"`

105 

106 - `instructions: string or array of ResponseInputItem`

107 

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

109 

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

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

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

113 

114 - `union_member_0: string`

115 

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

117 `developer` role.

118 

119 - `Input item list: array of ResponseInputItem`

120 

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

122 different content types.

123 

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

125 

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

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

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

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

130 interactions.

131 

132 - `content: string or ResponseInputMessageContentList`

133 

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

135 Can also contain previous assistant responses.

136 

137 - `Text input: string`

138 

139 A text input to the model.

140 

141 - `response_input_message_content_list: array of ResponseInputContent`

142 

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

144 types.

145 

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

147 

148 A text input to the model.

149 

150 - `text: string`

151 

152 The text input to the model.

153 

154 - `type: "input_text"`

155 

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

157 

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

159 

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

161 

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

163 

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

165 

166 - `"low"`

167 

168 - `"high"`

169 

170 - `"auto"`

171 

172 - `"original"`

173 

174 - `type: "input_image"`

175 

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

177 

178 - `file_id: optional string`

179 

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

181 

182 - `image_url: optional string`

183 

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

185 

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

187 

188 A file input to the model.

189 

190 - `type: "input_file"`

191 

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

193 

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

195 

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

197 

198 - `"low"`

199 

200 - `"high"`

201 

202 - `file_data: optional string`

203 

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

205 

206 - `file_id: optional string`

207 

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

209 

210 - `file_url: optional string`

211 

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

213 

214 - `filename: optional string`

215 

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

217 

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

219 

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

221 `developer`.

222 

223 - `"user"`

224 

225 - `"assistant"`

226 

227 - `"system"`

228 

229 - `"developer"`

230 

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

232 

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

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

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

236 

237 - `"commentary"`

238 

239 - `"final_answer"`

240 

241 - `type: optional "message"`

242 

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

244 

245 - `"message"`

246 

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

248 

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

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

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

252 

253 - `content: array of ResponseInputContent`

254 

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

256 types.

257 

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

259 

260 A text input to the model.

261 

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

263 

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

265 

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

267 

268 A file input to the model.

269 

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

271 

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

273 

274 - `"user"`

275 

276 - `"system"`

277 

278 - `"developer"`

279 

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

281 

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

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

284 

285 - `"in_progress"`

286 

287 - `"completed"`

288 

289 - `"incomplete"`

290 

291 - `type: optional "message"`

292 

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

294 

295 - `"message"`

296 

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

298 

299 An output message from the model.

300 

301 - `id: string`

302 

303 The unique ID of the output message.

304 

305 - `content: array of ResponseOutputText or ResponseOutputRefusal`

306 

307 The content of the output message.

308 

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

310 

311 A text output from the model.

312 

313 - `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 }`

314 

315 The annotations of the text output.

316 

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

318 

319 A citation to a file.

320 

321 - `file_id: string`

322 

323 The ID of the file.

324 

325 - `filename: string`

326 

327 The filename of the file cited.

328 

329 - `index: number`

330 

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

332 

333 - `type: "file_citation"`

334 

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

336 

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

338 

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

340 

341 - `end_index: number`

342 

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

344 

345 - `start_index: number`

346 

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

348 

349 - `title: string`

350 

351 The title of the web resource.

352 

353 - `type: "url_citation"`

354 

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

356 

357 - `url: string`

358 

359 The URL of the web resource.

360 

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

362 

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

364 

365 - `container_id: string`

366 

367 The ID of the container file.

368 

369 - `end_index: number`

370 

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

372 

373 - `file_id: string`

374 

375 The ID of the file.

376 

377 - `filename: string`

378 

379 The filename of the container file cited.

380 

381 - `start_index: number`

382 

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

384 

385 - `type: "container_file_citation"`

386 

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

388 

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

390 

391 A path to a file.

392 

393 - `file_id: string`

394 

395 The ID of the file.

396 

397 - `index: number`

398 

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

400 

401 - `type: "file_path"`

402 

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

404 

405 - `text: string`

406 

407 The text output from the model.

408 

409 - `type: "output_text"`

410 

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

412 

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

414 

415 - `token: string`

416 

417 - `bytes: array of number`

418 

419 - `logprob: number`

420 

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

422 

423 - `token: string`

424 

425 - `bytes: array of number`

426 

427 - `logprob: number`

428 

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

430 

431 A refusal from the model.

432 

433 - `refusal: string`

434 

435 The refusal explanation from the model.

436 

437 - `type: "refusal"`

438 

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

440 

441 - `role: "assistant"`

442 

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

444 

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

446 

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

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

449 

450 - `"in_progress"`

451 

452 - `"completed"`

453 

454 - `"incomplete"`

455 

456 - `type: "message"`

457 

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

459 

460 - `phase: optional "commentary" or "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 - `response_file_search_tool_call: object { id, queries, status, 2 more }`

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

476 

477 The unique ID of the file search tool call.

478 

479 - `queries: array of string`

480 

481 The queries used to search for files.

482 

483 - `status: "in_progress" or "searching" or "completed" or 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: "file_search_call"`

499 

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

501 

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

503 

504 The results of the file search tool call.

505 

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

507 

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

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

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

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

512 length of 512 characters, booleans, or numbers.

513 

514 - `union_member_0: string`

515 

516 - `union_member_1: number`

517 

518 - `union_member_2: boolean`

519 

520 - `file_id: optional string`

521 

522 The unique ID of the file.

523 

524 - `filename: optional string`

525 

526 The name of the file.

527 

528 - `score: optional number`

529 

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

531 

532 - `text: optional string`

533 

534 The text that was retrieved from the file.

535 

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

537 

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

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

540 

541 - `id: string`

542 

543 The unique ID of the computer call.

544 

545 - `call_id: string`

546 

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

548 

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

550 

551 The pending safety checks for the computer call.

552 

553 - `id: string`

554 

555 The ID of the pending safety check.

556 

557 - `code: optional string`

558 

559 The type of the pending safety check.

560 

561 - `message: optional string`

562 

563 Details about the pending safety check.

564 

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

566 

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

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

569 

570 - `"in_progress"`

571 

572 - `"completed"`

573 

574 - `"incomplete"`

575 

576 - `type: "computer_call"`

577 

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

579 

580 - `"computer_call"`

581 

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

583 

584 A click action.

585 

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

587 

588 A click action.

589 

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

591 

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

593 

594 - `"left"`

595 

596 - `"right"`

597 

598 - `"wheel"`

599 

600 - `"back"`

601 

602 - `"forward"`

603 

604 - `type: "click"`

605 

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

607 

608 - `x: number`

609 

610 The x-coordinate where the click occurred.

611 

612 - `y: number`

613 

614 The y-coordinate where the click occurred.

615 

616 - `keys: optional array of string`

617 

618 The keys being held while clicking.

619 

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

621 

622 A double click action.

623 

624 - `keys: array of string`

625 

626 The keys being held while double-clicking.

627 

628 - `type: "double_click"`

629 

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

631 

632 - `x: number`

633 

634 The x-coordinate where the double click occurred.

635 

636 - `y: number`

637 

638 The y-coordinate where the double click occurred.

639 

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

641 

642 A drag action.

643 

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

645 

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

647 

648 ```

649 [

650 { x: 100, y: 200 },

651 { x: 200, y: 300 }

652 ]

653 ```

654 

655 - `x: number`

656 

657 The x-coordinate.

658 

659 - `y: number`

660 

661 The y-coordinate.

662 

663 - `type: "drag"`

664 

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

666 

667 - `keys: optional array of string`

668 

669 The keys being held while dragging the mouse.

670 

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

672 

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

674 

675 - `keys: array of string`

676 

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

678 

679 - `type: "keypress"`

680 

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

682 

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

684 

685 A mouse move action.

686 

687 - `type: "move"`

688 

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

690 

691 - `x: number`

692 

693 The x-coordinate to move to.

694 

695 - `y: number`

696 

697 The y-coordinate to move to.

698 

699 - `keys: optional array of string`

700 

701 The keys being held while moving the mouse.

702 

703 - `screenshot: object { type }`

704 

705 A screenshot action.

706 

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

708 

709 A scroll action.

710 

711 - `scroll_x: number`

712 

713 The horizontal scroll distance.

714 

715 - `scroll_y: number`

716 

717 The vertical scroll distance.

718 

719 - `type: "scroll"`

720 

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

722 

723 - `x: number`

724 

725 The x-coordinate where the scroll occurred.

726 

727 - `y: number`

728 

729 The y-coordinate where the scroll occurred.

730 

731 - `keys: optional array of string`

732 

733 The keys being held while scrolling.

734 

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

736 

737 An action to type in text.

738 

739 - `text: string`

740 

741 The text to type.

742 

743 - `type: "type"`

744 

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

746 

747 - `wait: object { type }`

748 

749 A wait action.

750 

751 - `actions: optional array of ComputerAction`

752 

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

754 `type` discriminator and action-specific fields.

755 

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

757 

758 A click action.

759 

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

761 

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

763 

764 - `"left"`

765 

766 - `"right"`

767 

768 - `"wheel"`

769 

770 - `"back"`

771 

772 - `"forward"`

773 

774 - `type: "click"`

775 

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

777 

778 - `x: number`

779 

780 The x-coordinate where the click occurred.

781 

782 - `y: number`

783 

784 The y-coordinate where the click occurred.

785 

786 - `keys: optional array of string`

787 

788 The keys being held while clicking.

789 

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

791 

792 A double click action.

793 

794 - `keys: array of string`

795 

796 The keys being held while double-clicking.

797 

798 - `type: "double_click"`

799 

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

801 

802 - `x: number`

803 

804 The x-coordinate where the double click occurred.

805 

806 - `y: number`

807 

808 The y-coordinate where the double click occurred.

809 

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

811 

812 A drag action.

813 

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

815 

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

817 

818 ```

819 [

820 { x: 100, y: 200 },

821 { x: 200, y: 300 }

822 ]

823 ```

824 

825 - `x: number`

826 

827 The x-coordinate.

828 

829 - `y: number`

830 

831 The y-coordinate.

832 

833 - `type: "drag"`

834 

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

836 

837 - `keys: optional array of string`

838 

839 The keys being held while dragging the mouse.

840 

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

842 

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

844 

845 - `keys: array of string`

846 

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

848 

849 - `type: "keypress"`

850 

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

852 

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

854 

855 A mouse move action.

856 

857 - `type: "move"`

858 

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

860 

861 - `x: number`

862 

863 The x-coordinate to move to.

864 

865 - `y: number`

866 

867 The y-coordinate to move to.

868 

869 - `keys: optional array of string`

870 

871 The keys being held while moving the mouse.

872 

873 - `screenshot: object { type }`

874 

875 A screenshot action.

876 

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

878 

879 A scroll action.

880 

881 - `scroll_x: number`

882 

883 The horizontal scroll distance.

884 

885 - `scroll_y: number`

886 

887 The vertical scroll distance.

888 

889 - `type: "scroll"`

890 

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

892 

893 - `x: number`

894 

895 The x-coordinate where the scroll occurred.

896 

897 - `y: number`

898 

899 The y-coordinate where the scroll occurred.

900 

901 - `keys: optional array of string`

902 

903 The keys being held while scrolling.

904 

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

906 

907 An action to type in text.

908 

909 - `text: string`

910 

911 The text to type.

912 

913 - `type: "type"`

914 

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

916 

917 - `wait: object { type }`

918 

919 A wait action.

920 

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

922 

923 The output of a computer tool call.

924 

925 - `call_id: string`

926 

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

928 

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

930 

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

932 

933 - `type: "computer_screenshot"`

934 

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

936 always set to `computer_screenshot`.

937 

938 - `file_id: optional string`

939 

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

941 

942 - `image_url: optional string`

943 

944 The URL of the screenshot image.

945 

946 - `type: "computer_call_output"`

947 

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

949 

950 - `id: optional string`

951 

952 The ID of the computer tool call output.

953 

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

955 

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

957 

958 - `id: string`

959 

960 The ID of the pending safety check.

961 

962 - `code: optional string`

963 

964 The type of the pending safety check.

965 

966 - `message: optional string`

967 

968 Details about the pending safety check.

969 

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

971 

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

973 

974 - `"in_progress"`

975 

976 - `"completed"`

977 

978 - `"incomplete"`

979 

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

981 

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

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

984 

985 - `id: string`

986 

987 The unique ID of the web search tool call.

988 

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

990 

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

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

993 

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

995 

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

997 

998 - `query: string`

999 

1000 [DEPRECATED] The search query.

1001 

1002 - `type: "search"`

1003 

1004 The action type.

1005 

1006 - `queries: optional array of string`

1007 

1008 The search queries.

1009 

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

1011 

1012 The sources used in the search.

1013 

1014 - `type: "url"`

1015 

1016 The type of source. Always `url`.

1017 

1018 - `url: string`

1019 

1020 The URL of the source.

1021 

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

1023 

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

1025 

1026 - `type: "open_page"`

1027 

1028 The action type.

1029 

1030 - `url: optional string`

1031 

1032 The URL opened by the model.

1033 

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

1035 

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

1037 

1038 - `pattern: string`

1039 

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

1041 

1042 - `type: "find_in_page"`

1043 

1044 The action type.

1045 

1046 - `url: string`

1047 

1048 The URL of the page searched for the pattern.

1049 

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

1051 

1052 The status of the web search tool call.

1053 

1054 - `"in_progress"`

1055 

1056 - `"searching"`

1057 

1058 - `"completed"`

1059 

1060 - `"failed"`

1061 

1062 - `type: "web_search_call"`

1063 

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

1065 

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

1067 

1068 A tool call to run a function. See the

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

1070 

1071 - `arguments: string`

1072 

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

1074 

1075 - `call_id: string`

1076 

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

1078 

1079 - `name: string`

1080 

1081 The name of the function to run.

1082 

1083 - `type: "function_call"`

1084 

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

1086 

1087 - `id: optional string`

1088 

1089 The unique ID of the function tool call.

1090 

1091 - `namespace: optional string`

1092 

1093 The namespace of the function to run.

1094 

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

1096 

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

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

1099 

1100 - `"in_progress"`

1101 

1102 - `"completed"`

1103 

1104 - `"incomplete"`

1105 

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

1107 

1108 The output of a function tool call.

1109 

1110 - `call_id: string`

1111 

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

1113 

1114 - `output: string or ResponseFunctionCallOutputItemList`

1115 

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

1117 

1118 - `union_member_0: string`

1119 

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

1121 

1122 - `response_function_call_output_item_list: array of ResponseFunctionCallOutputItem`

1123 

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

1125 

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

1127 

1128 A text input to the model.

1129 

1130 - `text: string`

1131 

1132 The text input to the model.

1133 

1134 - `type: "input_text"`

1135 

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

1137 

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

1139 

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

1141 

1142 - `type: "input_image"`

1143 

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

1145 

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

1147 

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

1149 

1150 - `"low"`

1151 

1152 - `"high"`

1153 

1154 - `"auto"`

1155 

1156 - `"original"`

1157 

1158 - `file_id: optional string`

1159 

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

1161 

1162 - `image_url: optional string`

1163 

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

1165 

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

1167 

1168 A file input to the model.

1169 

1170 - `type: "input_file"`

1171 

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

1173 

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

1175 

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

1177 

1178 - `"low"`

1179 

1180 - `"high"`

1181 

1182 - `file_data: optional string`

1183 

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

1185 

1186 - `file_id: optional string`

1187 

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

1189 

1190 - `file_url: optional string`

1191 

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

1193 

1194 - `filename: optional string`

1195 

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

1197 

1198 - `type: "function_call_output"`

1199 

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

1201 

1202 - `id: optional string`

1203 

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

1205 

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

1207 

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

1209 

1210 - `"in_progress"`

1211 

1212 - `"completed"`

1213 

1214 - `"incomplete"`

1215 

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

1217 

1218 - `arguments: unknown`

1219 

1220 The arguments supplied to the tool search call.

1221 

1222 - `type: "tool_search_call"`

1223 

1224 The item type. Always `tool_search_call`.

1225 

1226 - `id: optional string`

1227 

1228 The unique ID of this tool search call.

1229 

1230 - `call_id: optional string`

1231 

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

1233 

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

1235 

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

1237 

1238 - `"server"`

1239 

1240 - `"client"`

1241 

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

1243 

1244 The status of the tool search call.

1245 

1246 - `"in_progress"`

1247 

1248 - `"completed"`

1249 

1250 - `"incomplete"`

1251 

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

1253 

1254 - `tools: array of Tool`

1255 

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

1257 

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

1259 

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

1261 

1262 - `name: string`

1263 

1264 The name of the function to call.

1265 

1266 - `parameters: map[unknown]`

1267 

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

1269 

1270 - `strict: boolean`

1271 

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

1273 

1274 - `type: "function"`

1275 

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

1277 

1278 - `defer_loading: optional boolean`

1279 

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

1281 

1282 - `description: optional string`

1283 

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

1285 

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

1287 

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

1289 

1290 - `type: "file_search"`

1291 

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

1293 

1294 - `vector_store_ids: array of string`

1295 

1296 The IDs of the vector stores to search.

1297 

1298 - `filters: optional ComparisonFilter or CompoundFilter`

1299 

1300 A filter to apply.

1301 

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

1303 

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

1305 

1306 - `key: string`

1307 

1308 The key to compare against the value.

1309 

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

1311 

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

1313 

1314 - `eq`: equals

1315 - `ne`: not equal

1316 - `gt`: greater than

1317 - `gte`: greater than or equal

1318 - `lt`: less than

1319 - `lte`: less than or equal

1320 - `in`: in

1321 - `nin`: not in

1322 

1323 - `"eq"`

1324 

1325 - `"ne"`

1326 

1327 - `"gt"`

1328 

1329 - `"gte"`

1330 

1331 - `"lt"`

1332 

1333 - `"lte"`

1334 

1335 - `"in"`

1336 

1337 - `"nin"`

1338 

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

1340 

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

1342 

1343 - `union_member_0: string`

1344 

1345 - `union_member_1: number`

1346 

1347 - `union_member_2: boolean`

1348 

1349 - `union_member_3: array of string or number`

1350 

1351 - `union_member_0: string`

1352 

1353 - `union_member_1: number`

1354 

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

1356 

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

1358 

1359 - `filters: array of ComparisonFilter or unknown`

1360 

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

1362 

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

1364 

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

1366 

1367 - `union_member_1: unknown`

1368 

1369 - `type: "and" or "or"`

1370 

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

1372 

1373 - `"and"`

1374 

1375 - `"or"`

1376 

1377 - `max_num_results: optional number`

1378 

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

1380 

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

1382 

1383 Ranking options for search.

1384 

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

1386 

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

1388 

1389 - `embedding_weight: number`

1390 

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

1392 

1393 - `text_weight: number`

1394 

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

1396 

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

1398 

1399 The ranker to use for the file search.

1400 

1401 - `"auto"`

1402 

1403 - `"default-2024-11-15"`

1404 

1405 - `score_threshold: optional number`

1406 

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

1408 

1409 - `computer_tool: object { type }`

1410 

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

1412 

1413 - `type: "computer"`

1414 

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

1416 

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

1418 

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

1420 

1421 - `display_height: number`

1422 

1423 The height of the computer display.

1424 

1425 - `display_width: number`

1426 

1427 The width of the computer display.

1428 

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

1430 

1431 The type of computer environment to control.

1432 

1433 - `"windows"`

1434 

1435 - `"mac"`

1436 

1437 - `"linux"`

1438 

1439 - `"ubuntu"`

1440 

1441 - `"browser"`

1442 

1443 - `type: "computer_use_preview"`

1444 

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

1446 

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

1448 

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

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

1451 

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

1453 

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

1455 

1456 - `"web_search"`

1457 

1458 - `"web_search_2025_08_26"`

1459 

1460 - `filters: optional object { allowed_domains }`

1461 

1462 Filters for the search.

1463 

1464 - `allowed_domains: optional array of string`

1465 

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

1467 Subdomains of the provided domains are allowed as well.

1468 

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

1470 

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

1472 

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

1474 

1475 - `"low"`

1476 

1477 - `"medium"`

1478 

1479 - `"high"`

1480 

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

1482 

1483 The approximate location of the user.

1484 

1485 - `city: optional string`

1486 

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

1488 

1489 - `country: optional string`

1490 

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

1492 

1493 - `region: optional string`

1494 

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

1496 

1497 - `timezone: optional string`

1498 

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

1500 

1501 - `type: optional "approximate"`

1502 

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

1504 

1505 - `"approximate"`

1506 

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

1508 

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

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

1511 

1512 - `server_label: string`

1513 

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

1515 

1516 - `type: "mcp"`

1517 

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

1519 

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

1521 

1522 List of allowed tool names or a filter object.

1523 

1524 - `MCP allowed tools: array of string`

1525 

1526 A string array of allowed tool names

1527 

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

1529 

1530 A filter object to specify which tools are allowed.

1531 

1532 - `read_only: optional boolean`

1533 

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

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

1536 it will match this filter.

1537 

1538 - `tool_names: optional array of string`

1539 

1540 List of allowed tool names.

1541 

1542 - `authorization: optional string`

1543 

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

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

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

1547 

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

1549 

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

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

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

1553 

1554 Currently supported `connector_id` values are:

1555 

1556 - Dropbox: `connector_dropbox`

1557 - Gmail: `connector_gmail`

1558 - Google Calendar: `connector_googlecalendar`

1559 - Google Drive: `connector_googledrive`

1560 - Microsoft Teams: `connector_microsoftteams`

1561 - Outlook Calendar: `connector_outlookcalendar`

1562 - Outlook Email: `connector_outlookemail`

1563 - SharePoint: `connector_sharepoint`

1564 

1565 - `"connector_dropbox"`

1566 

1567 - `"connector_gmail"`

1568 

1569 - `"connector_googlecalendar"`

1570 

1571 - `"connector_googledrive"`

1572 

1573 - `"connector_microsoftteams"`

1574 

1575 - `"connector_outlookcalendar"`

1576 

1577 - `"connector_outlookemail"`

1578 

1579 - `"connector_sharepoint"`

1580 

1581 - `defer_loading: optional boolean`

1582 

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

1584 

1585 - `headers: optional map[string]`

1586 

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

1588 or other purposes.

1589 

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

1591 

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

1593 

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

1595 

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

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

1598 that require approval.

1599 

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

1601 

1602 A filter object to specify which tools are allowed.

1603 

1604 - `read_only: optional boolean`

1605 

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

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

1608 it will match this filter.

1609 

1610 - `tool_names: optional array of string`

1611 

1612 List of allowed tool names.

1613 

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

1615 

1616 A filter object to specify which tools are allowed.

1617 

1618 - `read_only: optional boolean`

1619 

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

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

1622 it will match this filter.

1623 

1624 - `tool_names: optional array of string`

1625 

1626 List of allowed tool names.

1627 

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

1629 

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

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

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

1633 

1634 - `"always"`

1635 

1636 - `"never"`

1637 

1638 - `server_description: optional string`

1639 

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

1641 

1642 - `server_url: optional string`

1643 

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

1645 provided.

1646 

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

1648 

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

1650 

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

1652 

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

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

1655 optional `memory_limit` setting.

1656 

1657 - `union_member_0: string`

1658 

1659 The container ID.

1660 

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

1662 

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

1664 

1665 - `type: "auto"`

1666 

1667 Always `auto`.

1668 

1669 - `file_ids: optional array of string`

1670 

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

1672 

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

1674 

1675 The memory limit for the code interpreter container.

1676 

1677 - `"1g"`

1678 

1679 - `"4g"`

1680 

1681 - `"16g"`

1682 

1683 - `"64g"`

1684 

1685 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1686 

1687 Network access policy for the container.

1688 

1689 - `container_network_policy_disabled: object { type }`

1690 

1691 - `type: "disabled"`

1692 

1693 Disable outbound network access. Always `disabled`.

1694 

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

1696 

1697 - `allowed_domains: array of string`

1698 

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

1700 

1701 - `type: "allowlist"`

1702 

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

1704 

1705 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1706 

1707 Optional domain-scoped secrets for allowlisted domains.

1708 

1709 - `domain: string`

1710 

1711 The domain associated with the secret.

1712 

1713 - `name: string`

1714 

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

1716 

1717 - `value: string`

1718 

1719 The secret value to inject for the domain.

1720 

1721 - `type: "code_interpreter"`

1722 

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

1724 

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

1726 

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

1728 

1729 - `type: "image_generation"`

1730 

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

1732 

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

1734 

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

1736 

1737 - `"generate"`

1738 

1739 - `"edit"`

1740 

1741 - `"auto"`

1742 

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

1744 

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

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

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

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

1749 automatically determine the best background for the image.

1750 

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

1752 transparent backgrounds. Requests with `background` set to

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

1754 `auto` instead.

1755 

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

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

1758 

1759 - `"transparent"`

1760 

1761 - `"opaque"`

1762 

1763 - `"auto"`

1764 

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

1766 

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

1768 

1769 - `"high"`

1770 

1771 - `"low"`

1772 

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

1774 

1775 Optional mask for inpainting. Contains `image_url`

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

1777 

1778 - `file_id: optional string`

1779 

1780 File ID for the mask image.

1781 

1782 - `image_url: optional string`

1783 

1784 Base64-encoded mask image.

1785 

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

1787 

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

1789 

1790 - `"gpt-image-1"`

1791 

1792 - `"gpt-image-1-mini"`

1793 

1794 - `"gpt-image-2"`

1795 

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

1797 

1798 - `"gpt-image-1.5"`

1799 

1800 - `"chatgpt-image-latest"`

1801 

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

1803 

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

1805 

1806 - `"auto"`

1807 

1808 - `"low"`

1809 

1810 - `output_compression: optional number`

1811 

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

1813 

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

1815 

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

1817 `jpeg`. Default: `png`.

1818 

1819 - `"png"`

1820 

1821 - `"webp"`

1822 

1823 - `"jpeg"`

1824 

1825 - `partial_images: optional number`

1826 

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

1828 

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

1830 

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

1832 or `auto`. Default: `auto`.

1833 

1834 - `"low"`

1835 

1836 - `"medium"`

1837 

1838 - `"high"`

1839 

1840 - `"auto"`

1841 

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

1843 

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

1845 

1846 - `"1024x1024"`

1847 

1848 - `"1024x1536"`

1849 

1850 - `"1536x1024"`

1851 

1852 - `"auto"`

1853 

1854 - `local_shell: object { type }`

1855 

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

1857 

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

1859 

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

1861 

1862 - `type: "shell"`

1863 

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

1865 

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

1867 

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

1869 

1870 - `type: "container_auto"`

1871 

1872 Automatically creates a container for this request

1873 

1874 - `file_ids: optional array of string`

1875 

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

1877 

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

1879 

1880 The memory limit for the container.

1881 

1882 - `"1g"`

1883 

1884 - `"4g"`

1885 

1886 - `"16g"`

1887 

1888 - `"64g"`

1889 

1890 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1891 

1892 Network access policy for the container.

1893 

1894 - `container_network_policy_disabled: object { type }`

1895 

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

1897 

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

1899 

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

1901 

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

1903 

1904 - `skill_id: string`

1905 

1906 The ID of the referenced skill.

1907 

1908 - `type: "skill_reference"`

1909 

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

1911 

1912 - `version: optional string`

1913 

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

1915 

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

1917 

1918 - `description: string`

1919 

1920 The description of the skill.

1921 

1922 - `name: string`

1923 

1924 The name of the skill.

1925 

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

1927 

1928 Inline skill payload

1929 

1930 - `data: string`

1931 

1932 Base64-encoded skill zip bundle.

1933 

1934 - `media_type: "application/zip"`

1935 

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

1937 

1938 - `type: "base64"`

1939 

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

1941 

1942 - `type: "inline"`

1943 

1944 Defines an inline skill for this request.

1945 

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

1947 

1948 - `type: "local"`

1949 

1950 Use a local computer environment.

1951 

1952 - `skills: optional array of LocalSkill`

1953 

1954 An optional list of skills.

1955 

1956 - `description: string`

1957 

1958 The description of the skill.

1959 

1960 - `name: string`

1961 

1962 The name of the skill.

1963 

1964 - `path: string`

1965 

1966 The path to the directory containing the skill.

1967 

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

1969 

1970 - `container_id: string`

1971 

1972 The ID of the referenced container.

1973 

1974 - `type: "container_reference"`

1975 

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

1977 

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

1979 

1980 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)

1981 

1982 - `name: string`

1983 

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

1985 

1986 - `type: "custom"`

1987 

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

1989 

1990 - `defer_loading: optional boolean`

1991 

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

1993 

1994 - `description: optional string`

1995 

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