ruby/resources/responses/subresources/input_tokens/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

1# Input Tokens

2 

3## Get input token counts

4 

5`responses.input_tokens.count(**kwargs) -> InputTokenCountResponse`

6 

7**post** `/responses/input_tokens`

8 

9Returns input token counts of the request.

10 

11Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count.

12 

13### Parameters

14 

15- `conversation: String | ResponseConversationParam`

16 

17 The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request.

18 Input items and output items from this response are automatically added to this conversation after this response completes.

19 

20 - `String = String`

21 

22 The unique ID of the conversation.

23 

24 - `class ResponseConversationParam`

25 

26 The conversation that this response belongs to.

27 

28 - `id: String`

29 

30 The unique ID of the conversation.

31 

32- `input: String | Array[ResponseInputItem]`

33 

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

35 

36 - `String = String`

37 

38 A text input to the model, equivalent to a text input with the `user` role.

39 

40 - `UnionMember1 = Array[ResponseInputItem]`

41 

42 A list of one or many input items to the model, containing different content types.

43 

44 - `class EasyInputMessage`

45 

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

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

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

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

50 interactions.

51 

52 - `content: String | ResponseInputMessageContentList`

53 

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

55 Can also contain previous assistant responses.

56 

57 - `String = String`

58 

59 A text input to the model.

60 

61 - `ResponseInputMessageContentList = Array[ResponseInputContent]`

62 

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

64 types.

65 

66 - `class ResponseInputText`

67 

68 A text input to the model.

69 

70 - `text: String`

71 

72 The text input to the model.

73 

74 - `type: :input_text`

75 

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

77 

78 - `:input_text`

79 

80 - `class ResponseInputImage`

81 

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

83 

84 - `detail: :low | :high | :auto | :original`

85 

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

87 

88 - `:low`

89 

90 - `:high`

91 

92 - `:auto`

93 

94 - `:original`

95 

96 - `type: :input_image`

97 

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

99 

100 - `:input_image`

101 

102 - `file_id: String`

103 

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

105 

106 - `image_url: String`

107 

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

109 

110 - `class ResponseInputFile`

111 

112 A file input to the model.

113 

114 - `type: :input_file`

115 

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

117 

118 - `:input_file`

119 

120 - `detail: :low | :high`

121 

122 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

123 

124 - `:low`

125 

126 - `:high`

127 

128 - `file_data: String`

129 

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

131 

132 - `file_id: String`

133 

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

135 

136 - `file_url: String`

137 

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

139 

140 - `filename: String`

141 

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

143 

144 - `role: :user | :assistant | :system | :developer`

145 

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

147 `developer`.

148 

149 - `:user`

150 

151 - `:assistant`

152 

153 - `:system`

154 

155 - `:developer`

156 

157 - `phase: :commentary | :final_answer`

158 

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

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

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

162 

163 - `:commentary`

164 

165 - `:final_answer`

166 

167 - `type: :message`

168 

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

170 

171 - `:message`

172 

173 - `class Message`

174 

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

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

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

178 

179 - `content: ResponseInputMessageContentList`

180 

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

182 types.

183 

184 - `role: :user | :system | :developer`

185 

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

187 

188 - `:user`

189 

190 - `:system`

191 

192 - `:developer`

193 

194 - `status: :in_progress | :completed | :incomplete`

195 

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

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

198 

199 - `:in_progress`

200 

201 - `:completed`

202 

203 - `:incomplete`

204 

205 - `type: :message`

206 

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

208 

209 - `:message`

210 

211 - `class ResponseOutputMessage`

212 

213 An output message from the model.

214 

215 - `id: String`

216 

217 The unique ID of the output message.

218 

219 - `content: Array[ResponseOutputText | ResponseOutputRefusal]`

220 

221 The content of the output message.

222 

223 - `class ResponseOutputText`

224 

225 A text output from the model.

226 

