go/resources/conversations/methods/create/index.md 2026-09-16 22:58 UTC to 2026-09-18 22:59 UTC

1## Create a conversation

2 

3`client.Conversations.New(ctx, body) (*Conversation, error)`

4 

5**post** `/conversations`

6 

7Create a conversation.

8 

9### Parameters

10 

11- `body ConversationNewParams`

12 

13 - `Items param.Field[[]ResponseInputItemUnion]`

14 

15 Initial items to include in the conversation context. You may add up to 20 items at a time.

16 

17 - `type EasyInputMessage struct{…}`

18 

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

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

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

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

23 interactions.

24 

25 - `Content EasyInputMessageContentUnion`

26 

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

28 Can also contain previous assistant responses.

29 

30 - `string`

31 

32 - `type ResponseInputMessageContentList []ResponseInputContentUnion`

33 

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

35 types.

36 

37 - `type ResponseInputText struct{…}`

38 

39 A text input to the model.

40 

41 - `Text string`

42 

43 The text input to the model.

44 

45 - `Type InputText`

46 

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

48 

49 - `const InputTextInputText InputText = "input_text"`

50 

51 - `PromptCacheBreakpoint ResponseInputTextPromptCacheBreakpoint`

52 

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

54 

55 - `Mode Explicit`

56 

57 The breakpoint mode. Always `explicit`.

58 

59 - `const ExplicitExplicit Explicit = "explicit"`

60 

61 - `type ResponseInputImage struct{…}`

62 

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

64 

65 - `Detail ResponseInputImageDetail`

66 

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

68 

69 - `const ResponseInputImageDetailLow ResponseInputImageDetail = "low"`

70 

71 - `const ResponseInputImageDetailHigh ResponseInputImageDetail = "high"`

72 

73 - `const ResponseInputImageDetailAuto ResponseInputImageDetail = "auto"`

74 

75 - `const ResponseInputImageDetailOriginal ResponseInputImageDetail = "original"`

76 

77 - `Type InputImage`

78 

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

80 

81 - `const InputImageInputImage InputImage = "input_image"`

82 

83 - `FileID string`

84 

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

86 

87 - `ImageURL string`

88 

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

90 

91 - `PromptCacheBreakpoint ResponseInputImagePromptCacheBreakpoint`

92 

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

94 

95 - `Mode Explicit`

96 

97 The breakpoint mode. Always `explicit`.

98 

99 - `const ExplicitExplicit Explicit = "explicit"`

100 

101 - `type ResponseInputFile struct{…}`

102 

103 A file input to the model.

104 

105 - `Type InputFile`

106 

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

108 

109 - `const InputFileInputFile InputFile = "input_file"`

110 

111 - `Detail ResponseInputFileDetail`

112 

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

114 

115 - `const ResponseInputFileDetailAuto ResponseInputFileDetail = "auto"`

116 

117 - `const ResponseInputFileDetailLow ResponseInputFileDetail = "low"`

118 

119 - `const ResponseInputFileDetailHigh ResponseInputFileDetail = "high"`

120 

121 - `FileData string`

122 

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

124 

125 - `FileID string`

126 

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

128 

129 - `FileURL string`

130 

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

132 

133 - `Filename string`

134 

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

136 

137 - `PromptCacheBreakpoint ResponseInputFilePromptCacheBreakpoint`

138 

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

140 

141 - `Mode Explicit`

142 

143 The breakpoint mode. Always `explicit`.

144 

145 - `const ExplicitExplicit Explicit = "explicit"`

146 

147 - `Role EasyInputMessageRole`

148 

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

150 `developer`.

151 

152 - `const EasyInputMessageRoleUser EasyInputMessageRole = "user"`

153 

154 - `const EasyInputMessageRoleAssistant EasyInputMessageRole = "assistant"`

155 

156 - `const EasyInputMessageRoleSystem EasyInputMessageRole = "system"`

157 

158 - `const EasyInputMessageRoleDeveloper EasyInputMessageRole = "developer"`

159 

160 - `Phase EasyInputMessagePhase`

161 

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

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

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

165 

166 - `const EasyInputMessagePhaseCommentary EasyInputMessagePhase = "commentary"`

167 

168 - `const EasyInputMessagePhaseFinalAnswer EasyInputMessagePhase = "final_answer"`

169 

170 - `Type EasyInputMessageType`

171 

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

173 

174 - `const EasyInputMessageTypeMessage EasyInputMessageType = "message"`

175 

176 - `type ResponseInputItemMessage struct{…}`

177 

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

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

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

181 

182 - `Content ResponseInputMessageContentList`

183 

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

185 types.

186 

187 - `Role string`

188 

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

190 

191 - `const ResponseInputItemMessageRoleUser ResponseInputItemMessageRole = "user"`

192 

193 - `const ResponseInputItemMessageRoleSystem ResponseInputItemMessageRole = "system"`

194 

195 - `const ResponseInputItemMessageRoleDeveloper ResponseInputItemMessageRole = "developer"`

196 

197 - `Status string`

198 

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

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

201 

202 - `const ResponseInputItemMessageStatusInProgress ResponseInputItemMessageStatus = "in_progress"`

203 

204 - `const ResponseInputItemMessageStatusCompleted ResponseInputItemMessageStatus = "completed"`

205 

206 - `const ResponseInputItemMessageStatusIncomplete ResponseInputItemMessageStatus = "incomplete"`

207 

208 - `Type string`

209 

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

211 

212 - `const ResponseInputItemMessageTypeMessage ResponseInputItemMessageType = "message"`

213 

214 - `type ResponseOutputMessage struct{…}`

215 

216 An output message from the model.

217 

218 - `ID string`

219 

220 The unique ID of the output message.

221 

222 - `Content []ResponseOutputMessageContentUnion`

223 

224 The content of the output message.

225 

226 - `type ResponseOutputText struct{…}`

227 

228 A text output from the model.

229 

230 - `Annotations []ResponseOutputTextAnnotationUnion`

231 

232 The annotations of the text output.

233 

234 - `type ResponseOutputTextAnnotationFileCitation struct{…}`

235 

236 A citation to a file.

237 

238 - `FileID string`

239 

240 The ID of the file.

241 

242 - `Filename string`

243 

244 The filename of the file cited.

245 

246 - `Index int64`

247 

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

249 

250 - `Type FileCitation`

251 

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

253 

254 - `const FileCitationFileCitation FileCitation = "file_citation"`

255 

256 - `type ResponseOutputTextAnnotationURLCitation struct{…}`

257 

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

259 

260 - `EndIndex int64`

261 

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

263 

264 - `StartIndex int64`

265 

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

267 

268 - `Title string`

