resources/conversations/subresources/items/methods/retrieve/index.md 2026-09-16 22:58 UTC to 2026-09-18 22:59 UTC

1## Retrieve an item

2 

3**get** `/conversations/{conversation_id}/items/{item_id}`

4 

5Get a single item from a conversation with the given IDs.

6 

7### Path Parameters

8 

9- `conversation_id: string`

10 

11- `item_id: string`

12 

13### Query Parameters

14 

15- `include: optional array of ResponseIncludable`

16 

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

18 parameter for [listing Conversation items above](/api/reference/resources/conversations/subresources/items/methods/list#%28resource%29%20conversations.items%20%3E%20%28method%29%20list%20%3E%20%28params%29%20default%20%3E%20%28param%29%20include%20%3E%20%28schema%29) for more information.

19 

20 - `"file_search_call.results"`

21 

22 - `"web_search_call.results"`

23 

24 - `"web_search_call.action.sources"`

25 

26 - `"message.input_image.image_url"`

27 

28 - `"computer_call_output.output.image_url"`

29 

30 - `"code_interpreter_call.outputs"`

31 

32 - `"reasoning.encrypted_content"`

33 

34 - `"message.output_text.logprobs"`

35 

36### Returns

37 

38- `ConversationItem = Message or object { id, arguments, call_id, 7 more } or object { id, output, status, 6 more } or 26 more`

39 

40 A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](/api/reference/resources/responses#%28resource%29%20responses%20%3E%20%28model%29%20response%20%3E%20%28schema%29%20%3E%20%28property%29%20output).

41 

42 - `Message object { id, content, role, 3 more }`

43 

44 A message to or from the model.

45 

46 - `id: string`

47 

48 The unique ID of the message.

49 

50 - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more`

51 

52 The content of the message

53 

54 - `ResponseInputText object { text, type, prompt_cache_breakpoint }`

55 

56 A text input to the model.

57 

58 - `text: string`

59 

60 The text input to the model.

61 

62 - `type: "input_text"`

63 

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

65 

66 - `"input_text"`

67 

68 - `prompt_cache_breakpoint: optional object { mode }`

69 

70 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

71 

72 - `mode: "explicit"`

73 

74 The breakpoint mode. Always `explicit`.

75 

76 - `"explicit"`

77 

78 - `ResponseOutputText object { annotations, logprobs, text, type }`

79 

80 A text output from the model.

81 

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

83 

84 The annotations of the text output.

85 

86 - `FileCitation object { file_id, filename, index, type }`

87 

88 A citation to a file.

89 

90 - `file_id: string`

91 

92 The ID of the file.

93 

94 - `filename: string`

95 

96 The filename of the file cited.

97 

98 - `index: number`

99 

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

101 

102 - `type: "file_citation"`

103 

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

105 

106 - `"file_citation"`

107 

108 - `URLCitation object { end_index, start_index, title, 2 more }`

109 

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

111 

112 - `end_index: number`

113 

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

115 

116 - `start_index: number`

117 

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

119 

120 - `title: string`

121 

122 The title of the web resource.

123 

124 - `type: "url_citation"`

125 

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

127 

128 - `"url_citation"`

129 

130 - `url: string`

131 

132 The URL of the web resource.

133 

134 - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }`

135 

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

137 

138 - `container_id: string`

139 

140 The ID of the container file.

141 

142 - `end_index: number`

143 

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

145 

146 - `file_id: string`

147 

148 The ID of the file.

149 

150 - `filename: string`

151 

152 The filename of the container file cited.

153 

154 - `start_index: number`

155 

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

157 

158 - `type: "container_file_citation"`

159 

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

161 

162 - `"container_file_citation"`

163 

164 - `FilePath object { file_id, index, type }`

165 

166 A path to a file.

167 

168 - `file_id: string`

169 

170 The ID of the file.

171 

172 - `index: number`

173 

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

175 

176 - `type: "file_path"`

177 

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

179 

180 - `"file_path"`

181 

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

183 

184 - `token: string`

185 

186 - `bytes: array of number`

187 

188 - `logprob: number`

189 

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

191 

192 - `token: string`

193 

194 - `bytes: array of number`

195 

196 - `logprob: number`

197 

198 - `text: string`

199 

200 The text output from the model.

201 

202 - `type: "output_text"`

203 

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

205 

206 - `"output_text"`

207 

208 - `TextContent object { text, type }`

209 

210 A text content.

211 

212 - `text: string`

213 

214 - `type: "text"`

215 

216 - `"text"`

217 

218 - `SummaryTextContent object { text, type }`

219 

220 A summary text from the model.

221 

222 - `text: string`

223 

224 A summary of the reasoning output from the model so far.

225 

226 - `type: "summary_text"`

227 

228 The type of the object. Always `summary_text`.

229 

230 - `"summary_text"`

231 

232 - `ReasoningText object { text, type }`

233 

234 Reasoning text from the model.

235 

236 - `text: string`

237 

238 The reasoning text from the model.

239 

240 - `type: "reasoning_text"`

241 

242 The type of the reasoning text. Always `reasoning_text`.

243 

244 - `"reasoning_text"`

245 

246 - `ResponseOutputRefusal object { refusal, type }`

247 

248 A refusal from the model.

249 

250 - `refusal: string`

251 

252 The refusal explanation from the model.

253 

254 - `type: "refusal"`

255 

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

257 

258 - `"refusal"`

259 

260 - `ResponseInputImage object { detail, type, file_id, 2 more }`

261 

262 An image input to the model. Learn about [image inputs](/api/docs/guides/images-vision).

263 

264 - `detail: ImageDetail`

265 

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

267 

268 - `"low"`

269 

270 - `"high"`

271 

272 - `"auto"`

273 

274 - `"original"`

275 

276 - `type: "input_image"`

277 

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

279 

280 - `"input_image"`

281 

282 - `file_id: optional string or null`

283 

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

285 

286 - `image_url: optional string or null`

287 

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

289 

290 - `prompt_cache_breakpoint: optional object { mode }`

291 

292 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

293 

294 - `mode: "explicit"`

295 

296 The breakpoint mode. Always `explicit`.

297 

298 - `"explicit"`

299 

300 - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }`

301 

302 A screenshot of a computer.

303 

304 - `detail: ImageDetail`

305 

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

307 

308 - `file_id: string or null`

309 

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

311 

312 - `image_url: string or null`

313 

314 The URL of the screenshot image.

315 

316 - `type: "computer_screenshot"`

317 

318 Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`.