227 - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]`

228 

229 The annotations of the text output.

230 

231 - `class FileCitation`

232 

233 A citation to a file.

234 

235 - `file_id: String`

236 

237 The ID of the file.

238 

239 - `filename: String`

240 

241 The filename of the file cited.

242 

243 - `index: Integer`

244 

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

246 

247 - `type: :file_citation`

248 

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

250 

251 - `:file_citation`

252 

253 - `class URLCitation`

254 

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

256 

257 - `end_index: Integer`

258 

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

260 

261 - `start_index: Integer`

262 

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

264 

265 - `title: String`

266 

267 The title of the web resource.

268 

269 - `type: :url_citation`

270 

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

272 

273 - `:url_citation`

274 

275 - `url: String`

276 

277 The URL of the web resource.

278 

279 - `class ContainerFileCitation`

280 

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

282 

283 - `container_id: String`

284 

285 The ID of the container file.

286 

287 - `end_index: Integer`

288 

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

290 

291 - `file_id: String`

292 

293 The ID of the file.

294 

295 - `filename: String`

296 

297 The filename of the container file cited.

298 

299 - `start_index: Integer`

300 

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

302 

303 - `type: :container_file_citation`

304 

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

306 

307 - `:container_file_citation`

308 

309 - `class FilePath`

310 

311 A path to a file.

312 

313 - `file_id: String`

314 

315 The ID of the file.

316 

317 - `index: Integer`

318 

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

320 

321 - `type: :file_path`

322 

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

324 

325 - `:file_path`

326 

327 - `text: String`

328 

329 The text output from the model.

330 

331 - `type: :output_text`

332 

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

334 

335 - `:output_text`

336 

337 - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]`

338 

339 - `token: String`

340 

341 - `bytes: Array[Integer]`

342 

343 - `logprob: Float`

344 

345 - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]`

346 

347 - `token: String`

348 

349 - `bytes: Array[Integer]`

350 

351 - `logprob: Float`

352 

353 - `class ResponseOutputRefusal`

354 

355 A refusal from the model.

356 

357 - `refusal: String`

358 

359 The refusal explanation from the model.

360 

361 - `type: :refusal`

362 

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

364 

365 - `:refusal`

366 

367 - `role: :assistant`

368 

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

370 

371 - `:assistant`

372 

373 - `status: :in_progress | :completed | :incomplete`

374 

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

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

377 

378 - `:in_progress`

379 

380 - `:completed`

381 

382 - `:incomplete`

383 

384 - `type: :message`

385 

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

387 

388 - `:message`

389 

390 - `phase: :commentary | :final_answer`

391 

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

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

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

395 

396 - `:commentary`

397 

398 - `:final_answer`

399 

400 - `class ResponseFileSearchToolCall`

401 

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

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

404 

405 - `id: String`

406 

407 The unique ID of the file search tool call.

408 

409 - `queries: Array[String]`

410 

411 The queries used to search for files.

412 

413 - `status: :in_progress | :searching | :completed | 2 more`

414 

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

416 `searching`, `incomplete` or `failed`,

417 

418 - `:in_progress`

419 

420 - `:searching`

421 

422 - `:completed`

423 

424 - `:incomplete`

425 

426 - `:failed`

427 

428 - `type: :file_search_call`

429 

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

431 

432 - `:file_search_call`

433 

434 - `results: Array[Result{ attributes, file_id, filename, 2 more}]`

435 

436 The results of the file search tool call.

437 

438 - `attributes: Hash[Symbol, String | Float | bool]`

439 

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

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

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

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

444 length of 512 characters, booleans, or numbers.

445 

446 - `String = String`

447 

448 - `Float = Float`

449 

450 - `UnionMember2 = bool`

451 

452 - `file_id: String`

453 

454 The unique ID of the file.

455 

456 - `filename: String`

457 

458 The name of the file.

459 

460 - `score: Float`

461 

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

463 

464 - `text: String`

465 

466 The text that was retrieved from the file.

467 

468 - `class ResponseComputerToolCall`

469 

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

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

472 

473 - `id: String`

474 

475 The unique ID of the computer call.

476 

477 - `call_id: String`

478 

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

480 

481 - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]`

482 

483 The pending safety checks for the computer call.

484 

485 - `id: String`

486 

487 The ID of the pending safety check.

488 

489 - `code: String`

490 

491 The type of the pending safety check.

492 

493 - `message: String`

494 

495 Details about the pending safety check.

496 

497 - `status: :in_progress | :completed | :incomplete`

498 

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

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

501 

502 - `:in_progress`

503 

504 - `:completed`

505 

506 - `:incomplete`

507 

508 - `type: :computer_call`

509 

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

511 

512 - `:computer_call`

513 

514 - `action: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more`

515 

516 A click action.

517 

518 - `class Click`

519 

520 A click action.

521 

522 - `button: :left | :right | :wheel | 2 more`

523 

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

525 

526 - `:left`

527 

528 - `:right`

529 

530 - `:wheel`

531 

532 - `:back`

533 

534 - `:forward`

535 

536 - `type: :click`

537 

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

539 

540 - `:click`

541 

542 - `x: Integer`

543 

544 The x-coordinate where the click occurred.