269 

270 The title of the web resource.

271 

272 - `Type URLCitation`

273 

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

275 

276 - `const URLCitationURLCitation URLCitation = "url_citation"`

277 

278 - `URL string`

279 

280 The URL of the web resource.

281 

282 - `type ResponseOutputTextAnnotationContainerFileCitation struct{…}`

283 

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

285 

286 - `ContainerID string`

287 

288 The ID of the container file.

289 

290 - `EndIndex int64`

291 

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

293 

294 - `FileID string`

295 

296 The ID of the file.

297 

298 - `Filename string`

299 

300 The filename of the container file cited.

301 

302 - `StartIndex int64`

303 

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

305 

306 - `Type ContainerFileCitation`

307 

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

309 

310 - `const ContainerFileCitationContainerFileCitation ContainerFileCitation = "container_file_citation"`

311 

312 - `type ResponseOutputTextAnnotationFilePath struct{…}`

313 

314 A path to a file.

315 

316 - `FileID string`

317 

318 The ID of the file.

319 

320 - `Index int64`

321 

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

323 

324 - `Type FilePath`

325 

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

327 

328 - `const FilePathFilePath FilePath = "file_path"`

329 

330 - `Text string`

331 

332 The text output from the model.

333 

334 - `Type OutputText`

335 

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

337 

338 - `const OutputTextOutputText OutputText = "output_text"`

339 

340 - `Logprobs []ResponseOutputTextLogprob`

341 

342 - `Token string`

343 

344 - `Bytes []int64`

345 

346 - `Logprob float64`

347 

348 - `TopLogprobs []ResponseOutputTextLogprobTopLogprob`

349 

350 - `Token string`

351 

352 - `Bytes []int64`

353 

354 - `Logprob float64`

355 

356 - `type ResponseOutputRefusal struct{…}`

357 

358 A refusal from the model.

359 

360 - `Refusal string`

361 

362 The refusal explanation from the model.

363 

364 - `Type Refusal`

365 

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

367 

368 - `const RefusalRefusal Refusal = "refusal"`

369 

370 - `Role Assistant`

371 

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

373 

374 - `const AssistantAssistant Assistant = "assistant"`

375 

376 - `Status ResponseOutputMessageStatus`

377 

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

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

380 

381 - `const ResponseOutputMessageStatusInProgress ResponseOutputMessageStatus = "in_progress"`

382 

383 - `const ResponseOutputMessageStatusCompleted ResponseOutputMessageStatus = "completed"`

384 

385 - `const ResponseOutputMessageStatusIncomplete ResponseOutputMessageStatus = "incomplete"`

386 

387 - `Type Message`

388 

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

390 

391 - `const MessageMessage Message = "message"`

392 

393 - `Phase ResponseOutputMessagePhase`

394 

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

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

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

398 

399 - `const ResponseOutputMessagePhaseCommentary ResponseOutputMessagePhase = "commentary"`

400 

401 - `const ResponseOutputMessagePhaseFinalAnswer ResponseOutputMessagePhase = "final_answer"`

402 

403 - `type ResponseFileSearchToolCall struct{…}`

404 

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

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

407 

408 - `ID string`

409 

410 The unique ID of the file search tool call.

411 

412 - `Queries []string`

413 

414 The queries used to search for files.

415 

416 - `Status ResponseFileSearchToolCallStatus`

417 

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

419 `searching`, `incomplete` or `failed`,

420 

421 - `const ResponseFileSearchToolCallStatusInProgress ResponseFileSearchToolCallStatus = "in_progress"`

422 

423 - `const ResponseFileSearchToolCallStatusSearching ResponseFileSearchToolCallStatus = "searching"`

424 

425 - `const ResponseFileSearchToolCallStatusCompleted ResponseFileSearchToolCallStatus = "completed"`

426 

427 - `const ResponseFileSearchToolCallStatusIncomplete ResponseFileSearchToolCallStatus = "incomplete"`

428 

429 - `const ResponseFileSearchToolCallStatusFailed ResponseFileSearchToolCallStatus = "failed"`

430 

431 - `Type FileSearchCall`

432 

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

434 

435 - `const FileSearchCallFileSearchCall FileSearchCall = "file_search_call"`

436 

437 - `Results []ResponseFileSearchToolCallResult`

438 

439 The results of the file search tool call.

440 

441 - `Attributes map[string, ResponseFileSearchToolCallResultAttributeUnion]`

442 

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

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

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

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

447 length of 512 characters, booleans, or numbers.

448 

449 - `string`

450 

451 - `float64`

452 

453 - `bool`

454 

455 - `FileID string`

456 

457 The unique ID of the file.

458 

459 - `Filename string`

460 

461 The name of the file.

462 

463 - `Score float64`

464 

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

466 

467 - `Text string`

468 

469 The text that was retrieved from the file.

470 

471 - `type ResponseComputerToolCall struct{…}`

472 

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

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

475 

476 - `ID string`

477 

478 The unique ID of the computer call.

479 

480 - `CallID string`

481 

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

483 

484 - `PendingSafetyChecks []ResponseComputerToolCallPendingSafetyCheck`

485 

486 The pending safety checks for the computer call.

487 

488 - `ID string`

489 

490 The ID of the pending safety check.

491 

492 - `Code string`

493 

494 The type of the pending safety check.

495 

496 - `Message string`

497 

498 Details about the pending safety check.

499 

500 - `Status ResponseComputerToolCallStatus`

501 

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

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

504 

505 - `const ResponseComputerToolCallStatusInProgress ResponseComputerToolCallStatus = "in_progress"`

506 

507 - `const ResponseComputerToolCallStatusCompleted ResponseComputerToolCallStatus = "completed"`

508 

509 - `const ResponseComputerToolCallStatusIncomplete ResponseComputerToolCallStatus = "incomplete"`

510 

511 - `Type ResponseComputerToolCallType`

512 

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

514 

515 - `const ResponseComputerToolCallTypeComputerCall ResponseComputerToolCallType = "computer_call"`

516 

517 - `Action ResponseComputerToolCallActionUnion`

518 

519 A click action.

520 

521 - `type ResponseComputerToolCallActionClick struct{…}`

522 

523 A click action.

524 

525 - `Button string`

526 

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

528 

529 - `const ResponseComputerToolCallActionClickButtonLeft ResponseComputerToolCallActionClickButton = "left"`

530 

531 - `const ResponseComputerToolCallActionClickButtonRight ResponseComputerToolCallActionClickButton = "right"`

532 

533 - `const ResponseComputerToolCallActionClickButtonWheel ResponseComputerToolCallActionClickButton = "wheel"`

534 