319 

320 - `"computer_screenshot"`

321 

322 - `prompt_cache_breakpoint: optional object { mode }`

323 

324 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

325 

326 - `mode: "explicit"`

327 

328 The breakpoint mode. Always `explicit`.

329 

330 - `"explicit"`

331 

332 - `ResponseInputFile object { type, detail, file_data, 4 more }`

333 

334 A file input to the model.

335 

336 - `type: "input_file"`

337 

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

339 

340 - `"input_file"`

341 

342 - `detail: optional "auto" or "low" or "high"`

343 

344 The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`.

345 

346 - `"auto"`

347 

348 - `"low"`

349 

350 - `"high"`

351 

352 - `file_data: optional string`

353 

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

355 

356 - `file_id: optional string or null`

357 

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

359 

360 - `file_url: optional string`

361 

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

363 

364 - `filename: optional string`

365 

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

367 

368 - `prompt_cache_breakpoint: optional object { mode }`

369 

370 Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

371 

372 - `mode: "explicit"`

373 

374 The breakpoint mode. Always `explicit`.

375 

376 - `"explicit"`

377 

378 - `role: "unknown" or "user" or "assistant" or 5 more`

379 

380 The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`.

381 

382 - `"unknown"`

383 

384 - `"user"`

385 

386 - `"assistant"`

387 

388 - `"system"`

389 

390 - `"critic"`

391 

392 - `"discriminator"`

393 

394 - `"developer"`

395 

396 - `"tool"`

397 

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

399 

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

401 

402 - `"in_progress"`

403 

404 - `"completed"`

405 

406 - `"incomplete"`

407 

408 - `type: "message"`

409 

410 The type of the message. Always set to `message`.

411 

412 - `"message"`

413 

414 - `phase: optional "commentary" or "final_answer" or null`

415 

416 Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

417 

418 - `"commentary"`

419 

420 - `"final_answer"`

421 

422 - `FunctionCall object { id, arguments, call_id, 7 more }`

423 

424 - `id: string`

425 

426 The unique ID of the function tool call.

427 

428 - `arguments: string`

429 

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

431 

432 - `call_id: string`

433 

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

435 

436 - `name: string`

437 

438 The name of the function to run.

439 

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

441 

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

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

444 

445 - `"in_progress"`

446 

447 - `"completed"`

448 

449 - `"incomplete"`

450 

451 - `type: "function_call"`

452 

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

454 

455 - `"function_call"`

456 

457 - `async: optional boolean`

458 

459 Whether the function tool call runs asynchronously.

460 

461 - `caller: optional object { type } or object { caller_id, type } or null`

462 

463 The execution context that produced this tool call.

464 

465 - `Direct object { type }`

466 

467 - `type: "direct"`

468 

469 - `"direct"`

470 

471 - `Program object { caller_id, type }`

472 

473 - `caller_id: string`

474 

475 The call ID of the program item that produced this tool call.

476 

477 - `type: "program"`

478 

479 - `"program"`

480 

481 - `created_by: optional string`

482 

483 The identifier of the actor that created the item.

484 

485 - `namespace: optional string`

486 

487 The namespace of the function to run.

488 

489 - `FunctionCallOutput object { id, output, status, 6 more }`

490 

491 - `id: string`

492 

493 The unique ID of the function call tool output.

494 

495 - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile`

496 

497 The output from the function call generated by your code.

498 Can be a string or an list of output content.

499 

500 - `StringOutput = string`

501 

502 A string of the output of the function call.

503 

504 - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile`

505 

506 Text, image, or file output of the function call.

507 

508 - `ResponseInputText object { text, type, prompt_cache_breakpoint }`

509 

510 A text input to the model.

511 