545 

546 - `y_: Integer`

547 

548 The y-coordinate where the click occurred.

549 

550 - `keys: Array[String]`

551 

552 The keys being held while clicking.

553 

554 - `class DoubleClick`

555 

556 A double click action.

557 

558 - `keys: Array[String]`

559 

560 The keys being held while double-clicking.

561 

562 - `type: :double_click`

563 

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

565 

566 - `:double_click`

567 

568 - `x: Integer`

569 

570 The x-coordinate where the double click occurred.

571 

572 - `y_: Integer`

573 

574 The y-coordinate where the double click occurred.

575 

576 - `class Drag`

577 

578 A drag action.

579 

580 - `path: Array[Path{ x, y_}]`

581 

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

583 

584 ```

585 [

586 { x: 100, y: 200 },

587 { x: 200, y: 300 }

588 ]

589 ```

590 

591 - `x: Integer`

592 

593 The x-coordinate.

594 

595 - `y_: Integer`

596 

597 The y-coordinate.

598 

599 - `type: :drag`

600 

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

602 

603 - `:drag`

604 

605 - `keys: Array[String]`

606 

607 The keys being held while dragging the mouse.

608 

609 - `class Keypress`

610 

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

612 

613 - `keys: Array[String]`

614 

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

616 

617 - `type: :keypress`

618 

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

620 

621 - `:keypress`

622 

623 - `class Move`

624 

625 A mouse move action.

626 

627 - `type: :move`

628 

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

630 

631 - `:move`

632 

633 - `x: Integer`

634 

635 The x-coordinate to move to.

636 

637 - `y_: Integer`

638 

639 The y-coordinate to move to.

640 

641 - `keys: Array[String]`

642 

643 The keys being held while moving the mouse.

644 

645 - `class Screenshot`

646 

647 A screenshot action.

648 

649 - `type: :screenshot`

650 

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

652 

653 - `:screenshot`

654 

655 - `class Scroll`

656 

657 A scroll action.

658 

659 - `scroll_x: Integer`

660 

661 The horizontal scroll distance.

662 

663 - `scroll_y: Integer`

664 

665 The vertical scroll distance.

666 

667 - `type: :scroll`

668 

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

670 

671 - `:scroll`

672 

673 - `x: Integer`

674 

675 The x-coordinate where the scroll occurred.

676 

677 - `y_: Integer`

678 

679 The y-coordinate where the scroll occurred.

680 

681 - `keys: Array[String]`

682 

683 The keys being held while scrolling.

684 

685 - `class Type`

686 

687 An action to type in text.

688 

689 - `text: String`

690 

691 The text to type.

692 

693 - `type: :type`

694 

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

696 

697 - `:type`

698 

699 - `class Wait`

700 

701 A wait action.

702 

703 - `type: :wait`

704 

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

706 

707 - `:wait`

708 

709 - `actions: ComputerActionList`

710 

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

712 `type` discriminator and action-specific fields.

713 

714 - `class Click`

715 

716 A click action.

717 

718 - `button: :left | :right | :wheel | 2 more`

719 

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

721 

722 - `:left`

723 

724 - `:right`

725 

726 - `:wheel`

727 

728 - `:back`

729 

730 - `:forward`

731 

732 - `type: :click`

733 

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

735 

736 - `:click`

737 

738 - `x: Integer`

739 

740 The x-coordinate where the click occurred.

741 

742 - `y_: Integer`

743 

744 The y-coordinate where the click occurred.

745 

746 - `keys: Array[String]`

747 

748 The keys being held while clicking.

749 

750 - `class DoubleClick`

751 

752 A double click action.

753 

754 - `keys: Array[String]`

755 

756 The keys being held while double-clicking.

757 

758 - `type: :double_click`

759 

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

761 

762 - `:double_click`

763 

764 - `x: Integer`

765 

766 The x-coordinate where the double click occurred.

767 

768 - `y_: Integer`

769 

770 The y-coordinate where the double click occurred.

771 

772 - `class Drag`

773 

774 A drag action.

775 

776 - `path: Array[Path{ x, y_}]`

777 

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

779 

780 ```

781 [

782 { x: 100, y: 200 },

783 { x: 200, y: 300 }

784 ]

785 ```

786 

787 - `x: Integer`

788 

789 The x-coordinate.

790 

791 - `y_: Integer`

792 

793 The y-coordinate.

794 

795 - `type: :drag`

796 

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

798 

799 - `:drag`

800 

801 - `keys: Array[String]`

802 

803 The keys being held while dragging the mouse.