535 - `const ResponseComputerToolCallActionClickButtonBack ResponseComputerToolCallActionClickButton = "back"`

536 

537 - `const ResponseComputerToolCallActionClickButtonForward ResponseComputerToolCallActionClickButton = "forward"`

538 

539 - `Type Click`

540 

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

542 

543 - `const ClickClick Click = "click"`

544 

545 - `X int64`

546 

547 The x-coordinate where the click occurred.

548 

549 - `Y int64`

550 

551 The y-coordinate where the click occurred.

552 

553 - `Keys []string`

554 

555 The keys being held while clicking.

556 

557 - `type ResponseComputerToolCallActionDoubleClick struct{…}`

558 

559 A double click action.

560 

561 - `Keys []string`

562 

563 The keys being held while double-clicking.

564 

565 - `Type DoubleClick`

566 

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

568 

569 - `const DoubleClickDoubleClick DoubleClick = "double_click"`

570 

571 - `X int64`

572 

573 The x-coordinate where the double click occurred.

574 

575 - `Y int64`

576 

577 The y-coordinate where the double click occurred.

578 

579 - `type ResponseComputerToolCallActionDrag struct{…}`

580 

581 A drag action.

582 

583 - `Path []ResponseComputerToolCallActionDragPath`

584 

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

586 

587 ```

588 [

589 { x: 100, y: 200 },

590 { x: 200, y: 300 }

591 ]

592 ```

593 

594 - `X int64`

595 

596 The x-coordinate.

597 

598 - `Y int64`

599 

600 The y-coordinate.

601 

602 - `Type Drag`

603 

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

605 

606 - `const DragDrag Drag = "drag"`

607 

608 - `Keys []string`

609 

610 The keys being held while dragging the mouse.

611 

612 - `type ResponseComputerToolCallActionKeypress struct{…}`

613 

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

615 

616 - `Keys []string`

617 

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

619 

620 - `Type Keypress`

621 

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

623 

624 - `const KeypressKeypress Keypress = "keypress"`

625 

626 - `type ResponseComputerToolCallActionMove struct{…}`

627 

628 A mouse move action.

629 

630 - `Type Move`

631 

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

633 

634 - `const MoveMove Move = "move"`

635 

636 - `X int64`

637 

638 The x-coordinate to move to.

639 

640 - `Y int64`

641 

642 The y-coordinate to move to.

643 

644 - `Keys []string`

645 

646 The keys being held while moving the mouse.

647 

648 - `type ResponseComputerToolCallActionScreenshot struct{…}`

649 

650 A screenshot action.

651 

652 - `Type Screenshot`

653 

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

655 

656 - `const ScreenshotScreenshot Screenshot = "screenshot"`

657 

658 - `type ResponseComputerToolCallActionScroll struct{…}`

659 

660 A scroll action.

661 

662 - `ScrollX int64`

663 

664 The horizontal scroll distance.

665 

666 - `ScrollY int64`

667 

668 The vertical scroll distance.

669 

670 - `Type Scroll`

671 

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

673 

674 - `const ScrollScroll Scroll = "scroll"`

675 

676 - `X int64`

677 

678 The x-coordinate where the scroll occurred.

679 

680 - `Y int64`

681 

682 The y-coordinate where the scroll occurred.

683 

684 - `Keys []string`

685 

686 The keys being held while scrolling.

687 

688 - `type ResponseComputerToolCallActionType struct{…}`

689 

690 An action to type in text.

691 

692 - `Text string`

693 

694 The text to type.

695 

696 - `Type Type`

697 

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

699 

700 - `const TypeType Type = "type"`

701 

702 - `type ResponseComputerToolCallActionWait struct{…}`

703 

704 A wait action.

705 

706 - `Type Wait`

707 

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

709 

710 - `const WaitWait Wait = "wait"`

711 

712 - `Actions ComputerActionList`

713 

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

715 `type` discriminator and action-specific fields.

716 

717 - `type ComputerActionClick struct{…}`

718 

719 A click action.

720 

721 - `Button string`

722 

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

724 

725 - `const ComputerActionClickButtonLeft ComputerActionClickButton = "left"`

726 

727 - `const ComputerActionClickButtonRight ComputerActionClickButton = "right"`

728 

729 - `const ComputerActionClickButtonWheel ComputerActionClickButton = "wheel"`

730 

731 - `const ComputerActionClickButtonBack ComputerActionClickButton = "back"`

732 

733 - `const ComputerActionClickButtonForward ComputerActionClickButton = "forward"`

734 

735 - `Type Click`

736 

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

738 

739 - `const ClickClick Click = "click"`

740 

741 - `X int64`

742 

743 The x-coordinate where the click occurred.

744 

745 - `Y int64`

746 

747 The y-coordinate where the click occurred.

748 

749 - `Keys []string`

750 

751 The keys being held while clicking.

752 

753 - `type ComputerActionDoubleClick struct{…}`

754 

755 A double click action.

756 

757 - `Keys []string`

758 

759 The keys being held while double-clicking.

760 

761 - `Type DoubleClick`

762 

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

764 

765 - `const DoubleClickDoubleClick DoubleClick = "double_click"`

766 

767 - `X int64`

768 

769 The x-coordinate where the double click occurred.

770 

771 - `Y int64`

772 

773 The y-coordinate where the double click occurred.

774 

775 - `type ComputerActionDrag struct{…}`

776 

777 A drag action.

778 

779 - `Path []ComputerActionDragPath`

780 

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

782 

783 ```

784 [

785 { x: 100, y: 200 },

786 { x: 200, y: 300 }

787 ]

788 ```

789 

790 - `X int64`

791 

792 The x-coordinate.

793 

794 - `Y int64`

795 

796 The y-coordinate.

797 

798 - `Type Drag`

799 

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

801 

802 - `const DragDrag Drag = "drag"`

803 

804 - `Keys []string`

805 

806 The keys being held while dragging the mouse.

807 

808 - `type ComputerActionKeypress struct{…}`

809 

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

811 

812 - `Keys []string`

813 

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

815 

816 - `Type Keypress`

817 

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

819 

820 - `const KeypressKeypress Keypress = "keypress"`

821 

822 - `type ComputerActionMove struct{…}`

823 

824 A mouse move action.

825 

826 - `Type Move`

827 

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

829 

830 - `const MoveMove Move = "move"`

831 

832 - `X int64`

833 

834 The x-coordinate to move to.

835 

836 - `Y int64`

837 

838 The y-coordinate to move to.

839 

840 - `Keys []string`

841 

842 The keys being held while moving the mouse.

843 

844 - `type ComputerActionScreenshot struct{…}`

845 

846 A screenshot action.

847 