512 - `ResponseInputImage object { detail, type, file_id, 2 more }`

513 

514 An image input to the model. Learn about [image inputs](/api/docs/guides/images-vision).

515 

516 - `ResponseInputFile object { type, detail, file_data, 4 more }`

517 

518 A file input to the model.

519 

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

521 

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

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

524 

525 - `"in_progress"`

526 

527 - `"completed"`

528 

529 - `"incomplete"`

530 

531 - `type: "function_call_output"`

532 

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

534 

535 - `"function_call_output"`

536 

537 - `call_id: optional string`

538 

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

540 

541 - `caller: optional object { type } or object { caller_id, type } or null`

542 

543 The execution context that produced this tool call.

544 

545 - `Direct object { type }`

546 

547 - `type: "direct"`

548 

549 The caller type. Always `direct`.

550 

551 - `"direct"`

552 

553 - `Program object { caller_id, type }`

554 

555 - `caller_id: string`

556 

557 The call ID of the program item that produced this tool call.

558 

559 - `type: "program"`

560 

561 The caller type. Always `program`.

562 

563 - `"program"`

564 

565 - `created_by: optional string`

566 

567 The identifier of the actor that created the item.

568 

569 - `name: optional string`

570 

571 The name of the tool that produced the output.

572 

573 - `namespace: optional string`

574 

575 The namespace of the tool that produced the output.

576 

577 - `FileSearchCall object { id, queries, status, 2 more }`

578 

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

580 [file search guide](/api/docs/guides/tools-file-search) for more information.

581 

582 - `id: string`

583 

584 The unique ID of the file search tool call.

585 

586 - `queries: array of string`

587 

588 The queries used to search for files.

589 

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

591 

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

593 `searching`, `incomplete` or `failed`,

594 

595 - `"in_progress"`

596 

597 - `"searching"`

598 

599 - `"completed"`

600 

601 - `"incomplete"`

602 

603 - `"failed"`

604 

605 - `type: "file_search_call"`

606 

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

608 

609 - `"file_search_call"`

610 

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

612 

613 The results of the file search tool call.

614 

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

616 

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

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

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

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

621 length of 512 characters, booleans, or numbers.

622 

623 - `string`

624 

625 - `number`

626 

627 - `boolean`

628 

629 - `file_id: optional string`

630 

631 The unique ID of the file.

632 

633 - `filename: optional string`

634 

635 The name of the file.

636 

637 - `score: optional number`

638 

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

640 

641 - `text: optional string`

642 

643 The text that was retrieved from the file.

644 

645 - `WebSearchCall object { id, action, status, type }`

646 

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

648 [web search guide](/api/docs/guides/tools-web-search) for more information.

649 

650 - `id: string`

651 

652 The unique ID of the web search tool call.

653 

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

655 

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

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

658 

659 - `Search object { type, queries, query, sources }`

660 

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

662 

663 - `type: "search"`

664 

665 The action type.

666 

667 - `"search"`

668 

669 - `queries: optional array of string`

670 

671 The search queries.

672 

673 - `query: optional string`

674 

675 The search query.

676 

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

678 

679 The sources used in the search.

680 

681 - `type: "url"`

682 

683 The type of source. Always `url`.

684 

685 - `"url"`

686 

687 - `url: string`

688 

689 The URL of the source.

690 

691 - `OpenPage object { type, url }`

692 

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

694 

695 - `type: "open_page"`

696 

697 The action type.

698 

699 - `"open_page"`

700 

701 - `url: optional string or null`

702 

703 The URL opened by the model.

704 

705 - `FindInPage object { pattern, type, url }`

706 

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

708 

709 - `pattern: string`

710 

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

712 

713 - `type: "find_in_page"`

714 

715 The action type.

716 

717 - `"find_in_page"`

718 

719 - `url: string`

720 

721 The URL of the page searched for the pattern.

722 

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

724 

725 The status of the web search tool call.

726 

727 - `"in_progress"`

728 

729 - `"searching"`

730 

731 - `"completed"`

732 

733 - `"failed"`

734 

735 - `"incomplete"`

736 

737 - `type: "web_search_call"`

738 

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

740 

741 - `"web_search_call"`

742 

743 - `ImageGenerationCall object { id, result, status, 7 more }`

744 

745 An image generation request made by the model.

746 

747 - `id: string`

748 

749 The unique ID of the image generation call.

750 

751 - `result: string or null`

752 

753 The generated image encoded in base64.

754 

755 - `status: "in_progress" or "completed" or "generating" or "failed"`

756 

757 The status of the image generation call.

758 

759 - `"in_progress"`

760 

761 - `"completed"`

762 

763 - `"generating"`

764 

765 - `"failed"`

766 

767 - `type: "image_generation_call"`

768 

769 The type of the image generation call. Always `image_generation_call`.

770 

771 - `"image_generation_call"`

772 

773 - `action: optional "generate" or "edit" or "auto" or null`

774 

775 The action used for image generation.

776 

777 - `"generate"`

778 

779 - `"edit"`

780 

781 - `"auto"`

782 

783 - `background: optional "transparent" or "opaque" or "auto" or null`

784 