804 

805 - `class Keypress`

806 

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

808 

809 - `keys: Array[String]`

810 

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

812 

813 - `type: :keypress`

814 

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

816 

817 - `:keypress`

818 

819 - `class Move`

820 

821 A mouse move action.

822 

823 - `type: :move`

824 

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

826 

827 - `:move`

828 

829 - `x: Integer`

830 

831 The x-coordinate to move to.

832 

833 - `y_: Integer`

834 

835 The y-coordinate to move to.

836 

837 - `keys: Array[String]`

838 

839 The keys being held while moving the mouse.

840 

841 - `class Screenshot`

842 

843 A screenshot action.

844 

845 - `type: :screenshot`

846 

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

848 

849 - `:screenshot`

850 

851 - `class Scroll`

852 

853 A scroll action.

854 

855 - `scroll_x: Integer`

856 

857 The horizontal scroll distance.

858 

859 - `scroll_y: Integer`

860 

861 The vertical scroll distance.

862 

863 - `type: :scroll`

864 

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

866 

867 - `:scroll`

868 

869 - `x: Integer`

870 

871 The x-coordinate where the scroll occurred.

872 

873 - `y_: Integer`

874 

875 The y-coordinate where the scroll occurred.

876 

877 - `keys: Array[String]`

878 

879 The keys being held while scrolling.

880 

881 - `class Type`

882 

883 An action to type in text.

884 

885 - `text: String`

886 

887 The text to type.

888 

889 - `type: :type`

890 

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

892 

893 - `:type`

894 

895 - `class Wait`

896 

897 A wait action.

898 

899 - `type: :wait`

900 

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

902 

903 - `:wait`

904 

905 - `class ComputerCallOutput`

906 

907 The output of a computer tool call.

908 

909 - `call_id: String`

910 

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

912 

913 - `output: ResponseComputerToolCallOutputScreenshot`

914 

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

916 

917 - `type: :computer_screenshot`

918 

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

920 always set to `computer_screenshot`.

921 

922 - `:computer_screenshot`

923 

924 - `file_id: String`

925 

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

927 

928 - `image_url: String`

929 

930 The URL of the screenshot image.

931 

932 - `type: :computer_call_output`

933 

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

935 

936 - `:computer_call_output`

937 

938 - `id: String`

939 

940 The ID of the computer tool call output.

941 