848 - `Type Screenshot`

849 

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

851 

852 - `const ScreenshotScreenshot Screenshot = "screenshot"`

853 

854 - `type ComputerActionScroll struct{…}`

855 

856 A scroll action.

857 

858 - `ScrollX int64`

859 

860 The horizontal scroll distance.

861 

862 - `ScrollY int64`

863 

864 The vertical scroll distance.

865 

866 - `Type Scroll`

867 

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

869 

870 - `const ScrollScroll Scroll = "scroll"`

871 

872 - `X int64`

873 

874 The x-coordinate where the scroll occurred.

875 

876 - `Y int64`

877 

878 The y-coordinate where the scroll occurred.

879 

880 - `Keys []string`

881 

882 The keys being held while scrolling.

883 

884 - `type ComputerActionType struct{…}`

885 

886 An action to type in text.

887 

888 - `Text string`

889 

890 The text to type.

891 

892 - `Type Type`

893 

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

895 

896 - `const TypeType Type = "type"`

897 

898 - `type ComputerActionWait struct{…}`

899 

900 A wait action.

901 

902 - `Type Wait`

903 

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

905 

906 - `const WaitWait Wait = "wait"`

907 

908 - `type ResponseInputItemComputerCallOutput struct{…}`

909 

910 The output of a computer tool call.

911 

912 - `CallID string`

913 

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

915 

916 - `Output ResponseComputerToolCallOutputScreenshot`

917 

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

919 

920 - `Type ComputerScreenshot`

921 

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

923 always set to `computer_screenshot`.

924 

925 - `const ComputerScreenshotComputerScreenshot ComputerScreenshot = "computer_screenshot"`

926 

927 - `FileID string`

928 

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

930 

931 - `ImageURL string`

932 

933 The URL of the screenshot image.

934 

935 - `Type ComputerCallOutput`

936 

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

938 

939 - `const ComputerCallOutputComputerCallOutput ComputerCallOutput = "computer_call_output"`

940 

941 - `ID string`

942 

943 The ID of the computer tool call output.

944 

945 - `AcknowledgedSafetyChecks []ResponseInputItemComputerCallOutputAcknowledgedSafetyCheck`

946 

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

948 

949 - `ID string`

950 

951 The ID of the pending safety check.

952 

953 - `Code string`

954 

955 The type of the pending safety check.

956 

957 - `Message string`

958 

959 Details about the pending safety check.

960 

961 - `Status string`

962 

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

964 

965 - `const ResponseInputItemComputerCallOutputStatusInProgress ResponseInputItemComputerCallOutputStatus = "in_progress"`

966 

967 - `const ResponseInputItemComputerCallOutputStatusCompleted ResponseInputItemComputerCallOutputStatus = "completed"`

968 

969 - `const ResponseInputItemComputerCallOutputStatusIncomplete ResponseInputItemComputerCallOutputStatus = "incomplete"`

970 

971 - `type ResponseFunctionWebSearch struct{…}`

972 

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

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

975 

976 - `ID string`

977 

978 The unique ID of the web search tool call.

979 

980 - `Action ResponseFunctionWebSearchActionUnion`

981 

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

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

984 

985 - `type ResponseFunctionWebSearchActionSearch struct{…}`

986 

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

988 

989 - `Type Search`

990 

991 The action type.

992 

993 - `const SearchSearch Search = "search"`

994 

995 - `Queries []string`

996 

997 The search queries.

998 

999 - `Query string`

1000 

1001 The search query.

1002 

1003 - `Sources []ResponseFunctionWebSearchActionSearchSource`

1004 

1005 The sources used in the search.

1006 

1007 - `Type URL`

1008 

1009 The type of source. Always `url`.

1010 

1011 - `const URLURL URL = "url"`

1012 

1013 - `URL string`

1014 

1015 The URL of the source.

1016 

1017 - `type ResponseFunctionWebSearchActionOpenPage struct{…}`

1018 

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

1020 

1021 - `Type OpenPage`

1022 

1023 The action type.

1024 

1025 - `const OpenPageOpenPage OpenPage = "open_page"`

1026 

1027 - `URL string`

1028 

1029 The URL opened by the model.

1030 

1031 - `type ResponseFunctionWebSearchActionFindInPage struct{…}`

1032 

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

1034 

1035 - `Pattern string`

1036 

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

1038 

1039 - `Type FindInPage`

1040 

1041 The action type.

1042 

1043 - `const FindInPageFindInPage FindInPage = "find_in_page"`

1044 

1045 - `URL string`

1046 

1047 The URL of the page searched for the pattern.

1048 

1049 - `Status ResponseFunctionWebSearchStatus`

1050 

1051 The status of the web search tool call.

1052 

1053 - `const ResponseFunctionWebSearchStatusInProgress ResponseFunctionWebSearchStatus = "in_progress"`

1054 

1055 - `const ResponseFunctionWebSearchStatusSearching ResponseFunctionWebSearchStatus = "searching"`

1056 

1057 - `const ResponseFunctionWebSearchStatusCompleted ResponseFunctionWebSearchStatus = "completed"`

1058 

1059 - `const ResponseFunctionWebSearchStatusFailed ResponseFunctionWebSearchStatus = "failed"`

1060 

1061 - `Type WebSearchCall`

1062 

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

1064 

1065 - `const WebSearchCallWebSearchCall WebSearchCall = "web_search_call"`

1066 

1067 - `type ResponseFunctionToolCall struct{…}`

1068 

1069 A tool call to run a function. See the

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

1071 

1072 - `Arguments string`

1073 

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

1075 

1076 - `CallID string`

1077 

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

1079 

1080 - `Name string`

1081 

1082 The name of the function to run.

1083 

1084 - `Type FunctionCall`

1085 

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

1087 

1088 - `const FunctionCallFunctionCall FunctionCall = "function_call"`

1089 

1090 - `ID string`

1091 

1092 The unique ID of the function tool call.

1093 

1094 - `Caller ResponseFunctionToolCallCallerUnion`

1095 

1096 The execution context that produced this tool call.

1097 

1098 - `type ResponseFunctionToolCallCallerDirect struct{…}`

1099 

1100 - `Type Direct`

1101 

1102 - `const DirectDirect Direct = "direct"`

1103 

1104 - `type ResponseFunctionToolCallCallerProgram struct{…}`

1105 

1106 - `CallerID string`

1107 

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

1109 

1110 - `Type Program`

1111 

1112 - `const ProgramProgram Program = "program"`

1113 

1114 - `Namespace string`

1115 

1116 The namespace of the function to run.

1117 

1118 - `Status ResponseFunctionToolCallStatus`

1119 

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

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

1122 

