cli/resources/responses/methods/compact/index.md 2026-09-16 22:58 UTC to 2026-09-18 22:59 UTC

1## Compact a response

2 

3`$ openai responses compact`

4 

5**post** `/responses/compact`

6 

7Compact a conversation. Returns a compacted response object.

8 

9Learn when and how to compact long-running conversations in the [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced).

10 

11### Parameters

12 

13- `--model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string`

14 

15 Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models.

16 

17- `--input: optional string or array of ResponseInputItem`

18 

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

20 

21- `--instructions: optional string`

22 

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

24 When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

25 

26- `--previous-response-id: optional string`

27 

28 The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`.

29 

30- `--prompt-cache-key: optional string`

31 

32 A key to use when reading from or writing to the prompt cache.

33 

34- `--prompt-cache-options: optional object { mode, ttl }`

35 

36 Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details.

37 

38- `--prompt-cache-retention: optional "in_memory" or "24h"`

39 

40 How long to retain a prompt cache entry created by this request.

41 

42- `--service-tier: optional "auto" or "default" or "flex" or "priority"`

43 

44 The service tier to use for this request.

45 

46### Returns

47 

48- `compacted_response: object { id, created_at, object, 2 more }`

49 

50 - `id: string`

51 

52 The unique identifier for the compacted response.

53 

54 - `created_at: number`

55 

56 Unix timestamp (in seconds) when the compacted conversation was created.

57 

58 - `object: "response.compaction"`

59 

60 The object type. Always `response.compaction`.

61 

62 - `output: array of ResponseOutputItem`

63 

64 The compacted list of output items. This is a list of all user messages, followed by a single compaction item.

65 

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

67 

68 An output message from the model.

69 

70 - `id: string`

71 

72 The unique ID of the output message.

73 

74 - `content: array of ResponseOutputText or ResponseOutputRefusal`

75 

76 The content of the output message.

77 

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

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 - `file_citation: 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 - `url_citation: object { end_index, start_index, title, 2 more }`

107 

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

109 

110 - `end_index: number`

111 

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

113 

114 - `start_index: number`

115 

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

117 

118 - `title: string`

119 

120 The title of the web resource.

121 

122 - `type: "url_citation"`

123 

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

125 

126 - `url: string`

127 

128 The URL of the web resource.

129 

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

131 

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

133 

134 - `container_id: string`

135 

136 The ID of the container file.

137 

138 - `end_index: number`

139 

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

141 

142 - `file_id: string`

143 

144 The ID of the file.

145 

146 - `filename: string`

147 

148 The filename of the container file cited.

149 

150 - `start_index: number`

151 

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

153 

154 - `type: "container_file_citation"`

155 

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

157 

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

159 

160 A path to a file.

161 

162 - `file_id: string`

163 

164 The ID of the file.

165 

166 - `index: number`

167 

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

169 

170 - `type: "file_path"`

171 

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

173 

174 - `text: string`

175 

176 The text output from the model.

177 

178 - `type: "output_text"`

179 

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

181 