942 - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]`

943 

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

945 

946 - `id: String`

947 

948 The ID of the pending safety check.

949 

950 - `code: String`

951 

952 The type of the pending safety check.

953 

954 - `message: String`

955 

956 Details about the pending safety check.

957 

958 - `status: :in_progress | :completed | :incomplete`

959 

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

961 

962 - `:in_progress`

963 

964 - `:completed`

965 

966 - `:incomplete`

967 

968 - `class ResponseFunctionWebSearch`

969 

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

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

972 

973 - `id: String`

974 

975 The unique ID of the web search tool call.

976 

977 - `action: Search{ query, type, queries, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}`

978 

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

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

981 

982 - `class Search`

983 

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

985 

986 - `query: String`

987 

988 [DEPRECATED] The search query.

989 

990 - `type: :search`

991 

992 The action type.

993 

994 - `:search`

995 

996 - `queries: Array[String]`

997 

998 The search queries.

999 

1000 - `sources: Array[Source{ type, url}]`

1001 

1002 The sources used in the search.

1003 

1004 - `type: :url`

1005 

1006 The type of source. Always `url`.

1007 

1008 - `:url`

1009 

1010 - `url: String`

1011 

1012 The URL of the source.

1013 

1014 - `class OpenPage`

1015 

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

1017 

1018 - `type: :open_page`

1019 

1020 The action type.

1021 

1022 - `:open_page`

1023 

1024 - `url: String`

1025 

1026 The URL opened by the model.

1027 

1028 - `class FindInPage`

1029 

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

1031 

1032 - `pattern: String`

1033 

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

1035 

1036 - `type: :find_in_page`

1037 

1038 The action type.

1039 

1040 - `:find_in_page`

1041 

1042 - `url: String`

1043 

1044 The URL of the page searched for the pattern.

1045 

1046 - `status: :in_progress | :searching | :completed | :failed`

1047 

1048 The status of the web search tool call.

1049 

1050 - `:in_progress`

1051 

1052 - `:searching`

1053 

1054 - `:completed`

1055 

1056 - `:failed`

1057 

1058 - `type: :web_search_call`

1059 

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

1061 

1062 - `:web_search_call`

1063 

1064 - `class ResponseFunctionToolCall`

1065 

1066 A tool call to run a function. See the

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

1068 

1069 - `arguments: String`

1070 

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

1072 

1073 - `call_id: String`

1074 

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

1076 

1077 - `name: String`

1078 

1079 The name of the function to run.

1080 

1081 - `type: :function_call`

1082 

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

1084 

1085 - `:function_call`

1086 

1087 - `id: String`

1088 

1089 The unique ID of the function tool call.

1090 

1091 - `namespace: String`

1092 

1093 The namespace of the function to run.

1094 

1095 - `status: :in_progress | :completed | :incomplete`

1096 

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

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

1099 

1100 - `:in_progress`

1101 

1102 - `:completed`

1103 

1104 - `:incomplete`

1105 

1106 - `class FunctionCallOutput`

1107 

1108 The output of a function tool call.

1109 

1110 - `call_id: String`

1111 

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

1113 

1114 - `output: String | ResponseFunctionCallOutputItemList`

1115 

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

1117 

1118 - `String = String`

1119 

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

1121 

1122 - `ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]`

1123 

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

1125 

1126 - `class ResponseInputTextContent`

1127 

1128 A text input to the model.

1129 

1130 - `text: String`

1131 

1132 The text input to the model.

1133 

1134 - `type: :input_text`

1135 

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

1137 

1138 - `:input_text`

1139 

1140 - `class ResponseInputImageContent`

1141 

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

1143 

1144 - `type: :input_image`

1145 

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

1147 

1148 - `:input_image`

1149 

1150 - `detail: :low | :high | :auto | :original`

1151 

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

1153 

1154 - `:low`

1155 

1156 - `:high`

1157 

1158 - `:auto`

1159 

1160 - `:original`

1161 

1162 - `file_id: String`

1163 

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

1165 

1166 - `image_url: String`

1167 

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

1169 

1170 - `class ResponseInputFileContent`

1171 

1172 A file input to the model.

1173 

1174 - `type: :input_file`

1175 

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

1177 

1178 - `:input_file`

1179 

1180 - `detail: :low | :high`

1181 

1182 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

1183 

1184 - `:low`

1185 

1186 - `:high`

1187 

1188 - `file_data: String`

1189 

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

1191 

1192 - `file_id: String`

1193 

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

1195 

1196 - `file_url: String`

1197 

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

1199 

1200 - `filename: String`

1201 

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

1203 

1204 - `type: :function_call_output`

1205 

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

1207 

1208 - `:function_call_output`

1209 

1210 - `id: String`

1211 

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

1213 

1214 - `status: :in_progress | :completed | :incomplete`

1215 

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

1217 

1218 - `:in_progress`

1219 

1220 - `:completed`

1221 

1222 - `:incomplete`

1223 

1224 - `class ToolSearchCall`

1225 

1226 - `arguments: untyped`

1227 

1228 The arguments supplied to the tool search call.

1229 

1230 - `type: :tool_search_call`

1231 

1232 The item type. Always `tool_search_call`.

1233 

1234 - `:tool_search_call`

1235 

1236 - `id: String`

1237 

1238 The unique ID of this tool search call.

1239 

1240 - `call_id: String`

1241 

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

1243 

1244 - `execution: :server | :client`

1245 

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

1247 

1248 - `:server`

1249 

1250 - `:client`

1251 

1252 - `status: :in_progress | :completed | :incomplete`

1253 

1254 The status of the tool search call.

1255 

1256 - `:in_progress`

1257 

1258 - `:completed`

1259 

1260 - `:incomplete`

1261 

1262 - `class ResponseToolSearchOutputItemParam`

1263 

1264 - `tools: Array[Tool]`

1265 

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

1267 

1268 - `class FunctionTool`

1269 

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

1271 

1272 - `name: String`

1273 

1274 The name of the function to call.

1275 

1276 - `parameters: Hash[Symbol, untyped]`

1277 

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

1279 

1280 - `strict: bool`

1281 

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

1283 

1284 - `type: :function`

1285 

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

1287 

1288 - `:function`

1289 

1290 - `defer_loading: bool`

1291 

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

1293 

1294 - `description: String`

1295 

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

1297 

1298 - `class FileSearchTool`

1299 

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

1301 

1302 - `type: :file_search`

1303 

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

1305 

1306 - `:file_search`

1307 

1308 - `vector_store_ids: Array[String]`

1309 

1310 The IDs of the vector stores to search.

1311 

1312 - `filters: ComparisonFilter | CompoundFilter`

1313 

1314 A filter to apply.

1315 

1316 - `class ComparisonFilter`

1317 

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

1319 

1320 - `key: String`

1321 

1322 The key to compare against the value.

1323 

1324 - `type: :eq | :ne | :gt | 5 more`

1325 

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

1327 

1328 - `eq`: equals

1329 - `ne`: not equal

1330 - `gt`: greater than

1331 - `gte`: greater than or equal

1332 - `lt`: less than

1333 - `lte`: less than or equal

1334 - `in`: in

1335 - `nin`: not in

1336 

1337 - `:eq`

1338 

1339 - `:ne`

1340 

1341 - `:gt`

1342 

1343 - `:gte`

1344 

1345 - `:lt`

1346 

1347 - `:lte`

1348 

1349 - `:in`

1350 

1351 - `:nin`

1352 

1353 - `value: String | Float | bool | Array[String | Float]`

1354 

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

1356 

1357 - `String = String`

1358 

1359 - `Float = Float`

1360 

1361 - `UnionMember2 = bool`

1362 

1363 - `UnionMember3 = Array[String | Float]`

1364 

1365 - `String = String`

1366 

1367 - `Float = Float`

1368 

1369 - `class CompoundFilter`

1370 

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

1372 

1373 - `filters: Array[ComparisonFilter | untyped]`

1374 

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

1376 

1377 - `class ComparisonFilter`

1378 

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

1380 

1381 - `UnionMember1 = untyped`

1382 

1383 - `type: :and | :or`

1384 

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

1386 

1387 - `:and`

1388 

1389 - `:or`

1390 

1391 - `max_num_results: Integer`

1392 

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

1394 

1395 - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}`