1123 - `const ResponseFunctionToolCallStatusInProgress ResponseFunctionToolCallStatus = "in_progress"`

1124 

1125 - `const ResponseFunctionToolCallStatusCompleted ResponseFunctionToolCallStatus = "completed"`

1126 

1127 - `const ResponseFunctionToolCallStatusIncomplete ResponseFunctionToolCallStatus = "incomplete"`

1128 

1129 - `type ResponseInputItemFunctionCallOutput struct{…}`

1130 

1131 The output of a function tool call.

1132 

1133 - `CallID string`

1134 

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

1136 

1137 - `Output ResponseInputItemFunctionCallOutputOutputUnion`

1138 

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

1140 

1141 - `string`

1142 

1143 - `type ResponseFunctionCallOutputItemList []ResponseFunctionCallOutputItemUnion`

1144 

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

1146 

1147 - `type ResponseInputTextContent struct{…}`

1148 

1149 A text input to the model.

1150 

1151 - `Text string`

1152 

1153 The text input to the model.

1154 

1155 - `Type InputText`

1156 

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

1158 

1159 - `const InputTextInputText InputText = "input_text"`

1160 

1161 - `PromptCacheBreakpoint ResponseInputTextContentPromptCacheBreakpoint`

1162 

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

1164 

1165 - `Mode Explicit`

1166 

1167 The breakpoint mode. Always `explicit`.

1168 

1169 - `const ExplicitExplicit Explicit = "explicit"`

1170 

1171 - `type ResponseInputImageContent struct{…}`

1172 

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

1174 

1175 - `Type InputImage`

1176 

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

1178 

1179 - `const InputImageInputImage InputImage = "input_image"`

1180 

1181 - `Detail ResponseInputImageContentDetail`

1182 

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

1184 

1185 - `const ResponseInputImageContentDetailLow ResponseInputImageContentDetail = "low"`

1186 

1187 - `const ResponseInputImageContentDetailHigh ResponseInputImageContentDetail = "high"`

1188 

1189 - `const ResponseInputImageContentDetailAuto ResponseInputImageContentDetail = "auto"`

1190 

1191 - `const ResponseInputImageContentDetailOriginal ResponseInputImageContentDetail = "original"`

1192 

1193 - `FileID string`

1194 

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

1196 

1197 - `ImageURL string`

1198 

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

1200 

1201 - `PromptCacheBreakpoint ResponseInputImageContentPromptCacheBreakpoint`

1202 

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

1204 

1205 - `Mode Explicit`

1206 

1207 The breakpoint mode. Always `explicit`.

1208 

1209 - `const ExplicitExplicit Explicit = "explicit"`

1210 

1211 - `type ResponseInputFileContent struct{…}`

1212 

1213 A file input to the model.

1214 

1215 - `Type InputFile`

1216 

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

1218 

1219 - `const InputFileInputFile InputFile = "input_file"`

1220 

1221 - `Detail ResponseInputFileContentDetail`

1222 

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

1224 

1225 - `const ResponseInputFileContentDetailAuto ResponseInputFileContentDetail = "auto"`

1226 

1227 - `const ResponseInputFileContentDetailLow ResponseInputFileContentDetail = "low"`

1228 

1229 - `const ResponseInputFileContentDetailHigh ResponseInputFileContentDetail = "high"`

1230 

1231 - `FileData string`

1232 

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

1234 

1235 - `FileID string`

1236 

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

1238 

1239 - `FileURL string`

1240 

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

1242 

1243 - `Filename string`

1244 

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

1246 

1247 - `PromptCacheBreakpoint ResponseInputFileContentPromptCacheBreakpoint`

1248 

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

1250 

1251 - `Mode Explicit`

1252 

1253 The breakpoint mode. Always `explicit`.

1254 

1255 - `const ExplicitExplicit Explicit = "explicit"`

1256 

1257 - `Type FunctionCallOutput`

1258 

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

1260 

1261 - `const FunctionCallOutputFunctionCallOutput FunctionCallOutput = "function_call_output"`

1262 

1263 - `ID string`

1264 

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

1266 

1267 - `Caller ResponseInputItemFunctionCallOutputCallerUnion`

1268 

1269 The execution context that produced this tool call.

1270 

1271 - `type ResponseInputItemFunctionCallOutputCallerDirect struct{…}`

1272 

1273 - `Type Direct`

1274 

1275 The caller type. Always `direct`.

1276 

1277 - `const DirectDirect Direct = "direct"`

1278 

1279 - `type ResponseInputItemFunctionCallOutputCallerProgram struct{…}`

1280 

1281 - `CallerID string`

1282 

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

1284 

1285 - `Type Program`

1286 

1287 The caller type. Always `program`.

1288 

1289 - `const ProgramProgram Program = "program"`

1290 

1291 - `Status string`

1292 

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

1294 

1295 - `const ResponseInputItemFunctionCallOutputStatusInProgress ResponseInputItemFunctionCallOutputStatus = "in_progress"`

1296 

1297 - `const ResponseInputItemFunctionCallOutputStatusCompleted ResponseInputItemFunctionCallOutputStatus = "completed"`

1298 

1299 - `const ResponseInputItemFunctionCallOutputStatusIncomplete ResponseInputItemFunctionCallOutputStatus = "incomplete"`

1300 

1301 - `type ResponseInputItemToolSearchCall struct{…}`

1302 

1303 - `Arguments any`

1304 

1305 The arguments supplied to the tool search call.

1306 

1307 - `Type ToolSearchCall`

1308 

1309 The item type. Always `tool_search_call`.

1310 

1311 - `const ToolSearchCallToolSearchCall ToolSearchCall = "tool_search_call"`

1312 

1313 - `ID string`

1314 

1315 The unique ID of this tool search call.

1316 

1317 - `CallID string`

1318 

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

1320 

1321 - `Execution string`

1322 

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

1324 

1325 - `const ResponseInputItemToolSearchCallExecutionServer ResponseInputItemToolSearchCallExecution = "server"`

1326 

1327 - `const ResponseInputItemToolSearchCallExecutionClient ResponseInputItemToolSearchCallExecution = "client"`

1328 

1329 - `Status string`

1330 

1331 The status of the tool search call.

1332 

1333 - `const ResponseInputItemToolSearchCallStatusInProgress ResponseInputItemToolSearchCallStatus = "in_progress"`

1334 

1335 - `const ResponseInputItemToolSearchCallStatusCompleted ResponseInputItemToolSearchCallStatus = "completed"`

1336 

1337 - `const ResponseInputItemToolSearchCallStatusIncomplete ResponseInputItemToolSearchCallStatus = "incomplete"`

1338 