182 - `logprobs: optional 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 - `response_output_refusal: object { refusal, type }`

199 

200 A refusal from the model.

201 

202 - `refusal: string`

203 

204 The refusal explanation from the model.

205 

206 - `type: "refusal"`

207 

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

209 

210 - `role: "assistant"`

211 

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

213 

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

215 

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

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

218 

219 - `"in_progress"`

220 

221 - `"completed"`

222 

223 - `"incomplete"`

224 

225 - `type: "message"`

226 

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

228 

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

230 

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

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

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

234 

235 - `"commentary"`

236 

237 - `"final_answer"`

238 

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

240 

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

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

243 

244 - `id: string`

245 

246 The unique ID of the file search tool call.

247 

248 - `queries: array of string`

249 

250 The queries used to search for files.

251 

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

253 

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

255 `searching`, `incomplete` or `failed`,

256 

257 - `"in_progress"`

258 

259 - `"searching"`

260 

261 - `"completed"`

262 

263 - `"incomplete"`

264 

265 - `"failed"`

266 

267 - `type: "file_search_call"`

268 

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

270 

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

272 

273 The results of the file search tool call.

274 

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

276 

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

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

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

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

281 length of 512 characters, booleans, or numbers.

282 

283 - `union_member_0: string`

284 

285 - `union_member_1: number`

286 

287 - `union_member_2: boolean`

288 

289 - `file_id: optional string`

290 

291 The unique ID of the file.

292 

293 - `filename: optional string`

294 

295 The name of the file.

296 

297 - `score: optional number`

298 

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

300 

301 - `text: optional string`

302 

303 The text that was retrieved from the file.

304 

305 - `response_function_tool_call: object { arguments, call_id, name, 5 more }`

306 

307 A tool call to run a function. See the

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

309 

310 - `arguments: string`

311 

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

313 

314 - `call_id: string`

315 

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

317 

318 - `name: string`

319 

320 The name of the function to run.

321 

322 - `type: "function_call"`

323 

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

325 

326 - `id: optional string`

327 

328 The unique ID of the function tool call.

329 

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

331 

332 The execution context that produced this tool call.

333 

334 - `direct: object { type }`

335 

336 - `program: object { caller_id, type }`

337 

338 - `caller_id: string`

339 

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

341 

342 - `type: "program"`

343 

344 - `namespace: optional string`

345 

346 The namespace of the function to run.

347 

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

349 

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

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

352 

353 - `"in_progress"`

354 

355 - `"completed"`

356 

357 - `"incomplete"`

358 

359 - `response_function_tool_call_output_item: object { id, call_id, output, 4 more }`

360 

361 - `id: string`

362 

363 The unique ID of the function call tool output.

364 

365 - `call_id: string`

366 

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

368 

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

370 

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

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

373 

374 - `string output: string`

375 

376 A string of the output of the function call.

377 

378 - `output content list: array of ResponseInputText or ResponseInputImage or ResponseInputFile`

379 

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

381 

382 - `response_input_text: object { text, type, prompt_cache_breakpoint }`

383 

384 A text input to the model.

385 

386 - `text: string`

387 

388 The text input to the model.

389 

390 - `type: "input_text"`

391 

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

393 

394 - `prompt_cache_breakpoint: optional object { mode }`

395 

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

397 

398 - `mode: "explicit"`

399 

400 The breakpoint mode. Always `explicit`.

401 

402 - `response_input_image: object { detail, type, file_id, 2 more }`

403 

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

405 

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

407 

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

409 

410 - `"low"`

411 

412 - `"high"`

413 

414 - `"auto"`

415 

416 - `"original"`

417 

418 - `type: "input_image"`

419 

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

421 

422 - `file_id: optional string`

423 

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

425 

426 - `image_url: optional string`

427 

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

429 

430 - `prompt_cache_breakpoint: optional object { mode }`

431 

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

433 

434 - `mode: "explicit"`

435 

436 The breakpoint mode. Always `explicit`.

437 

438 - `response_input_file: object { type, detail, file_data, 4 more }`

439 

440 A file input to the model.

441 

442 - `type: "input_file"`

443 

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

445 

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

447 

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

449 

450 - `"auto"`

451 

452 - `"low"`

453 

454 - `"high"`

455 

456 - `file_data: optional string`

457 

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

459 

460 - `file_id: optional string`

461 

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

463 

464 - `file_url: optional string`

465 

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

467 

468 - `filename: optional string`

469 

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

471 

472 - `prompt_cache_breakpoint: optional object { mode }`

473 

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

475 

476 - `mode: "explicit"`

477 

478 The breakpoint mode. Always `explicit`.

479 

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

481 

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

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

484 

485 - `"in_progress"`

486 

487 - `"completed"`

488 

489 - `"incomplete"`

490 

491 - `type: "function_call_output"`

492 

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

494 

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

496 

497 The execution context that produced this tool call.

498 

499 - `direct: object { type }`

500 

501 - `program: object { caller_id, type }`

502 

503 - `caller_id: string`

504 

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

506 

507 - `type: "program"`

508 

509 The caller type. Always `program`.

510 

511 - `created_by: optional string`

512 

513 The identifier of the actor that created the item.

514 

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

516 

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

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

519 

520 - `id: string`

521 

522 The unique ID of the web search tool call.

523 

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

525 

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

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

528 

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

530 

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

532 

533 - `type: "search"`

534 

535 The action type.

536 

537 - `queries: optional array of string`

538 

539 The search queries.

540 

541 - `query: optional string`

542 

543 The search query.

544 

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

546 

547 The sources used in the search.

548 

549 - `type: "url"`

550 

551 The type of source. Always `url`.

552 

553 - `url: string`

554 

555 The URL of the source.

556 

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

558 

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

560 

561 - `type: "open_page"`

562 

563 The action type.

564 

565 - `url: optional string`

566 

567 The URL opened by the model.

568 

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

570 

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

572 

573 - `pattern: string`

574 

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

576 

577 - `type: "find_in_page"`

578 

579 The action type.

580 

581 - `url: string`

582 

583 The URL of the page searched for the pattern.

584 

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

586 

587 The status of the web search tool call.

588 

589 - `"in_progress"`

590 

591 - `"searching"`

592 

593 - `"completed"`

594 

595 - `"failed"`

596 

597 - `type: "web_search_call"`

598 

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

600 

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

602 

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

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

605 

606 - `id: string`

607 

608 The unique ID of the computer call.

609 

610 - `call_id: string`

611 

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

613 

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

615 

616 The pending safety checks for the computer call.

617 

618 - `id: string`

619 

620 The ID of the pending safety check.

621 

622 - `code: optional string`

623 

624 The type of the pending safety check.

625 

626 - `message: optional string`

627 

628 Details about the pending safety check.

629 

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

631 

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

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

634 

635 - `"in_progress"`

636 

637 - `"completed"`

638 

639 - `"incomplete"`

640 

641 - `type: "computer_call"`

642 

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

644 

645 - `"computer_call"`

646 

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

648 

649 A click action.

650 

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

652 

653 A click action.

654 

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

656 

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

658 

659 - `"left"`

660 

661 - `"right"`

662 

663 - `"wheel"`

664 

665 - `"back"`

666 

667 - `"forward"`

668 

669 - `type: "click"`

670 

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

672 

673 - `x: number`

674 

675 The x-coordinate where the click occurred.

676 

677 - `y: number`

678 

679 The y-coordinate where the click occurred.

680 

681 - `keys: optional array of string`

682 

683 The keys being held while clicking.

684 

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

686 

687 A double click action.

688 

689 - `keys: array of string`

690 

691 The keys being held while double-clicking.

692 

693 - `type: "double_click"`

694 

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

696 

697 - `x: number`

698 

699 The x-coordinate where the double click occurred.

700 

701 - `y: number`

702 

703 The y-coordinate where the double click occurred.

704 

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

706 

707 A drag action.

708 

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

710 

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

712 

713 ```