1396 

1397 Ranking options for search.

1398 

1399 - `hybrid_search: HybridSearch{ embedding_weight, text_weight}`

1400 

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

1402 

1403 - `embedding_weight: Float`

1404 

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

1406 

1407 - `text_weight: Float`

1408 

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

1410 

1411 - `ranker: :auto | :"default-2024-11-15"`

1412 

1413 The ranker to use for the file search.

1414 

1415 - `:auto`

1416 

1417 - `:"default-2024-11-15"`

1418 

1419 - `score_threshold: Float`

1420 

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

1422 

1423 - `class ComputerTool`

1424 

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

1426 

1427 - `type: :computer`

1428 

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

1430 

1431 - `:computer`

1432 

1433 - `class ComputerUsePreviewTool`

1434 

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

1436 

1437 - `display_height: Integer`

1438 

1439 The height of the computer display.

1440 

1441 - `display_width: Integer`

1442 

1443 The width of the computer display.

1444 

1445 - `environment: :windows | :mac | :linux | 2 more`

1446 

1447 The type of computer environment to control.

1448 

1449 - `:windows`

1450 

1451 - `:mac`

1452 

1453 - `:linux`

1454 

1455 - `:ubuntu`

1456 

1457 - `:browser`

1458 

1459 - `type: :computer_use_preview`

1460 

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

1462 

1463 - `:computer_use_preview`

1464 

1465 - `class WebSearchTool`

1466 

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

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

1469 

1470 - `type: :web_search | :web_search_2025_08_26`

1471 

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

1473 

1474 - `:web_search`

1475 

1476 - `:web_search_2025_08_26`

1477 

1478 - `filters: Filters{ allowed_domains}`

1479 

1480 Filters for the search.

1481 

1482 - `allowed_domains: Array[String]`

1483 

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

1485 Subdomains of the provided domains are allowed as well.

1486 

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

1488 

1489 - `search_context_size: :low | :medium | :high`

1490 

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

1492 

1493 - `:low`

1494 

1495 - `:medium`

1496 

1497 - `:high`

1498 

1499 - `user_location: UserLocation{ city, country, region, 2 more}`

1500 

1501 The approximate location of the user.

1502 

1503 - `city: String`

1504 

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

1506 

1507 - `country: String`

1508 

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

1510 

1511 - `region: String`

1512 

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

1514 

1515 - `timezone: String`

1516 

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

1518 

1519 - `type: :approximate`

1520 

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

1522 

1523 - `:approximate`

1524 

1525 - `class Mcp`

1526 

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

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

1529 

1530 - `server_label: String`

1531 

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

1533 

1534 - `type: :mcp`

1535 

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

1537 

1538 - `:mcp`

1539 