1339 - `type ResponseToolSearchOutputItemParamResp struct{…}`

1340 

1341 - `Tools []ToolUnion`

1342 

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

1344 

1345 - `type FunctionTool struct{…}`

1346 

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

1348 

1349 - `Name string`

1350 

1351 The name of the function to call.

1352 

1353 - `Parameters map[string, any]`

1354 

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

1356 

1357 - `Strict bool`

1358 

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

1360 

1361 - `Type Function`

1362 

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

1364 

1365 - `const FunctionFunction Function = "function"`

1366 

1367 - `AllowedCallers []string`

1368 

1369 The tool invocation context(s).

1370 

1371 - `const FunctionToolAllowedCallerDirect FunctionToolAllowedCaller = "direct"`

1372 

1373 - `const FunctionToolAllowedCallerProgrammatic FunctionToolAllowedCaller = "programmatic"`

1374 

1375 - `DeferLoading bool`

1376 

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

1378 

1379 - `Description string`

1380 

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

1382 

1383 - `OutputSchema map[string, any]`

1384 

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

1386 

1387 - `type FileSearchTool struct{…}`

1388 

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

1390 

1391 - `Type FileSearch`

1392 

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

1394 

1395 - `const FileSearchFileSearch FileSearch = "file_search"`

1396 

1397 - `VectorStoreIDs []string`

1398 

1399 The IDs of the vector stores to search.

1400 

1401 - `Filters FileSearchToolFiltersUnion`

1402 

1403 A filter to apply.

1404 

1405 - `type ComparisonFilter struct{…}`

1406 

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

1408 

1409 - `Key string`

1410 

1411 The key to compare against the value.

1412 

1413 - `Type ComparisonFilterType`

1414 

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

1416 

1417 - `eq`: equals

1418 - `ne`: not equal

1419 - `gt`: greater than

1420 - `gte`: greater than or equal

1421 - `lt`: less than

1422 - `lte`: less than or equal

1423 - `in`: in

1424 - `nin`: not in

1425 

1426 - `const ComparisonFilterTypeEq ComparisonFilterType = "eq"`

1427 

1428 - `const ComparisonFilterTypeNe ComparisonFilterType = "ne"`

1429 

1430 - `const ComparisonFilterTypeGt ComparisonFilterType = "gt"`

1431 

1432 - `const ComparisonFilterTypeGte ComparisonFilterType = "gte"`

1433 

1434 - `const ComparisonFilterTypeLt ComparisonFilterType = "lt"`

1435 

1436 - `const ComparisonFilterTypeLte ComparisonFilterType = "lte"`

1437 

1438 - `const ComparisonFilterTypeIn ComparisonFilterType = "in"`

1439 

1440 - `const ComparisonFilterTypeNin ComparisonFilterType = "nin"`

1441 

1442 - `Value ComparisonFilterValueUnion`

1443 

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

1445 

1446 - `string`

1447 

1448 - `float64`

1449 

1450 - `bool`

1451 

1452 - `type ComparisonFilterValueArray []ComparisonFilterValueArrayItemUnion`

1453 

1454 - `string`

1455 

1456 - `float64`

1457 

1458 - `type CompoundFilter struct{…}`

1459 

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

1461 

1462 - `Filters []ComparisonFilter`

1463 

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

1465 

1466 - `type ComparisonFilter struct{…}`

1467 

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

1469 

1470 - `Type CompoundFilterType`

1471 

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

1473 

1474 - `const CompoundFilterTypeAnd CompoundFilterType = "and"`

1475 

1476 - `const CompoundFilterTypeOr CompoundFilterType = "or"`

1477 

1478 - `MaxNumResults int64`

1479 

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

1481 

1482 - `RankingOptions FileSearchToolRankingOptions`

1483 

1484 Ranking options for search.

1485 

1486 - `HybridSearch FileSearchToolRankingOptionsHybridSearch`

1487 

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

1489 

1490 - `EmbeddingWeight float64`

1491 

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

1493 

1494 - `TextWeight float64`

1495 

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

1497 

1498 - `Ranker string`

1499 

1500 The ranker to use for the file search.

1501 

1502 - `const FileSearchToolRankingOptionsRankerAuto FileSearchToolRankingOptionsRanker = "auto"`

1503 

1504 - `const FileSearchToolRankingOptionsRankerDefault2024_11_15 FileSearchToolRankingOptionsRanker = "default-2024-11-15"`

1505 

1506 - `ScoreThreshold float64`

1507 

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

1509 

1510 - `type ComputerTool struct{…}`

1511 

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

1513 

1514 - `Type Computer`

1515 

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

1517 

1518 - `const ComputerComputer Computer = "computer"`

1519 

1520 - `type ComputerUsePreviewTool struct{…}`

1521 

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

1523 

1524 - `DisplayHeight int64`

1525 

1526 The height of the computer display.

1527 

1528 - `DisplayWidth int64`

1529 

1530 The width of the computer display.

1531 

1532 - `Environment ComputerUsePreviewToolEnvironment`

1533 

1534 The type of computer environment to control.

1535 

1536 - `const ComputerUsePreviewToolEnvironmentWindows ComputerUsePreviewToolEnvironment = "windows"`

1537 

1538 - `const ComputerUsePreviewToolEnvironmentMac ComputerUsePreviewToolEnvironment = "mac"`

1539 

1540 - `const ComputerUsePreviewToolEnvironmentLinux ComputerUsePreviewToolEnvironment = "linux"`

1541 

1542 - `const ComputerUsePreviewToolEnvironmentUbuntu ComputerUsePreviewToolEnvironment = "ubuntu"`

1543 

1544 - `const ComputerUsePreviewToolEnvironmentBrowser ComputerUsePreviewToolEnvironment = "browser"`

1545 

1546 - `Type ComputerUsePreview`

1547 

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

1549 

1550 - `const ComputerUsePreviewComputerUsePreview ComputerUsePreview = "computer_use_preview"`

1551 

1552 - `type WebSearchTool struct{…}`

1553 

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

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

1556 

1557 - `Type WebSearchToolType`

1558 

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

1560 

1561 - `const WebSearchToolTypeWebSearch WebSearchToolType = "web_search"`

1562 

1563 - `const WebSearchToolTypeWebSearch2025_08_26 WebSearchToolType = "web_search_2025_08_26"`

1564 

1565 - `Filters WebSearchToolFilters`

1566 

1567 Filters for the search.

1568 

1569 - `AllowedDomains []string`

1570 

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

1572 Subdomains of the provided domains are allowed as well.

1573 

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

1575 

1576 - `SearchContextSize WebSearchToolSearchContextSize`

1577 

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

1579 