785 The background setting used for generation.

786 

787 - `"transparent"`

788 

789 - `"opaque"`

790 

791 - `"auto"`

792 

793 - `output_format: optional "png" or "webp" or "jpeg" or null`

794 

795 The output format used for generation.

796 

797 - `"png"`

798 

799 - `"webp"`

800 

801 - `"jpeg"`

802 

803 - `quality: optional "low" or "medium" or "high" or 3 more or null`

804 

805 The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`.

806 

807 - `"low"`

808 

809 - `"medium"`

810 

811 - `"high"`

812 

813 - `"xhigh"`

814 

815 - `"max"`

816 

817 - `"auto"`

818 

819 - `revised_prompt: optional string or null`

820 

821 The prompt that was used after any model prompt rewriting.

822 

823 - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null`

824 

825 The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`.

826 

827 - `string`

828 

829 - `"1024x1024" or "1024x1536" or "1536x1024"`

830 

831 The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`.

832 

833 - `"1024x1024"`

834 

835 - `"1024x1536"`

836 

837 - `"1536x1024"`

838 

839 - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }`

840 

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

842 [computer use guide](/api/docs/guides/tools-computer-use) for more information.

843 

844 - `id: string`

845 

846 The unique ID of the computer call.

847 

848 - `call_id: string`

849 

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

851 

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

853 

854 The pending safety checks for the computer call.

855 

856 - `id: string`

857 

858 The ID of the pending safety check.

859 

860 - `code: optional string or null`

861 

862 The type of the pending safety check.

863 

864 - `message: optional string or null`

865 

866 Details about the pending safety check.

867 

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

869 

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

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

872 

873 - `"in_progress"`

874 

875 - `"completed"`

876 

877 - `"incomplete"`

878 

879 - `type: "computer_call"`

880 

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

882 

883 - `"computer_call"`

884 

885 - `action: optional ComputerAction`

886 

887 A click action.

888 

889 - `Click object { button, type, x, 2 more }`

890 

891 A click action.

892 

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

894 

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

896 

897 - `"left"`

898 

899 - `"right"`

900 

901 - `"wheel"`

902 

903 - `"back"`

904 

905 - `"forward"`

906 

907 - `type: "click"`

908 

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

910 

911 - `"click"`

912 

913 - `x: number`

914 

915 The x-coordinate where the click occurred.

916 

917 - `y: number`

918 

919 The y-coordinate where the click occurred.

920 

921 - `keys: optional array of string or null`

922 

923 The keys being held while clicking.

924 

925 - `DoubleClick object { keys, type, x, y }`

926 

927 A double click action.

928 

929 - `keys: array of string or null`

930 

931 The keys being held while double-clicking.

932 

933 - `type: "double_click"`

934 

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

936 

937 - `"double_click"`

938 

939 - `x: number`

940 

941 The x-coordinate where the double click occurred.

942 

943 - `y: number`

944 

945 The y-coordinate where the double click occurred.

946 

947 - `Drag object { path, type, keys }`

948 

949 A drag action.

950 

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

952 

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

954 

955 ```

956 [

957 { x: 100, y: 200 },

958 { x: 200, y: 300 }

959 ]