1540 - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}`

1541 

1542 List of allowed tool names or a filter object.

1543 

1544 - `McpAllowedTools = Array[String]`

1545 

1546 A string array of allowed tool names

1547 

1548 - `class McpToolFilter`

1549 

1550 A filter object to specify which tools are allowed.

1551 

1552 - `read_only: bool`

1553 

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

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

1556 it will match this filter.

1557 

1558 - `tool_names: Array[String]`

1559 

1560 List of allowed tool names.

1561 

1562 - `authorization: String`

1563 

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

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

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

1567 

1568 - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more`

1569 

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

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

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

1573 

1574 Currently supported `connector_id` values are:

1575 

1576 - Dropbox: `connector_dropbox`

1577 - Gmail: `connector_gmail`

1578 - Google Calendar: `connector_googlecalendar`

1579 - Google Drive: `connector_googledrive`

1580 - Microsoft Teams: `connector_microsoftteams`

1581 - Outlook Calendar: `connector_outlookcalendar`

1582 - Outlook Email: `connector_outlookemail`

1583 - SharePoint: `connector_sharepoint`

1584 

1585 - `:connector_dropbox`

1586 

1587 - `:connector_gmail`

1588 

1589 - `:connector_googlecalendar`

1590 

1591 - `:connector_googledrive`

1592 

1593 - `:connector_microsoftteams`

1594 

1595 - `:connector_outlookcalendar`

1596 

1597 - `:connector_outlookemail`

1598 

1599 - `:connector_sharepoint`

1600 

1601 - `defer_loading: bool`

1602 

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

1604 

1605 - `headers: Hash[Symbol, String]`

1606 

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

1608 or other purposes.

1609 

1610 - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never`

1611 

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

1613 

1614 - `class McpToolApprovalFilter`

1615 

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

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

1618 that require approval.

1619 

1620 - `always: Always{ read_only, tool_names}`

1621 

1622 A filter object to specify which tools are allowed.

1623 

1624 - `read_only: bool`

1625 

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

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

1628 it will match this filter.

1629 

1630 - `tool_names: Array[String]`

1631 

1632 List of allowed tool names.

1633 

1634 - `never: Never{ read_only, tool_names}`

1635 

1636 A filter object to specify which tools are allowed.

1637 

1638 - `read_only: bool`

1639 

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

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

1642 it will match this filter.

1643 

1644 - `tool_names: Array[String]`

1645 

1646 List of allowed tool names.

1647 

1648 - `McpToolApprovalSetting = :always | :never`

1649 

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

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

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

1653 

1654 - `:always`

1655 

1656 - `:never`

1657 

1658 - `server_description: String`

1659 

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

1661 

1662 - `server_url: String`

1663 

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

1665 provided.

1666 

1667 - `class CodeInterpreter`

1668 

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

1670 

1671 - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}`

1672 

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

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

1675 optional `memory_limit` setting.

1676 

1677 - `String = String`

1678 

1679 The container ID.

1680 

1681 - `class CodeInterpreterToolAuto`

1682 

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

1684 

1685 - `type: :auto`

1686 

1687 Always `auto`.

1688 

1689 - `:auto`

1690 

1691 - `file_ids: Array[String]`

1692 

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

1694 

1695 - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"`

1696 

1697 The memory limit for the code interpreter container.

1698 

1699 - `:"1g"`

1700 

1701 - `:"4g"`

1702 

1703 - `:"16g"`

1704 

1705 - `:"64g"`

1706 

1707 - `network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist`

1708 

1709 Network access policy for the container.

1710 

1711 - `class ContainerNetworkPolicyDisabled`

1712 

1713 - `type: :disabled`

1714 

1715 Disable outbound network access. Always `disabled`.

1716 

1717 - `:disabled`

1718 

1719 - `class ContainerNetworkPolicyAllowlist`

1720 

1721 - `allowed_domains: Array[String]`

1722 

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

1724 

1725 - `type: :allowlist`

1726 

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

1728 

1729 - `:allowlist`

1730 

1731 - `domain_secrets: Array[ContainerNetworkPolicyDomainSecret]`

1732 

1733 Optional domain-scoped secrets for allowlisted domains.

1734 

1735 - `domain: String`

1736 

1737 The domain associated with the secret.

1738 

1739 - `name: String`

1740 

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

1742 

1743 - `value: String`

1744 

1745 The secret value to inject for the domain.

1746 

1747 - `type: :code_interpreter`

1748 

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

1750 

1751 - `:code_interpreter`

1752 

1753 - `class ImageGeneration`

1754 

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

1756 

1757 - `type: :image_generation`

1758 

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

1760 

1761 - `:image_generation`

1762 

1763 - `action: :generate | :edit | :auto`