714 [

715 { x: 100, y: 200 },

716 { x: 200, y: 300 }

717 ]

718 ```

719 

720 - `x: number`

721 

722 The x-coordinate.

723 

724 - `y: number`

725 

726 The y-coordinate.

727 

728 - `type: "drag"`

729 

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

731 

732 - `keys: optional array of string`

733 

734 The keys being held while dragging the mouse.

735 

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

737 

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

739 

740 - `keys: array of string`

741 

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

743 

744 - `type: "keypress"`

745 

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

747 

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

749 

750 A mouse move action.

751 

752 - `type: "move"`

753 

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

755 

756 - `x: number`

757 

758 The x-coordinate to move to.

759 

760 - `y: number`

761 

762 The y-coordinate to move to.

763 

764 - `keys: optional array of string`

765 

766 The keys being held while moving the mouse.

767 

768 - `screenshot: object { type }`

769 

770 A screenshot action.

771 

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

773 

774 A scroll action.

775 

776 - `scroll_x: number`

777 

778 The horizontal scroll distance.

779 

780 - `scroll_y: number`

781 

782 The vertical scroll distance.

783 

784 - `type: "scroll"`

785 

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

787 

788 - `x: number`

789 

790 The x-coordinate where the scroll occurred.

791 

792 - `y: number`

793 

794 The y-coordinate where the scroll occurred.

795 

796 - `keys: optional array of string`

797 

798 The keys being held while scrolling.

799 

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

801 

802 An action to type in text.

803 

804 - `text: string`

805 

806 The text to type.

807 

808 - `type: "type"`

809 

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

811 

812 - `wait: object { type }`

813 

814 A wait action.

815 

816 - `actions: optional array of ComputerAction`

817 

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

819 `type` discriminator and action-specific fields.

820 

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

822 

823 A click action.

824 

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

826 

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

828 

829 - `"left"`

830 

831 - `"right"`

832 

833 - `"wheel"`

834 

835 - `"back"`

836 

837 - `"forward"`

838 

839 - `type: "click"`

840 

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

842 

843 - `x: number`

844 

845 The x-coordinate where the click occurred.

846 

847 - `y: number`

848 

849 The y-coordinate where the click occurred.

850 

851 - `keys: optional array of string`

852 

853 The keys being held while clicking.

854 

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

856 

857 A double click action.

858 

859 - `keys: array of string`

860 

861 The keys being held while double-clicking.

862 

863 - `type: "double_click"`

864 

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

866 

867 - `x: number`

868 

869 The x-coordinate where the double click occurred.

870 

871 - `y: number`

872 

873 The y-coordinate where the double click occurred.

874 

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

876 

877 A drag action.

878 

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

880 

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

882 

883 ```