960 ```

961 

962 - `x: number`

963 

964 The x-coordinate.

965 

966 - `y: number`

967 

968 The y-coordinate.

969 

970 - `type: "drag"`

971 

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

973 

974 - `"drag"`

975 

976 - `keys: optional array of string or null`

977 

978 The keys being held while dragging the mouse.

979 

980 - `Keypress object { keys, type }`

981 

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

983 

984 - `keys: array of string`

985 

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

987 

988 - `type: "keypress"`

989 

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

991 

992 - `"keypress"`

993 

994 - `Move object { type, x, y, keys }`

995 

996 A mouse move action.

997 

998 - `type: "move"`

999 

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

1001 

1002 - `"move"`

1003 

1004 - `x: number`

1005 

1006 The x-coordinate to move to.

1007 

1008 - `y: number`

1009 

1010 The y-coordinate to move to.

1011 

1012 - `keys: optional array of string or null`

1013 

1014 The keys being held while moving the mouse.

1015 

1016 - `Screenshot object { type }`

1017 

1018 A screenshot action.

1019 

1020 - `type: "screenshot"`

1021 

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

1023 

1024 - `"screenshot"`

1025 

1026 - `Scroll object { scroll_x, scroll_y, type, 3 more }`

1027 

1028 A scroll action.

1029 

1030 - `scroll_x: number`

1031 

1032 The horizontal scroll distance.

1033 

1034 - `scroll_y: number`

1035 

1036 The vertical scroll distance.

1037 

1038 - `type: "scroll"`

1039 

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

1041 

1042 - `"scroll"`

1043 

1044 - `x: number`

1045 

1046 The x-coordinate where the scroll occurred.

1047 

1048 - `y: number`

1049 

1050 The y-coordinate where the scroll occurred.

1051 

1052 - `keys: optional array of string or null`

1053 

1054 The keys being held while scrolling.

1055 

1056 - `Type object { text, type }`

1057 

1058 An action to type in text.

1059 

1060 - `text: string`

1061 

1062 The text to type.

1063 

1064 - `type: "type"`

1065 

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

1067 

1068 - `"type"`

1069 

1070 - `Wait object { type }`

1071 

1072 A wait action.

1073 

1074 - `type: "wait"`

1075 

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

1077 

1078 - `"wait"`

1079 

1080 - `actions: optional ComputerActionList`

1081 

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

1083 `type` discriminator and action-specific fields.

1084 

1085 - `Click object { button, type, x, 2 more }`

1086 

1087 A click action.

1088 

1089 - `DoubleClick object { keys, type, x, y }`

1090 

1091 A double click action.

1092 

1093 - `Drag object { path, type, keys }`

1094 

1095 A drag action.

1096 

1097 - `Keypress object { keys, type }`

1098 

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

1100 

1101 - `Move object { type, x, y, keys }`

1102 

1103 A mouse move action.

1104 

1105 - `Screenshot object { type }`

1106 

1107 A screenshot action.

1108 

1109 - `Scroll object { scroll_x, scroll_y, type, 3 more }`

1110 

1111 A scroll action.

1112 

1113 - `Type object { text, type }`

1114 

1115 An action to type in text.

1116 

1117 - `Wait object { type }`

1118 

1119 A wait action.

1120 

1121 - `ComputerCallOutput object { id, call_id, output, 4 more }`

1122 

1123 - `id: string`

1124 

1125 The unique ID of the computer call tool output.

1126 

1127 - `call_id: string`

1128 

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

1130 

1131 - `output: ResponseComputerToolCallOutputScreenshot`

1132 

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

1134 

1135 - `type: "computer_screenshot"`

1136 

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

1138 always set to `computer_screenshot`.

1139 

1140 - `"computer_screenshot"`

1141 

1142 - `file_id: optional string`

1143 

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

1145 

1146 - `image_url: optional string`

1147 

1148 The URL of the screenshot image.

1149 

1150 - `status: "completed" or "incomplete" or "failed" or "in_progress"`

1151 

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

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

1154 

1155 - `"completed"`

1156 

1157 - `"incomplete"`

1158 

1159 - `"failed"`

1160 

1161 - `"in_progress"`

1162 

1163 - `type: "computer_call_output"`

1164 

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

1166 

1167 - `"computer_call_output"`

1168 

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

1170 

1171 The safety checks reported by the API that have been acknowledged by the

1172 developer.

1173 

1174 - `id: string`

1175 

1176 The ID of the pending safety check.

1177 

1178 - `code: optional string or null`

1179 

1180 The type of the pending safety check.

1181 

1182 - `message: optional string or null`

1183 

1184 Details about the pending safety check.

1185 

1186 - `created_by: optional string`

1187 

1188 The identifier of the actor that created the item.

1189 

1190 - `ToolSearchCall object { id, arguments, call_id, 4 more }`

1191 

1192 - `id: string`

1193 

1194 The unique ID of the tool search call item.

1195 

1196 - `arguments: unknown`

1197 

1198 Arguments used for the tool search call.

1199 

1200 - `call_id: string or null`

1201 

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

1203 

1204 - `execution: "server" or "client"`

1205 

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

1207 

1208 - `"server"`

1209 

1210 - `"client"`

1211 

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

1213 

1214 The status of the tool search call item that was recorded.

1215 

1216 - `"in_progress"`

1217 

1218 - `"completed"`

1219 

1220 - `"incomplete"`

1221 

1222 - `type: "tool_search_call"`

1223 

1224 The type of the item. Always `tool_search_call`.

1225 

1226 - `"tool_search_call"`

1227 

1228 - `created_by: optional string`

1229 

1230 The identifier of the actor that created the item.

1231 

1232 - `ToolSearchOutput object { id, call_id, execution, 4 more }`

1233 

1234 - `id: string`

1235 

1236 The unique ID of the tool search output item.

1237 

1238 - `call_id: string or null`

1239 

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

1241 

1242 - `execution: "server" or "client"`

1243 

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

1245 

1246 - `"server"`

1247 

1248 - `"client"`

1249 

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

1251 

1252 The status of the tool search output item that was recorded.

1253 

1254 - `"in_progress"`

1255 

1256 - `"completed"`

1257 

1258 - `"incomplete"`

1259 

1260 - `tools: array of object { name, parameters, strict, 6 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more`

1261 

1262 The loaded tool definitions returned by tool search.

1263 

1264 - `Function object { name, parameters, strict, 6 more }`

1265 

1266 Defines a function in your own code the model can choose to call. Learn more about [function calling](/api/docs/guides/function-calling).

1267 

1268 - `name: string`

1269 

1270 The name of the function to call.

1271 

1272 - `parameters: map[unknown] or null`

1273 

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

1275 

1276 - `strict: boolean or null`

1277 

1278 Whether strict parameter validation is enforced for this function tool.

1279 

1280 - `type: "function"`

1281 

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

1283 

1284 - `"function"`

1285 

1286 - `allowed_callers: optional array of "direct" or "programmatic" or null`

1287 

1288 The tool invocation context(s).

1289 

1290 - `"direct"`

1291 

1292 - `"programmatic"`

1293 

1294 - `async: optional boolean`

1295 

1296 - `defer_loading: optional boolean`

1297 

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

1299 

1300 - `description: optional string or null`

1301 

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

1303 

1304 - `output_schema: optional map[unknown] or null`

1305 

1306 A JSON schema object describing the JSON value encoded in string outputs for this function.

1307 

1308 - `FileSearch object { type, vector_store_ids, filters, 2 more }`

1309 

1310 A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](/api/docs/guides/tools-file-search).

1311 

1312 - `type: "file_search"`

1313 

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

1315 

1316 - `"file_search"`

1317 

1318 - `vector_store_ids: array of string`

1319 

1320 The IDs of the vector stores to search.

1321 

1322 - `filters: optional ComparisonFilter or CompoundFilter or null`

1323 

1324 A filter to apply.

1325 

1326 - `ComparisonFilter object { key, type, value }`

1327 

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

1329 

1330 - `key: string`

1331 

1332 The key to compare against the value.

1333 

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

1335 

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

1337 

1338 - `eq`: equals

1339 - `ne`: not equal

1340 - `gt`: greater than

1341 - `gte`: greater than or equal

1342 - `lt`: less than

1343 - `lte`: less than or equal

1344 - `in`: in

1345 - `nin`: not in

1346 

1347 - `"eq"`

1348 

1349 - `"ne"`

1350 

1351 - `"gt"`

1352 

1353 - `"gte"`

1354 

1355 - `"lt"`

1356 

1357 - `"lte"`

1358 

1359 - `"in"`

1360 

1361 - `"nin"`

1362 

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

1364 

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

1366 

1367 - `string`

1368 

1369 - `number`

1370 

1371 - `boolean`

1372 

1373 - `array of string or number`

1374 

1375 - `string`

1376 

1377 - `number`

1378 

1379 - `CompoundFilter object { filters, type }`

1380 

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

1382 

1383 - `filters: array of ComparisonFilter or unknown`

1384 

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

1386 

1387 - `ComparisonFilter object { key, type, value }`

1388 

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

1390 

1391 - `unknown`

1392 

1393 - `type: "and" or "or"`

1394 

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

1396 

1397 - `"and"`

1398 

1399 - `"or"`

1400 

1401 - `max_num_results: optional number`

1402 

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

1404 

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

1406 

1407 Ranking options for search.

1408 

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

1410 

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

1412 

1413 - `embedding_weight: number`

1414 

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

1416 

1417 - `text_weight: number`

1418 

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

1420 

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

1422 

1423 The ranker to use for the file search.

1424 

1425 - `"auto"`

1426 

1427 - `"default-2024-11-15"`

1428 

1429 - `score_threshold: optional number`

1430 

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

1432 

1433 - `Computer object { type }`

1434 

1435 A tool that controls a virtual computer. Learn more about the [computer tool](/api/docs/guides/tools-computer-use).

1436 

1437 - `type: "computer"`

1438 

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

1440 

1441 - `"computer"`

1442 

1443 - `ComputerUsePreview object { display_height, display_width, environment, type }`

1444 

1445 A tool that controls a virtual computer. Learn more about the [computer tool](/api/docs/guides/tools-computer-use).

1446 

1447 - `display_height: number`

1448 

1449 The height of the computer display.

1450 

1451 - `display_width: number`

1452 

1453 The width of the computer display.

1454 

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

1456 

1457 The type of computer environment to control.

1458 

1459 - `"windows"`

1460 

1461 - `"mac"`

1462 

1463 - `"linux"`

1464 

1465 - `"ubuntu"`

1466 

1467 - `"browser"`

1468 

1469 - `type: "computer_use_preview"`

1470 

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

1472 

1473 - `"computer_use_preview"`

1474 

1475 - `WebSearch object { type, external_web_access, filters, 2 more }`

1476 

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

1478 [web search tool](/api/docs/guides/tools-web-search).

1479 

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

1481 

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

1483 

1484 - `"web_search"`

1485 

1486 - `"web_search_2025_08_26"`

1487 

1488 - `external_web_access: optional boolean`

1489 

1490 Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content.

1491 

1492 - `filters: optional object { allowed_domains } or null`

1493 

1494 Filters for the search.

1495 

1496 - `allowed_domains: optional array of string or null`

1497 

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

1499 Subdomains of the provided domains are allowed as well.

1500 

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

1502 

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

1504 

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

1506 

1507 - `"low"`

1508 

1509 - `"medium"`

1510 

1511 - `"high"`

1512 

1513 - `user_location: optional object { city, country, region, 2 more } or null`

1514 

1515 The approximate location of the user.

1516 

1517 - `city: optional string or null`

1518 

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

1520 

1521 - `country: optional string or null`

1522 

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

1524 

1525 - `region: optional string or null`

1526 

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

1528 

1529 - `timezone: optional string or null`

1530 

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

1532 

1533 - `type: optional "approximate"`

1534 

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

1536 

1537 - `"approximate"`

1538 

1539 - `Mcp object { server_label, type, allowed_callers, 9 more }`

1540 

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

1542 (MCP) servers. [Learn more about MCP](/api/docs/guides/tools-connectors-mcp).

1543 

1544 - `server_label: string`

1545 

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

1547 

1548 - `type: "mcp"`

1549 

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

1551 

1552 - `"mcp"`

1553 

1554 - `allowed_callers: optional array of "direct" or "programmatic" or null`

1555 

1556 The tool invocation context(s).

1557 

1558 - `"direct"`

1559 

1560 - `"programmatic"`

1561 

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

1563 

1564 List of allowed tool names or a filter object.

1565 

1566 - `McpAllowedTools = array of string`

1567 

1568 A string array of allowed tool names

1569 

1570 - `McpToolFilter object { read_only, tool_names }`

1571 

1572 A filter object to specify which tools are allowed.

1573 

1574 - `read_only: optional boolean`

1575 

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

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

1578 it will match this filter.

1579 

1580 - `tool_names: optional array of string`

1581 

1582 List of allowed tool names.

1583 

1584 - `authorization: optional string`

1585 

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

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

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

1589 

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

1591 

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

1593 `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more

1594 about service connectors [here](/api/docs/guides/tools-connectors-mcp#connectors).

1595 

1596 This field is deprecated for models released after September 1, 2026.

1597 Use `server_url` to connect to a remote MCP server, or `tunnel_id` to

1598 connect through a Secure MCP Tunnel.

1599 

1600 Currently supported `connector_id` values are:

1601 

1602 - Dropbox: `connector_dropbox`

1603 - Gmail: `connector_gmail`

1604 - Google Calendar: `connector_googlecalendar`

1605 - Google Drive: `connector_googledrive`

1606 - Microsoft Teams: `connector_microsoftteams`

1607 - Outlook Calendar: `connector_outlookcalendar`

1608 - Outlook Email: `connector_outlookemail`

1609 - SharePoint: `connector_sharepoint`

1610 

1611 - `"connector_dropbox"`

1612 

1613 - `"connector_gmail"`

1614 

1615 - `"connector_googlecalendar"`

1616 

1617 - `"connector_googledrive"`

1618 

1619 - `"connector_microsoftteams"`

1620 

1621 - `"connector_outlookcalendar"`

1622 

1623 - `"connector_outlookemail"`

1624 

1625 - `"connector_sharepoint"`

1626 

1627 - `defer_loading: optional boolean`

1628 

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

1630 

1631 - `headers: optional map[string] or null`

1632 

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

1634 or other purposes.

1635 

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

1637 

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

1639 

1640 - `McpToolApprovalFilter object { always, never }`

1641 

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

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

1644 that require approval.

1645 

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

1647 

1648 A filter object to specify which tools are allowed.

1649 

1650 - `read_only: optional boolean`

1651 

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

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

1654 it will match this filter.

1655 

1656 - `tool_names: optional array of string`

1657 

1658 List of allowed tool names.

1659 

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

1661 

1662 A filter object to specify which tools are allowed.

1663 

1664 - `read_only: optional boolean`

1665 

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

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

1668 it will match this filter.

1669 

1670 - `tool_names: optional array of string`

1671 

1672 List of allowed tool names.

1673 

1674 - `McpToolApprovalSetting = "always" or "never"`

1675 

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

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

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

1679 

1680 - `"always"`

1681 

1682 - `"never"`

1683 

1684 - `server_description: optional string`

1685 

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

1687 

1688 - `server_url: optional string`

1689 

1690 The URL for the MCP server. One of `server_url`, `connector_id`, or

1691 `tunnel_id` must be provided.

1692 

1693 - `tunnel_id: optional string`

1694 

1695 The Secure MCP Tunnel ID to use instead of a direct server URL. One of

1696 `server_url`, `connector_id`, or `tunnel_id` must be provided.

1697 

1698 - `CodeInterpreter object { container, type, allowed_callers }`

1699 

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

1701 

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

1703 

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

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

1706 optional `memory_limit` setting.

1707 

1708 - `string`

1709 

1710 The container ID.

1711 

1712 - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }`

1713 

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

1715 

1716 - `type: "auto"`

1717 

1718 Always `auto`.

1719 

1720 - `"auto"`

1721 

1722 - `file_ids: optional array of string`

1723 

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

1725 

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

1727 

1728 The memory limit for the code interpreter container.

1729 

1730 - `"1g"`

1731 

1732 - `"4g"`

1733 

1734 - `"16g"`

1735 

1736 - `"64g"`

1737 

1738 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1739 

1740 Network access policy for the container.

1741 

1742 - `ContainerNetworkPolicyDisabled object { type }`

1743 

1744 - `type: "disabled"`

1745 

1746 Disable outbound network access. Always `disabled`.

1747 

1748 - `"disabled"`

1749 

1750 - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }`

1751 

1752 - `allowed_domains: array of string`

1753 

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

1755 

1756 - `type: "allowlist"`

1757 

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

1759 

1760 - `"allowlist"`

1761 

1762 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1763 

1764 Optional domain-scoped secrets for allowlisted domains.

1765 

1766 - `domain: string`

1767 

1768 The domain associated with the secret.

1769 

1770 - `name: string`

1771 

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

1773 

1774 - `value: string`

1775 

1776 The secret value to inject for the domain.

1777 

1778 - `type: "code_interpreter"`

1779 

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

1781 

1782 - `"code_interpreter"`

1783 

1784 - `allowed_callers: optional array of "direct" or "programmatic" or null`

1785 

1786 The tool invocation context(s).

1787 

1788 - `"direct"`

1789 

1790 - `"programmatic"`

1791 

1792 - `ProgrammaticToolCalling object { type }`

1793 

1794 - `type: "programmatic_tool_calling"`

1795 

1796 The type of the tool. Always `programmatic_tool_calling`.

1797 

1798 - `"programmatic_tool_calling"`

1799 

1800 - `ImageGeneration object { type, action, background, 9 more }`

1801 

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

1803 

1804 - `type: "image_generation"`

1805 

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

1807 

1808 - `"image_generation"`

1809 

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

1811 

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

1813 

1814 - `"generate"`

1815 

1816 - `"edit"`

1817 

1818 - `"auto"`

1819 

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

1821 

1822 Set the background of the generated image. One of `transparent`, `opaque`,

1823 or `auto`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including

1824 their `2026-09-08` snapshots, support `opaque` and `transparent`

1825 backgrounds. Transparent backgrounds are available for supported GPT Image

1826 models. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in

1827 preview. When using `transparent`, set the output format to `png` or `webp`.

1828 Default: `auto`.

1829 

1830 - `"transparent"`

1831 

1832 - `"opaque"`

1833 

1834 - `"auto"`

1835 

1836 - `input_fidelity: optional "high" or "low" or null`

1837 

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

1839 

1840 - `"high"`

1841 

1842 - `"low"`

1843 

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

1845 

1846 Optional mask for inpainting. Contains `image_url`

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

1848 

1849 - `file_id: optional string`

1850 

1851 File ID for the mask image.

1852 

1853 - `image_url: optional string`

1854 

1855 Base64-encoded mask image.

1856 

1857 - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 6 more`

1858 

1859 The image generation model to use. One of `gpt-image-1`,

1860 `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`,

1861 `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,

1862 `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,

1863 `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default:

1864 `gpt-image-1`.

1865 

1866 - `string`

1867 

1868 - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 6 more`

1869 

1870 The image generation model to use. One of `gpt-image-1`,

1871 `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`,

1872 `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,

1873 `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,

1874 `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default:

1875 `gpt-image-1`.

1876 

1877 - `"gpt-image-1"`

1878 

1879 - `"gpt-image-1-mini"`

1880 

1881 - `"gpt-image-1.5"`

1882 

1883 - `"gpt-image-2"`

1884 

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

1886 

1887 - `"gpt-image-2.5-sunburst"`

1888 

1889 - `"gpt-image-2.5-sunburst-2026-09-08"`

1890 

1891 - `"gpt-image-2.5-flare"`

1892 

1893 - `"gpt-image-2.5-flare-2026-09-08"`

1894 

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

1896 

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

1898 

1899 - `"auto"`

1900 

1901 - `"low"`

1902 

1903 - `output_compression: optional number`

1904 

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

1906 

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

1908 

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

1910 `jpeg`. Default: `png`.

1911 

1912 - `"png"`

1913 

1914 - `"webp"`

1915 

1916 - `"jpeg"`

1917 

1918 - `partial_images: optional number`

1919 

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

1921 

1922 - `quality: optional "low" or "medium" or "high" or 3 more`

1923 

1924 The quality of the generated image. The GPT image models support `low`,

1925 `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`,

1926 including their `2026-09-08` snapshots, also support `xhigh` and `max`.

1927 Default: `auto`.

1928 

1929 - `"low"`

1930 

1931 - `"medium"`

1932 

1933 - `"high"`

1934 

1935 - `"xhigh"`

1936 

1937 - `"max"`

1938 

1939 - `"auto"`

1940 

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

1942 

1943 The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, 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`.

1944 

1945 - `string`

1946 

1947 - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1948 

1949 The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, 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`.

1950 

1951 - `"1024x1024"`

1952 

1953 - `"1024x1536"`

1954 

1955 - `"1536x1024"`

1956 

1957 - `"auto"`

1958 

1959 - `LocalShell object { type }`

1960 

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

1962 

1963 - `type: "local_shell"`

1964 

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

1966 

1967 - `"local_shell"`

1968 

1969 - `Shell object { type, allowed_callers, environment }`

1970 

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

1972 

1973 - `type: "shell"`

1974 

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

1976 

1977 - `"shell"`

1978 

1979 - `allowed_callers: optional array of "direct" or "programmatic" or null`

1980 

1981 The tool invocation context(s).

1982 

1983 - `"direct"`

1984 

1985 - `"programmatic"`

1986 

1987 - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference or null`

1988 

1989 - `ContainerAuto object { type, file_ids, memory_limit, 2 more }`

1990 

1991 - `type: "container_auto"`

1992 

1993 Automatically creates a container for this request

1994 

1995 - `"container_auto"`

1996