1764 

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

1766 

1767 - `:generate`

1768 

1769 - `:edit`

1770 

1771 - `:auto`

1772 

1773 - `background: :transparent | :opaque | :auto`

1774 

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

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

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

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

1779 automatically determine the best background for the image.

1780 

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

1782 transparent backgrounds. Requests with `background` set to

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

1784 `auto` instead.

1785 

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

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

1788 

1789 - `:transparent`

1790 

1791 - `:opaque`

1792 

1793 - `:auto`

1794 

1795 - `input_fidelity: :high | :low`

1796 

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

1798 

1799 - `:high`

1800 

1801 - `:low`

1802 

1803 - `input_image_mask: InputImageMask{ file_id, image_url}`

1804 

1805 Optional mask for inpainting. Contains `image_url`

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

1807 

1808 - `file_id: String`

1809 

1810 File ID for the mask image.

1811 

1812 - `image_url: String`

1813 

1814 Base64-encoded mask image.

1815 

1816 - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more`

1817 

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

1819 

1820 - `String = String`

1821 

1822 - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more`

1823 

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

1825 

1826 - `:"gpt-image-1"`

1827 

1828 - `:"gpt-image-1-mini"`

1829 

1830 - `:"gpt-image-2"`

1831 

1832 - `:"gpt-image-2-2026-04-21"`

1833 

1834 - `:"gpt-image-1.5"`

1835 

1836 - `:"chatgpt-image-latest"`

1837 

1838 - `moderation: :auto | :low`

1839 

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

1841 

1842 - `:auto`

1843 

1844 - `:low`

1845 

1846 - `output_compression: Integer`

1847 

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

1849 

1850 - `output_format: :png | :webp | :jpeg`

1851 

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

1853 `jpeg`. Default: `png`.

1854 

1855 - `:png`

1856 

1857 - `:webp`

1858 

1859 - `:jpeg`

1860 

1861 - `partial_images: Integer`

1862 

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

1864 

1865 - `quality: :low | :medium | :high | :auto`

1866 

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

1868 or `auto`. Default: `auto`.

1869 

1870 - `:low`

1871 

1872 - `:medium`

1873 

1874 - `:high`

1875 

1876 - `:auto`

1877 

1878 - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`

1879 

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

1881 

1882 - `String = String`

1883 

1884 - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`

1885 

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

1887 

1888 - `:"1024x1024"`

1889 

1890 - `:"1024x1536"`

1891 

1892 - `:"1536x1024"`

1893 

1894 - `:auto`

1895 

1896 - `class LocalShell`

1897 

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

1899 

1900 - `type: :local_shell`

1901 

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

1903 

1904 - `:local_shell`

1905 

1906 - `class FunctionShellTool`

1907 

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

1909 

1910 - `type: :shell`

1911 

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

1913 

1914 - `:shell`

1915 

1916 - `environment: ContainerAuto | LocalEnvironment | ContainerReference`

1917 

1918 - `class ContainerAuto`

1919 

1920 - `type: :container_auto`

1921 

1922 Automatically creates a container for this request

1923 

1924 - `:container_auto`

1925 

1926 - `file_ids: Array[String]`

1927 

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

1929 

1930 - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"`

1931 

1932 The memory limit for the container.

1933 

1934 - `:"1g"`

1935 

1936 - `:"4g"`

1937 

1938 - `:"16g"`

1939 

1940 - `:"64g"`

1941 

1942 - `network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist`

1943 

1944 Network access policy for the container.

1945 

1946 - `class ContainerNetworkPolicyDisabled`

1947 

1948 - `class ContainerNetworkPolicyAllowlist`

1949 

1950 - `skills: Array[SkillReference | InlineSkill]`

1951 

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

1953 

1954 - `class SkillReference`

1955 

1956 - `skill_id: String`

1957 

1958 The ID of the referenced skill.

1959 

1960 - `type: :skill_reference`

1961 

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

1963 

1964 - `:skill_reference`

1965 

1966 - `version: String`

1967 

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

1969 

1970 - `class InlineSkill`

1971 

1972 - `description: String`

1973 

1974 The description of the skill.

1975 

1976 - `name: String`

1977 

1978 The name of the skill.

1979 

1980 - `source: InlineSkillSource`

1981 

1982 Inline skill payload

1983 

1984 - `data: String`

1985 

1986 Base64-encoded skill zip bundle.

1987 

1988 - `media_type: :"application/zip"`

1989 

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

1991 

1992 - `:"application/zip"`

1993 

1994 - `type: :base64`

1995 

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