884 [

885 { x: 100, y: 200 },

886 { x: 200, y: 300 }

887 ]

888 ```

889 

890 - `x: number`

891 

892 The x-coordinate.

893 

894 - `y: number`

895 

896 The y-coordinate.

897 

898 - `type: "drag"`

899 

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

901 

902 - `keys: optional array of string`

903 

904 The keys being held while dragging the mouse.

905 

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

907 

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

909 

910 - `keys: array of string`

911 

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

913 

914 - `type: "keypress"`

915 

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

917 

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

919 

920 A mouse move action.

921 

922 - `type: "move"`

923 

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

925 

926 - `x: number`

927 

928 The x-coordinate to move to.

929 

930 - `y: number`

931 

932 The y-coordinate to move to.

933 

934 - `keys: optional array of string`

935 

936 The keys being held while moving the mouse.

937 

938 - `screenshot: object { type }`

939 

940 A screenshot action.

941 

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

943 

944 A scroll action.

945 

946 - `scroll_x: number`

947 

948 The horizontal scroll distance.

949 

950 - `scroll_y: number`

951 

952 The vertical scroll distance.

953 

954 - `type: "scroll"`

955 

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

957 

958 - `x: number`

959 

960 The x-coordinate where the scroll occurred.

961 

962 - `y: number`

963 

964 The y-coordinate where the scroll occurred.

965 

966 - `keys: optional array of string`

967 

968 The keys being held while scrolling.

969 

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

971 

972 An action to type in text.

973 

974 - `text: string`

975 

976 The text to type.

977 

978 - `type: "type"`

979 

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

981 

982 - `wait: object { type }`

983 

984 A wait action.

985 

986 - `response_computer_tool_call_output_item: object { id, call_id, output, 4 more }`

987 

988 - `id: string`

989 

990 The unique ID of the computer call tool output.

991 

992 - `call_id: string`

993 

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

995 

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

997 

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

999 

1000 - `type: "computer_screenshot"`

1001 

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

1003 always set to `computer_screenshot`.

1004 

1005 - `file_id: optional string`

1006 

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

1008 

1009 - `image_url: optional string`

1010 

1011 The URL of the screenshot image.

1012 

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

1014 

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

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

1017 

1018 - `"completed"`

1019 

1020 - `"incomplete"`

1021 

1022 - `"failed"`

1023 

1024 - `"in_progress"`

1025 

1026 - `type: "computer_call_output"`

1027 

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

1029 

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

1031 

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

1033 developer.

1034 

1035 - `id: string`

1036 

1037 The ID of the pending safety check.

1038 

1039 - `code: optional string`

1040 

1041 The type of the pending safety check.

1042 

1043 - `message: optional string`

1044 

1045 Details about the pending safety check.

1046 

1047 - `created_by: optional string`

1048 

1049 The identifier of the actor that created the item.

1050 

1051 - `response_reasoning_item: object { id, summary, type, 3 more }`

1052 

1053 A description of the chain of thought used by a reasoning model while generating

1054 a response. Be sure to include these items in your `input` to the Responses API

1055 for subsequent turns of a conversation if you are manually

1056 [managing context](https://platform.openai.com/docs/guides/conversation-state).

1057 

1058 - `id: string`

1059 

1060 The unique identifier of the reasoning content.

1061 

1062 - `summary: array of object { text, type }`

1063 

1064 Reasoning summary content.

1065 

1066 - `text: string`

1067 

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

1069 

1070 - `type: "summary_text"`

1071 

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

1073 

1074 - `type: "reasoning"`

1075 

1076 The type of the object. Always `reasoning`.

1077 

1078 - `content: optional array of object { text, type }`

1079 

1080 Reasoning text content.

1081 

1082 - `text: string`

1083 

1084 The reasoning text from the model.

1085 

1086 - `type: "reasoning_text"`

1087 

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

1089 

1090 - `encrypted_content: optional string`

1091 

1092 The encrypted content of the reasoning item. This is populated by default

1093 for reasoning items returned by `POST /v1/responses` and WebSocket

1094 `response.create` requests.

1095 

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

1097 

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

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

1100 

1101 - `"in_progress"`

1102 

1103 - `"completed"`

1104 

1105 - `"incomplete"`

1106 

1107 - `program: object { id, call_id, code, 2 more }`

1108 

1109 - `id: string`

1110 

1111 The unique ID of the program item.

1112 

1113 - `call_id: string`

1114 

1115 The stable call ID of the program item.

1116 

1117 - `code: string`

1118 

1119 The JavaScript source executed by programmatic tool calling.

1120 

1121 - `fingerprint: string`

1122 

1123 Opaque program replay fingerprint that must be round-tripped.

1124 

1125 - `type: "program"`

1126 

1127 The type of the item. Always `program`.

1128 

1129 - `program_output: object { id, call_id, result, 2 more }`

1130 

1131 - `id: string`

1132 

1133 The unique ID of the program output item.

1134 

1135 - `call_id: string`

1136 

1137 The call ID of the program item.

1138 

1139 - `result: string`

1140 

1141 The result produced by the program item.

1142 

1143 - `status: "completed" or "incomplete"`

1144 

1145 The terminal status of the program output item.

1146 

1147 - `"completed"`

1148 

1149 - `"incomplete"`

1150 

1151 - `type: "program_output"`

1152 

1153 The type of the item. Always `program_output`.

1154 

1155 - `response_tool_search_call: object { id, arguments, call_id, 4 more }`

1156 

1157 - `id: string`

1158 

1159 The unique ID of the tool search call item.

1160 

1161 - `arguments: unknown`

1162 

1163 Arguments used for the tool search call.

1164 

1165 - `call_id: string`

1166 

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

1168 

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

1170 

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

1172 

1173 - `"server"`

1174 

1175 - `"client"`

1176 

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

1178 

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

1180 

1181 - `"in_progress"`

1182 

1183 - `"completed"`

1184 

1185 - `"incomplete"`

1186 

1187 - `type: "tool_search_call"`

1188 

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

1190 

1191 - `created_by: optional string`

1192 

1193 The identifier of the actor that created the item.

1194 

1195 - `response_tool_search_output_item: object { id, call_id, execution, 4 more }`

1196 

1197 - `id: string`

1198 

1199 The unique ID of the tool search output item.

1200 

1201 - `call_id: string`

1202 

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

1204 

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

1206 

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

1208 

1209 - `"server"`

1210 

1211 - `"client"`

1212 

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

1214 

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

1216 

1217 - `"in_progress"`

1218 

1219 - `"completed"`

1220 

1221 - `"incomplete"`

1222 

1223 - `tools: array of Tool`

1224 

1225 The loaded tool definitions returned by tool search.

1226 

1227 - `function_tool: object { name, parameters, strict, 5 more }`

1228 

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

1230 

1231 - `name: string`

1232 

1233 The name of the function to call.

1234 

1235 - `parameters: map[unknown]`

1236 

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

1238 

1239 - `strict: boolean`

1240 

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

1242 

1243 - `type: "function"`

1244 

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

1246 

1247 - `allowed_callers: optional array of "direct" or "programmatic"`

1248 

1249 The tool invocation context(s).

1250 

1251 - `"direct"`

1252 

1253 - `"programmatic"`

1254 

1255 - `defer_loading: optional boolean`

1256 

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

1258 

1259 - `description: optional string`

1260 

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

1262 

1263 - `output_schema: optional map[unknown]`

1264 

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

1266 

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

1268 

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

1270 

1271 - `type: "file_search"`

1272 

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

1274 

1275 - `vector_store_ids: array of string`

1276 

1277 The IDs of the vector stores to search.

1278 

1279 - `filters: optional ComparisonFilter or CompoundFilter`

1280 

1281 A filter to apply.

1282 

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

1284 

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

1286 

1287 - `key: string`

1288 

1289 The key to compare against the value.

1290 

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

1292 

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

1294 

1295 - `eq`: equals

1296 - `ne`: not equal

1297 - `gt`: greater than

1298 - `gte`: greater than or equal

1299 - `lt`: less than

1300 - `lte`: less than or equal

1301 - `in`: in

1302 - `nin`: not in

1303 

1304 - `"eq"`

1305 

1306 - `"ne"`

1307 

1308 - `"gt"`

1309 

1310 - `"gte"`

1311 

1312 - `"lt"`

1313 

1314 - `"lte"`

1315 

1316 - `"in"`

1317 

1318 - `"nin"`

1319 

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

1321 

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

1323 

1324 - `union_member_0: string`

1325 

1326 - `union_member_1: number`

1327 

1328 - `union_member_2: boolean`

1329 

1330 - `union_member_3: array of string or number`

1331 

1332 - `union_member_0: string`

1333 

1334 - `union_member_1: number`

1335 

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

1337 

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

1339 

1340 - `filters: array of ComparisonFilter or unknown`

1341 

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

1343 

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

1345 

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

1347 

1348 - `union_member_1: unknown`

1349 

1350 - `type: "and" or "or"`

1351 

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

1353 

1354 - `"and"`

1355 

1356 - `"or"`

1357 

1358 - `max_num_results: optional number`

1359 

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

1361 

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

1363 

1364 Ranking options for search.

1365 

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

1367 

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

1369 

1370 - `embedding_weight: number`

1371 

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

1373 

1374 - `text_weight: number`

1375 

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

1377 

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

1379 

1380 The ranker to use for the file search.

1381 

1382 - `"auto"`

1383 

1384 - `"default-2024-11-15"`

1385 

1386 - `score_threshold: optional number`

1387 

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

1389 

1390 - `computer_tool: object { type }`

1391 

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

1393 

1394 - `type: "computer"`

1395 

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

1397 

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

1399 

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

1401 

1402 - `display_height: number`

1403 

1404 The height of the computer display.

1405 

1406 - `display_width: number`

1407 

1408 The width of the computer display.

1409 

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

1411 

1412 The type of computer environment to control.

1413 

1414 - `"windows"`

1415 

1416 - `"mac"`

1417 

1418 - `"linux"`

1419 

1420 - `"ubuntu"`

1421 

1422 - `"browser"`

1423 

1424 - `type: "computer_use_preview"`

1425 

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

1427 

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

1429 

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

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

1432 

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

1434 

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

1436 

1437 - `"web_search"`

1438 

1439 - `"web_search_2025_08_26"`

1440 

1441 - `filters: optional object { allowed_domains }`

1442 

1443 Filters for the search.

1444 

1445 - `allowed_domains: optional array of string`

1446 

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

1448 Subdomains of the provided domains are allowed as well.

1449 

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

1451 

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

1453 

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

1455 

1456 - `"low"`

1457 

1458 - `"medium"`

1459 

1460 - `"high"`

1461 

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

1463 

1464 The approximate location of the user.

1465 

1466 - `city: optional string`

1467 

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

1469 

1470 - `country: optional string`

1471 

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

1473 

1474 - `region: optional string`

1475 

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

1477 

1478 - `timezone: optional string`

1479 

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

1481 

1482 - `type: optional "approximate"`

1483 

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

1485 

1486 - `"approximate"`

1487 

1488 - `mcp: object { server_label, type, allowed_callers, 9 more }`

1489 

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

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

1492 

1493 - `server_label: string`

1494 

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

1496 

1497 - `type: "mcp"`

1498 

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

1500 

1501 - `allowed_callers: optional array of "direct" or "programmatic"`

1502 

1503 The tool invocation context(s).

1504 

1505 - `"direct"`

1506 

1507 - `"programmatic"`

1508 

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

1510 

1511 List of allowed tool names or a filter object.

1512 

1513 - `MCP allowed tools: array of string`

1514 

1515 A string array of allowed tool names

1516 

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

1518 

1519 A filter object to specify which tools are allowed.

1520 

1521 - `read_only: optional boolean`

1522 

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

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

1525 it will match this filter.

1526 

1527 - `tool_names: optional array of string`

1528 

1529 List of allowed tool names.

1530 

1531 - `authorization: optional string`

1532 

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

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

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

1536 

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

1538 

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

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

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

1542 

1543 Currently supported `connector_id` values are:

1544 

1545 - Dropbox: `connector_dropbox`

1546 - Gmail: `connector_gmail`

1547 - Google Calendar: `connector_googlecalendar`

1548 - Google Drive: `connector_googledrive`

1549 - Microsoft Teams: `connector_microsoftteams`

1550 - Outlook Calendar: `connector_outlookcalendar`

1551 - Outlook Email: `connector_outlookemail`

1552 - SharePoint: `connector_sharepoint`

1553 

1554 - `"connector_dropbox"`

1555 

1556 - `"connector_gmail"`

1557 

1558 - `"connector_googlecalendar"`

1559 

1560 - `"connector_googledrive"`

1561 

1562 - `"connector_microsoftteams"`

1563 

1564 - `"connector_outlookcalendar"`

1565 

1566 - `"connector_outlookemail"`

1567 

1568 - `"connector_sharepoint"`

1569 

1570 - `defer_loading: optional boolean`

1571 

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

1573 

1574 - `headers: optional map[string]`

1575 

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

1577 or other purposes.

1578 

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

1580 

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

1582 

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

1584 

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

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

1587 that require approval.

1588 

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

1590 

1591 A filter object to specify which tools are allowed.

1592 

1593 - `read_only: optional boolean`

1594 

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

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

1597 it will match this filter.

1598 

1599 - `tool_names: optional array of string`

1600 

1601 List of allowed tool names.

1602 

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

1604 

1605 A filter object to specify which tools are allowed.

1606 

1607 - `read_only: optional boolean`

1608 

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

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

1611 it will match this filter.

1612 

1613 - `tool_names: optional array of string`

1614 

1615 List of allowed tool names.

1616 

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

1618 

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

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

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

1622 

1623 - `"always"`

1624 

1625 - `"never"`

1626 

1627 - `server_description: optional string`

1628 

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

1630 

1631 - `server_url: optional string`

1632 

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

1634 `tunnel_id` must be provided.

1635 

1636 - `tunnel_id: optional string`

1637 

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

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

1640 

1641 - `code_interpreter: object { container, type, allowed_callers }`

1642 

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

1644 

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

1646 

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

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

1649 optional `memory_limit` setting.

1650 

1651 - `union_member_0: string`

1652 

1653 The container ID.

1654 

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

1656 

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

1658 

1659 - `type: "auto"`

1660 

1661 Always `auto`.

1662 

1663 - `file_ids: optional array of string`

1664 

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

1666 

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

1668 

1669 The memory limit for the code interpreter container.

1670 

1671 - `"1g"`

1672 

1673 - `"4g"`

1674 

1675 - `"16g"`

1676 

1677 - `"64g"`

1678 

1679 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1680 

1681 Network access policy for the container.

1682 

1683 - `container_network_policy_disabled: object { type }`

1684 

1685 - `type: "disabled"`

1686 

1687 Disable outbound network access. Always `disabled`.

1688 

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

1690 

1691 - `allowed_domains: array of string`

1692 

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

1694 

1695 - `type: "allowlist"`

1696 

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

1698 

1699 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1700 

1701 Optional domain-scoped secrets for allowlisted domains.

1702 

1703 - `domain: string`

1704 

1705 The domain associated with the secret.

1706 

1707 - `name: string`

1708 

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

1710 

1711 - `value: string`

1712 

1713 The secret value to inject for the domain.

1714 

1715 - `type: "code_interpreter"`

1716 

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

1718 

1719 - `allowed_callers: optional array of "direct" or "programmatic"`

1720 

1721 The tool invocation context(s).

1722 

1723 - `"direct"`

1724 

1725 - `"programmatic"`

1726 

1727 - `programmatic_tool_calling: object { type }`

1728 

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

1730 

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

1732 

1733 - `type: "image_generation"`

1734 

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

1736 

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

1738 

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

1740 

1741 - `"generate"`

1742 

1743 - `"edit"`

1744 

1745 - `"auto"`

1746 

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

1748 

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

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

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

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

1753 automatically determine the best background for the image.

1754 

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

1756 transparent backgrounds. Requests with `background` set to

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

1758 `auto` instead.

1759 

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

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

1762 

1763 - `"transparent"`

1764 

1765 - `"opaque"`

1766 

1767 - `"auto"`

1768 

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

1770 

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

1772 

1773 - `"high"`

1774 

1775 - `"low"`

1776 

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

1778 

1779 Optional mask for inpainting. Contains `image_url`

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

1781 

1782 - `file_id: optional string`

1783 

1784 File ID for the mask image.

1785 

1786 - `image_url: optional string`

1787 

1788 Base64-encoded mask image.

1789 

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

1791 

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

1793 

1794 - `"gpt-image-1"`

1795 

1796 - `"gpt-image-1-mini"`

1797 

1798 - `"gpt-image-2"`

1799 

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

1801 

1802 - `"gpt-image-1.5"`

1803 

1804 - `"chatgpt-image-latest"`

1805 

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

1807 

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

1809 

1810 - `"auto"`

1811 

1812 - `"low"`

1813 

1814 - `output_compression: optional number`

1815 

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

1817 

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

1819 

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

1821 `jpeg`. Default: `png`.

1822 

1823 - `"png"`

1824 

1825 - `"webp"`

1826 

1827 - `"jpeg"`

1828 

1829 - `partial_images: optional number`

1830 

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

1832 

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

1834 

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

1836 or `auto`. Default: `auto`.

1837 

1838 - `"low"`

1839 

1840 - `"medium"`

1841 

1842 - `"high"`

1843 

1844 - `"auto"`

1845 

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

1847 

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

1849 

1850 - `"1024x1024"`

1851 

1852 - `"1024x1536"`

1853 

1854 - `"1536x1024"`

1855 

1856 - `"auto"`

1857 

1858 - `local_shell: object { type }`

1859 

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

1861 

1862 - `function_shell_tool: object { type, allowed_callers, environment }`

1863 

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

1865 

1866 - `type: "shell"`

1867 

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

1869 

1870 - `allowed_callers: optional array of "direct" or "programmatic"`

1871 

1872 The tool invocation context(s).

1873 

1874 - `"direct"`

1875 

1876 - `"programmatic"`

1877 

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

1879 

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

1881 

1882 - `type: "container_auto"`

1883 

1884 Automatically creates a container for this request

1885 

1886 - `file_ids: optional array of string`

1887 

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

1889 

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

1891 

1892 The memory limit for the container.

1893 

1894 - `"1g"`

1895 

1896 - `"4g"`

1897 

1898 - `"16g"`

1899 

1900 - `"64g"`

1901 

1902 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1903 

1904 Network access policy for the container.

1905 

1906 - `container_network_policy_disabled: object { type }`

1907 

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

1909 

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

1911 

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

1913 

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

1915 

1916 - `skill_id: string`

1917 

1918 The ID of the referenced skill.

1919 

1920 - `type: "skill_reference"`

1921 

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

1923 

1924 - `version: optional string`

1925 

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

1927 

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

1929 

1930 - `description: string`

1931 

1932 The description of the skill.

1933 

1934 - `name: string`

1935 

1936 The name of the skill.

1937 

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

1939 

1940 Inline skill payload

1941 

1942 - `data: string`

1943 

1944 Base64-encoded skill zip bundle.

1945 

1946 - `media_type: "application/zip"`

1947 

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

1949 

1950 - `type: "base64"`

1951 

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

1953 

1954 - `type: "inline"`

1955 

1956 Defines an inline skill for this request.

1957 

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

1959 

1960 - `type: "local"`

1961 

1962 Use a local computer environment.

1963 

1964 - `skills: optional array of LocalSkill`

1965 

1966 An optional list of skills.

1967 

1968 - `description: string`

1969 

1970 The description of the skill.

1971 

1972 - `name: string`

1973 

1974 The name of the skill.

1975 

1976 - `path: string`

1977 

1978 The path to the directory containing the skill.

1979 

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

1981 

1982 - `container_id: string`

1983 

1984 The ID of the referenced container.

1985 

1986 - `type: "container_reference"`

1987 

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

1989 

1990 - `custom_tool: object { name, type, allowed_callers, 3 more }`

1991 

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

1993 

1994 - `name: string`

1995 

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