1580 - `const WebSearchToolSearchContextSizeLow WebSearchToolSearchContextSize = "low"`

1581 

1582 - `const WebSearchToolSearchContextSizeMedium WebSearchToolSearchContextSize = "medium"`

1583 

1584 - `const WebSearchToolSearchContextSizeHigh WebSearchToolSearchContextSize = "high"`

1585 

1586 - `UserLocation WebSearchToolUserLocation`

1587 

1588 The approximate location of the user.

1589 

1590 - `City string`

1591 

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

1593 

1594 - `Country string`

1595 

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

1597 

1598 - `Region string`

1599 

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

1601 

1602 - `Timezone string`

1603 

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

1605 

1606 - `Type string`

1607 

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

1609 

1610 - `const WebSearchToolUserLocationTypeApproximate WebSearchToolUserLocationType = "approximate"`

1611 

1612 - `type ToolMcp struct{…}`

1613 

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

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

1616 

1617 - `ServerLabel string`

1618 

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

1620 

1621 - `Type Mcp`

1622 

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

1624 

1625 - `const McpMcp Mcp = "mcp"`

1626 

1627 - `AllowedCallers []string`

1628 

1629 The tool invocation context(s).

1630 

1631 - `const ToolMcpAllowedCallerDirect ToolMcpAllowedCaller = "direct"`

1632 

1633 - `const ToolMcpAllowedCallerProgrammatic ToolMcpAllowedCaller = "programmatic"`

1634 

1635 - `AllowedTools ToolMcpAllowedToolsUnion`

1636 

1637 List of allowed tool names or a filter object.

1638 

1639 - `type ToolMcpAllowedToolsMcpAllowedTools []string`

1640 

1641 A string array of allowed tool names

1642 

1643 - `type ToolMcpAllowedToolsMcpToolFilter struct{…}`

1644 

1645 A filter object to specify which tools are allowed.

1646 

1647 - `ReadOnly bool`

1648 

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

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

1651 it will match this filter.

1652 

1653 - `ToolNames []string`

1654 

1655 List of allowed tool names.

1656 

1657 - `Authorization string`

1658 

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

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

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

1662 

1663 - `ConnectorID string`

1664 

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

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

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

1668 

1669 Currently supported `connector_id` values are:

1670 

1671 - Dropbox: `connector_dropbox`

1672 - Gmail: `connector_gmail`

1673 - Google Calendar: `connector_googlecalendar`

1674 - Google Drive: `connector_googledrive`

1675 - Microsoft Teams: `connector_microsoftteams`

1676 - Outlook Calendar: `connector_outlookcalendar`

1677 - Outlook Email: `connector_outlookemail`

1678 - SharePoint: `connector_sharepoint`

1679 

1680 - `const ToolMcpConnectorIDConnectorDropbox ToolMcpConnectorID = "connector_dropbox"`

1681 

1682 - `const ToolMcpConnectorIDConnectorGmail ToolMcpConnectorID = "connector_gmail"`

1683 

1684 - `const ToolMcpConnectorIDConnectorGooglecalendar ToolMcpConnectorID = "connector_googlecalendar"`

1685 

1686 - `const ToolMcpConnectorIDConnectorGoogledrive ToolMcpConnectorID = "connector_googledrive"`

1687 

1688 - `const ToolMcpConnectorIDConnectorMicrosoftteams ToolMcpConnectorID = "connector_microsoftteams"`

1689 

1690 - `const ToolMcpConnectorIDConnectorOutlookcalendar ToolMcpConnectorID = "connector_outlookcalendar"`

1691 

1692 - `const ToolMcpConnectorIDConnectorOutlookemail ToolMcpConnectorID = "connector_outlookemail"`

1693 

1694 - `const ToolMcpConnectorIDConnectorSharepoint ToolMcpConnectorID = "connector_sharepoint"`

1695 

1696 - `DeferLoading bool`

1697 

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

1699 

1700 - `Headers map[string, string]`

1701 

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

1703 or other purposes.

1704 

1705 - `RequireApproval ToolMcpRequireApprovalUnion`

1706 

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

1708 

1709 - `type ToolMcpRequireApprovalMcpToolApprovalFilter struct{…}`

1710 

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

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

1713 that require approval.

1714 

1715 - `Always ToolMcpRequireApprovalMcpToolApprovalFilterAlways`

1716 

1717 A filter object to specify which tools are allowed.

1718 

1719 - `ReadOnly bool`

1720 

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

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

1723 it will match this filter.

1724 

1725 - `ToolNames []string`

1726 

1727 List of allowed tool names.

1728 

1729 - `Never ToolMcpRequireApprovalMcpToolApprovalFilterNever`

1730 

1731 A filter object to specify which tools are allowed.

1732 

1733 - `ReadOnly bool`

1734 

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

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

1737 it will match this filter.

1738 

1739 - `ToolNames []string`

1740 

1741 List of allowed tool names.

1742 

1743 - `type ToolMcpRequireApprovalMcpToolApprovalSetting string`

1744 

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

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

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

1748 

1749 - `const ToolMcpRequireApprovalMcpToolApprovalSettingAlways ToolMcpRequireApprovalMcpToolApprovalSetting = "always"`

1750 

1751 - `const ToolMcpRequireApprovalMcpToolApprovalSettingNever ToolMcpRequireApprovalMcpToolApprovalSetting = "never"`

1752 

1753 - `ServerDescription string`

1754 

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

1756 

1757 - `ServerURL string`

1758 

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

1760 `tunnel_id` must be provided.

1761 

1762 - `TunnelID string`

1763 

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

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

1766 

1767 - `type ToolCodeInterpreter struct{…}`

1768 

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

1770 

1771 - `Container ToolCodeInterpreterContainerUnion`

1772 

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

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

1775 optional `memory_limit` setting.

1776 

1777 - `string`

1778 

1779 - `type ToolCodeInterpreterContainerCodeInterpreterContainerAuto struct{…}`

1780 

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

1782 

1783 - `Type Auto`

1784 

1785 Always `auto`.

1786 

1787 - `const AutoAuto Auto = "auto"`

1788 

1789 - `FileIDs []string`

1790 

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

1792 

1793 - `MemoryLimit string`

1794 

1795 The memory limit for the code interpreter container.

1796 

1797 - `const ToolCodeInterpreterContainerCodeInterpreterToolAutoMemoryLimit1g ToolCodeInterpreterContainerCodeInterpreterToolAutoMemoryLimit = "1g"`

1798 

1799 - `const ToolCodeInterpreterContainerCodeInterpreterToolAutoMemoryLimit4g ToolCodeInterpreterContainerCodeInterpreterToolAutoMemoryLimit = "4g"`

1800 

1801 - `const ToolCodeInterpreterContainerCodeInterpreterToolAutoMemoryLimit16g ToolCodeInterpreterContainerCodeInterpreterToolAutoMemoryLimit = "16g"`

1802 

1803 - `const ToolCodeInterpreterContainerCodeInterpreterToolAutoMemoryLimit64g ToolCodeInterpreterContainerCodeInterpreterToolAutoMemoryLimit = "64g"`

1804 

1805 - `NetworkPolicy ToolCodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicyUnion`

1806 

1807 Network access policy for the container.

1808 

1809 - `type ContainerNetworkPolicyDisabled struct{…}`

1810 

1811 - `Type Disabled`

1812 

1813 Disable outbound network access. Always `disabled`.

1814 

1815 - `const DisabledDisabled Disabled = "disabled"`

1816 

1817 - `type ContainerNetworkPolicyAllowlist struct{…}`

1818 

1819 - `AllowedDomains []string`

1820 

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

1822 

1823 - `Type Allowlist`

1824 

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

1826 

1827 - `const AllowlistAllowlist Allowlist = "allowlist"`

1828 

1829 - `DomainSecrets []ContainerNetworkPolicyDomainSecret`

1830 

1831 Optional domain-scoped secrets for allowlisted domains.

1832 

1833 - `Domain string`

1834 

1835 The domain associated with the secret.

1836 

1837 - `Name string`

1838 

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

1840 

1841 - `Value string`

1842 

1843 The secret value to inject for the domain.

1844 

1845 - `Type CodeInterpreter`

1846 

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

1848 

1849 - `const CodeInterpreterCodeInterpreter CodeInterpreter = "code_interpreter"`

1850 

1851 - `AllowedCallers []string`

1852 

1853 The tool invocation context(s).

1854 

1855 - `const ToolCodeInterpreterAllowedCallerDirect ToolCodeInterpreterAllowedCaller = "direct"`

1856 

1857 - `const ToolCodeInterpreterAllowedCallerProgrammatic ToolCodeInterpreterAllowedCaller = "programmatic"`

1858 

1859 - `type ToolProgrammaticToolCalling struct{…}`

1860 

1861 - `Type ProgrammaticToolCalling`

1862 

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

1864 

1865 - `const ProgrammaticToolCallingProgrammaticToolCalling ProgrammaticToolCalling = "programmatic_tool_calling"`

1866 

1867 - `type ToolImageGeneration struct{…}`

1868 

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

1870 

1871 - `Type ImageGeneration`

1872 

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

1874 

1875 - `const ImageGenerationImageGeneration ImageGeneration = "image_generation"`

1876 

1877 - `Action string`

1878 

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

1880 

1881 - `const ToolImageGenerationActionGenerate ToolImageGenerationAction = "generate"`

1882 

1883 - `const ToolImageGenerationActionEdit ToolImageGenerationAction = "edit"`

1884 

1885 - `const ToolImageGenerationActionAuto ToolImageGenerationAction = "auto"`

1886 

1887 - `Background string`

1888 

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

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

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

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

1893 automatically determine the best background for the image.

1894 

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

1896 transparent backgrounds. Requests with `background` set to

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

1898 `auto` instead.

1899 

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

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

1902 

1903 - `const ToolImageGenerationBackgroundTransparent ToolImageGenerationBackground = "transparent"`

1904 

1905 - `const ToolImageGenerationBackgroundOpaque ToolImageGenerationBackground = "opaque"`

1906 

1907 - `const ToolImageGenerationBackgroundAuto ToolImageGenerationBackground = "auto"`

1908 

1909 - `InputFidelity string`

1910 

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

1912 

1913 - `const ToolImageGenerationInputFidelityHigh ToolImageGenerationInputFidelity = "high"`

1914 

1915 - `const ToolImageGenerationInputFidelityLow ToolImageGenerationInputFidelity = "low"`

1916 

1917 - `InputImageMask ToolImageGenerationInputImageMask`

1918 

1919 Optional mask for inpainting. Contains `image_url`

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

1921 

1922 - `FileID string`

1923 

1924 File ID for the mask image.

1925 

1926 - `ImageURL string`

1927 

1928 Base64-encoded mask image.

1929 

1930 - `Model string`

1931 

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

1933 

1934 - `string`

1935 

1936 - `string`

1937 

1938 - `const ToolImageGenerationModelGPTImage1 ToolImageGenerationModel = "gpt-image-1"`

1939 

1940 - `const ToolImageGenerationModelGPTImage1Mini ToolImageGenerationModel = "gpt-image-1-mini"`

1941 

1942 - `const ToolImageGenerationModelGPTImage2 ToolImageGenerationModel = "gpt-image-2"`

1943 

1944 - `const ToolImageGenerationModelGPTImage2_2026_04_21 ToolImageGenerationModel = "gpt-image-2-2026-04-21"`

1945 

1946 - `const ToolImageGenerationModelGPTImage1_5 ToolImageGenerationModel = "gpt-image-1.5"`

1947 

1948 - `const ToolImageGenerationModelChatgptImageLatest ToolImageGenerationModel = "chatgpt-image-latest"`

1949 

1950 - `Moderation string`

1951 

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

1953 

1954 - `const ToolImageGenerationModerationAuto ToolImageGenerationModeration = "auto"`

1955 

1956 - `const ToolImageGenerationModerationLow ToolImageGenerationModeration = "low"`

1957 

1958 - `OutputCompression int64`

1959 

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

1961 

1962 - `OutputFormat string`

1963 

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

1965 `jpeg`. Default: `png`.

1966 

1967 - `const ToolImageGenerationOutputFormatPNG ToolImageGenerationOutputFormat = "png"`

1968 

1969 - `const ToolImageGenerationOutputFormatWebP ToolImageGenerationOutputFormat = "webp"`

1970 

1971 - `const ToolImageGenerationOutputFormatJPEG ToolImageGenerationOutputFormat = "jpeg"`

1972 

1973 - `PartialImages int64`

1974 

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

1976 

1977 - `Quality string`

1978 

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

1980 or `auto`. Default: `auto`.

1981 

1982 - `const ToolImageGenerationQualityLow ToolImageGenerationQuality = "low"`

1983 

1984 - `const ToolImageGenerationQualityMedium ToolImageGenerationQuality = "medium"`

1985 

1986 - `const ToolImageGenerationQualityHigh ToolImageGenerationQuality = "high"`

1987 

1988 - `const ToolImageGenerationQualityAuto ToolImageGenerationQuality = "auto"`

1989 

1990 - `Size string`

1991 

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

1993 

1994 - `string`

1995 

1996 - `string`