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

1## Get an eval run

2 

3**get** `/evals/{eval_id}/runs/{run_id}`

4 

5Get an evaluation run by ID.

6 

7### Path Parameters

8 

9- `eval_id: string`

10 

11- `run_id: string`

12 

13### Returns

14 

15- `id: string`

16 

17 Unique identifier for the evaluation run.

18 

19- `created_at: number`

20 

21 Unix timestamp (in seconds) when the evaluation run was created.

22 

23- `data_source: CreateEvalJSONLRunDataSource or CreateEvalCompletionsRunDataSource or object { source, type, input_messages, 2 more }`

24 

25 Information about the run's data source.

26 

27 - `CreateEvalJSONLRunDataSource object { source, type }`

28 

29 A JsonlRunDataSource object with that specifies a JSONL file that matches the eval

30 

31 - `source: object { content, type } or object { id, type }`

32 

33 Determines what populates the `item` namespace in the data source.

34 

35 - `EvalJSONLFileContentSource object { content, type }`

36 

37 - `content: array of object { item, sample }`

38 

39 The content of the jsonl file.

40 

41 - `item: map[unknown]`

42 

43 - `sample: optional map[unknown]`

44 

45 - `type: "file_content"`

46 

47 The type of jsonl source. Always `file_content`.

48 

49 - `"file_content"`

50 

51 - `EvalJSONLFileIDSource object { id, type }`

52 

53 - `id: string`

54 

55 The identifier of the file.

56 

57 - `type: "file_id"`

58 

59 The type of jsonl source. Always `file_id`.

60 

61 - `"file_id"`

62 

63 - `type: "jsonl"`

64 

65 The type of data source. Always `jsonl`.

66 

67 - `"jsonl"`

68 

69 - `CreateEvalCompletionsRunDataSource object { source, type, input_messages, 2 more }`

70 

71 A CompletionsRunDataSource object describing a model sampling configuration.

72 

73 - `source: object { content, type } or object { id, type } or object { type, created_after, created_before, 3 more }`

74 

75 Determines what populates the `item` namespace in this run's data source.

76 

77 - `EvalJSONLFileContentSource object { content, type }`

78 

79 - `content: array of object { item, sample }`

80 

81 The content of the jsonl file.

82 

83 - `item: map[unknown]`

84 

85 - `sample: optional map[unknown]`

86 

87 - `type: "file_content"`

88 

89 The type of jsonl source. Always `file_content`.

90 

91 - `"file_content"`

92 

93 - `EvalJSONLFileIDSource object { id, type }`

94 

95 - `id: string`

96 

97 The identifier of the file.

98 

99 - `type: "file_id"`

100 

101 The type of jsonl source. Always `file_id`.

102 

103 - `"file_id"`

104 

105 - `StoredCompletionsRunDataSource object { type, created_after, created_before, 3 more }`

106 

107 A StoredCompletionsRunDataSource configuration describing a set of filters

108 

109 - `type: "stored_completions"`

110 

111 The type of source. Always `stored_completions`.

112 

113 - `"stored_completions"`

114 

115 - `created_after: optional number or null`

116 

117 An optional Unix timestamp to filter items created after this time.

118 

119 - `created_before: optional number or null`

120 

121 An optional Unix timestamp to filter items created before this time.

122 

123 - `limit: optional number or null`

124 

125 An optional maximum number of items to return.

126 

127 - `metadata: optional Metadata or null`

128 

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

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

131 format, and querying for objects via API or the dashboard.

132 

133 Keys are strings with a maximum length of 64 characters. Values are strings

134 with a maximum length of 512 characters.

135 

136 - `model: optional string or null`

137 

138 An optional model to filter by (e.g., 'gpt-6-astra').

139 

140 - `type: "completions"`

141 

142 The type of run data source. Always `completions`.

143 

144 - `"completions"`

145 

146 - `input_messages: optional object { template, type } or object { item_reference, type }`

147 

148 Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace.

149 

150 - `TemplateInputMessages object { template, type }`

151 

152 - `template: array of EasyInputMessage or object { content, role, type }`

153 

154 A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}.

155 

156 - `EasyInputMessage object { content, role, phase, type }`

157 

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

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

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

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

162 interactions.

163 

164 - `content: string or ResponseInputMessageContentList`

165 

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

167 Can also contain previous assistant responses.

168 

169 - `TextInput = string`

170 

171 A text input to the model.

172 

173 - `ResponseInputMessageContentList = array of ResponseInputContent`

174 

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

176 types.

177 

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

179 

180 A text input to the model.

181 

182 - `text: string`

183 

184 The text input to the model.

185 

186 - `type: "input_text"`

187 

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

189 

190 - `"input_text"`

191 

192 - `prompt_cache_breakpoint: optional object { mode }`

193 

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

195 

196 - `mode: "explicit"`

197 

198 The breakpoint mode. Always `explicit`.

199 

200 - `"explicit"`

201 

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

203 

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

205 

206 - `detail: ImageDetail`

207 

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

209 

210 - `"low"`

211 

212 - `"high"`

213 

214 - `"auto"`

215 

216 - `"original"`

217 

218 - `type: "input_image"`

219 

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

221 

222 - `"input_image"`

223 

224 - `file_id: optional string or null`

225 

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

227 

228 - `image_url: optional string or null`

229 

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

231 

232 - `prompt_cache_breakpoint: optional object { mode }`

233 

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

235 

236 - `mode: "explicit"`

237 

238 The breakpoint mode. Always `explicit`.

239 

240 - `"explicit"`

241 

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

243 

244 A file input to the model.

245 

246 - `type: "input_file"`

247 

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

249 

250 - `"input_file"`

251 

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

253 

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

255 

256 - `"auto"`

257 

258 - `"low"`

259 

260 - `"high"`

261 

262 - `file_data: optional string`

263 

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

265 

266 - `file_id: optional string or null`

267 

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

269 

270 - `file_url: optional string`

271 

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

273 

274 - `filename: optional string`

275 

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

277 

278 - `prompt_cache_breakpoint: optional object { mode }`

279 

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

281 

282 - `mode: "explicit"`

283 

284 The breakpoint mode. Always `explicit`.

285 

286 - `"explicit"`

287 

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

289 

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

291 `developer`.

292 

293 - `"user"`

294 

295 - `"assistant"`

296 

297 - `"system"`

298 

299 - `"developer"`

300 

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

302 

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

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

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

306 

307 - `"commentary"`

308 

309 - `"final_answer"`

310 

311 - `type: optional "message"`

312 

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

314 

315 - `"message"`

316 

317 - `EvalMessageObject object { content, role, type }`

318 

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

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

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

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

323 interactions.

324 

325 - `content: string or ResponseInputText or object { text, type } or 3 more`

326 

327 Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items.

328 

329 - `TextInput = string`

330 

331 A text input to the model.

332 

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

334 

335 A text input to the model.

336 

337 - `OutputText object { text, type }`

338 

339 A text output from the model.

340 

341 - `text: string`

342 

343 The text output from the model.

344 

345 - `type: "output_text"`

346 

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

348 

349 - `"output_text"`

350 

351 - `InputImage object { image_url, type, detail }`

352 

353 An image input block used within EvalItem content arrays.

354 

355 - `image_url: string`

356 

357 The URL of the image input.

358 

359 - `type: "input_image"`

360 

361 The type of the image input. Always `input_image`.

362 

363 - `"input_image"`

364 

365 - `detail: optional string`

366 

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

368 

369 - `ResponseInputAudio object { input_audio, type }`

370 

371 An audio input to the model.

372 

373 - `input_audio: object { data, format }`

374 

375 - `data: string`

376 

377 Base64-encoded audio data.

378 

379 - `format: "mp3" or "wav"`

380 

381 The format of the audio data. Currently supported formats are `mp3` and

382 `wav`.

383 

384 - `"mp3"`

385 

386 - `"wav"`

387 

388 - `type: "input_audio"`

389 

390 The type of the input item. Always `input_audio`.

391 

392 - `"input_audio"`

393 

394 - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more`

395 

396 A list of inputs, each of which may be either an input text, output text, input

397 image, or input audio object.

398 

399 - `TextInput = string`

400 

401 A text input to the model.

402 

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

404 

405 A text input to the model.

406 

407 - `OutputText object { text, type }`

408 

409 A text output from the model.

410 

411 - `text: string`

412 

413 The text output from the model.

414 

415 - `type: "output_text"`

416 

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

418 

419 - `"output_text"`

420 

421 - `InputImage object { image_url, type, detail }`

422 

423 An image input block used within EvalItem content arrays.

424 

425 - `image_url: string`

426 

427 The URL of the image input.

428 

429 - `type: "input_image"`

430 

431 The type of the image input. Always `input_image`.

432 

433 - `"input_image"`

434 

435 - `detail: optional string`

436 

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

438 

439 - `ResponseInputAudio object { input_audio, type }`

440 

441 An audio input to the model.

442 

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

444 

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

446 `developer`.

447 

448 - `"user"`

449 

450 - `"assistant"`

451 

452 - `"system"`

453 

454 - `"developer"`

455 

456 - `type: optional "message"`

457 

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

459 

460 - `"message"`

461 

462 - `type: "template"`

463 

464 The type of input messages. Always `template`.

465 

466 - `"template"`

467 

468 - `ItemReferenceInputMessages object { item_reference, type }`

469 

470 - `item_reference: string`

471 

472 A reference to a variable in the `item` namespace. Ie, "item.input_trajectory"

473 

474 - `type: "item_reference"`

475 

476 The type of input messages. Always `item_reference`.

477 

478 - `"item_reference"`

479 

480 - `model: optional string`

481 

482 The name of the model to use for generating completions (e.g. "o3-mini").

483 

484 - `sampling_params: optional object { max_completion_tokens, reasoning_effort, response_format, 4 more }`

485 

486 - `max_completion_tokens: optional number`

487 

488 The maximum number of tokens in the generated output.

489 

490 - `reasoning_effort: optional ReasoningEffort or null`

491 

492 Constrains effort on reasoning for reasoning models. Currently supported

493 values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.

494 Reducing reasoning effort can result in faster responses and fewer tokens

495 used on reasoning in a response. Not all reasoning models support every

496 value. See the

497 [reasoning guide](/api/docs/guides/reasoning)

498 for model-specific support.

499 

500 - `"none"`

501 

502 - `"minimal"`

503 

504 - `"low"`

505 

506 - `"medium"`

507 

508 - `"high"`

509 

510 - `"xhigh"`

511 

512 - `"max"`

513 

514 - `response_format: optional ResponseFormatText or ResponseFormatJSONSchema or ResponseFormatJSONObject`

515 

516 An object specifying the format that the model must output.

517 

518 Setting to `{ "type": "json_schema", "json_schema": {...} }` enables

519 Structured Outputs which ensures the model will match your supplied JSON

520 schema. Learn more in the [Structured Outputs

521 guide](/api/docs/guides/structured-outputs).

522 

523 Setting to `{ "type": "json_object" }` enables the older JSON mode, which

524 ensures the message the model generates is valid JSON. Using `json_schema`

525 is preferred for models that support it.

526 

527 - `ResponseFormatText object { type }`

528 

529 Default response format. Used to generate text responses.

530 

531 - `type: "text"`

532 

533 The type of response format being defined. Always `text`.

534 

535 - `"text"`

536 

537 - `ResponseFormatJSONSchema object { json_schema, type }`

538 

539 JSON Schema response format. Used to generate structured JSON responses.

540 Learn more about [Structured Outputs](/api/docs/guides/structured-outputs).

541 

542 - `json_schema: object { name, description, schema, strict }`

543 

544 Structured Outputs configuration options, including a JSON Schema.

545 

546 - `name: string`

547 

548 The name of the response format. Must be a-z, A-Z, 0-9, or contain

549 underscores and dashes, with a maximum length of 64.

550 

551 - `description: optional string`

552 

553 A description of what the response format is for, used by the model to

554 determine how to respond in the format.

555 

556 - `schema: optional map[unknown]`

557 

558 The schema for the response format, described as a JSON Schema object.

559 Learn how to build JSON schemas [here](https://json-schema.org/).

560 

561 - `strict: optional boolean or null`

562 

563 Whether to enable strict schema adherence when generating the output.

564 If set to true, the model will always follow the exact schema defined

565 in the `schema` field. Only a subset of JSON Schema is supported when

566 `strict` is `true`. To learn more, read the [Structured Outputs

567 guide](/api/docs/guides/structured-outputs).

568 

569 - `type: "json_schema"`

570 

571 The type of response format being defined. Always `json_schema`.

572 

573 - `"json_schema"`

574 

575 - `ResponseFormatJSONObject object { type }`

576 

577 JSON object response format. An older method of generating JSON responses.

578 Using `json_schema` is recommended for models that support it. Note that the

579 model will not generate JSON without a system or user message instructing it

580 to do so.

581 

582 - `type: "json_object"`

583 

584 The type of response format being defined. Always `json_object`.

585 

586 - `"json_object"`

587 

588 - `seed: optional number`

589 

590 A seed value to initialize the randomness, during sampling.

591 

592 - `temperature: optional number`

593 

594 A higher temperature increases randomness in the outputs.

595 

596 - `tools: optional array of ChatCompletionFunctionTool`

597 

598 A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.

599 

600 - `function: FunctionDefinition`

601 

602 - `name: string`

603 

604 The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

605 

606 - `description: optional string`

607 

608 A description of what the function does, used by the model to choose when and how to call the function.

609 

610 - `parameters: optional FunctionParameters`

611 

612 The parameters the functions accepts, described as a JSON Schema object. See the [guide](/api/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.

613 

614 Omitting `parameters` defines a function with an empty parameter list.

615 

616 - `strict: optional boolean or null`

617 

618 Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/api/docs/guides/function-calling).

619 

620 - `type: "function"`

621 

622 The type of the tool. Currently, only `function` is supported.

623 

624 - `"function"`

625 

626 - `top_p: optional number`

627 

628 An alternative to temperature for nucleus sampling; 1.0 includes all tokens.

629 

630 - `ResponsesRunDataSource object { source, type, input_messages, 2 more }`

631 

632 A ResponsesRunDataSource object describing a model sampling configuration.

633 

634 - `source: object { content, type } or object { id, type } or object { type, created_after, created_before, 8 more }`

635 

636 Determines what populates the `item` namespace in this run's data source.

637 

638 - `EvalJSONLFileContentSource object { content, type }`

639 

640 - `content: array of object { item, sample }`

641 

642 The content of the jsonl file.

643 

644 - `item: map[unknown]`

645 

646 - `sample: optional map[unknown]`

647 

648 - `type: "file_content"`

649 

650 The type of jsonl source. Always `file_content`.

651 

652 - `"file_content"`

653 

654 - `EvalJSONLFileIDSource object { id, type }`

655 

656 - `id: string`

657 

658 The identifier of the file.

659 

660 - `type: "file_id"`

661 

662 The type of jsonl source. Always `file_id`.

663 

664 - `"file_id"`

665 

666 - `EvalResponsesSource object { type, created_after, created_before, 8 more }`

667 

668 A EvalResponsesSource object describing a run data source configuration.

669 

670 - `type: "responses"`

671 

672 The type of run data source. Always `responses`.

673 

674 - `"responses"`

675 

676 - `created_after: optional number or null`

677 

678 Only include items created after this timestamp (inclusive). This is a query parameter used to select responses.

679 

680 - `created_before: optional number or null`

681 

682 Only include items created before this timestamp (inclusive). This is a query parameter used to select responses.

683 

684 - `instructions_search: optional string or null`

685 

686 Optional string to search the 'instructions' field. This is a query parameter used to select responses.

687 

688 - `metadata: optional unknown or null`

689 

690 Metadata filter for the responses. This is a query parameter used to select responses.

691 

692 - `model: optional string or null`

693 

694 The name of the model to find responses for. This is a query parameter used to select responses.

695 

696 - `reasoning_effort: optional ReasoningEffort or null`

697 

698 Constrains effort on reasoning for reasoning models. Currently supported

699 values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.

700 Reducing reasoning effort can result in faster responses and fewer tokens

701 used on reasoning in a response. Not all reasoning models support every

702 value. See the

703 [reasoning guide](/api/docs/guides/reasoning)

704 for model-specific support.

705 

706 - `temperature: optional number or null`

707 

708 Sampling temperature. This is a query parameter used to select responses.

709 

710 - `tools: optional array of string or null`

711 

712 List of tool names. This is a query parameter used to select responses.

713 

714 - `top_p: optional number or null`

715 

716 Nucleus sampling parameter. This is a query parameter used to select responses.

717 

718 - `users: optional array of string or null`

719 

720 List of user identifiers. This is a query parameter used to select responses.

721 

722 - `type: "responses"`

723 

724 The type of run data source. Always `responses`.

725 

726 - `"responses"`

727 

728 - `input_messages: optional object { template, type } or object { item_reference, type }`

729 

730 Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace.

731 

732 - `InputMessagesTemplate object { template, type }`

733 

734 - `template: array of object { content, role } or object { content, role, type }`

735 

736 A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}.

737 

738 - `ChatMessage object { content, role }`

739 

740 - `content: string`

741 

742 The content of the message.

743 

744 - `role: string`

745 

746 The role of the message (e.g. "system", "assistant", "user").

747 

748 - `EvalMessageObject object { content, role, type }`

749 

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

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

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

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

754 interactions.

755 

756 - `content: string or ResponseInputText or object { text, type } or 3 more`

757 

758 Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items.

759 

760 - `TextInput = string`

761 

762 A text input to the model.

763 

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

765 

766 A text input to the model.

767 

768 - `OutputText object { text, type }`

769 

770 A text output from the model.

771 

772 - `text: string`

773 

774 The text output from the model.

775 

776 - `type: "output_text"`

777 

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

779 

780 - `"output_text"`

781 

782 - `InputImage object { image_url, type, detail }`

783 

784 An image input block used within EvalItem content arrays.

785 

786 - `image_url: string`

787 

788 The URL of the image input.

789 

790 - `type: "input_image"`

791 

792 The type of the image input. Always `input_image`.

793 

794 - `"input_image"`

795 

796 - `detail: optional string`

797 

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

799 

800 - `ResponseInputAudio object { input_audio, type }`

801 

802 An audio input to the model.

803 

804 - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more`

805 

806 A list of inputs, each of which may be either an input text, output text, input

807 image, or input audio object.

808 

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

810 

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

812 `developer`.

813 

814 - `"user"`

815 

816 - `"assistant"`

817 

818 - `"system"`

819 

820 - `"developer"`

821 

822 - `type: optional "message"`

823 

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

825 

826 - `"message"`

827 

828 - `type: "template"`

829 

830 The type of input messages. Always `template`.

831 

832 - `"template"`

833 

834 - `InputMessagesItemReference object { item_reference, type }`

835 

836 - `item_reference: string`

837 

838 A reference to a variable in the `item` namespace. Ie, "item.name"

839 

840 - `type: "item_reference"`

841 

842 The type of input messages. Always `item_reference`.

843 

844 - `"item_reference"`

845 

846 - `model: optional string`

847 

848 The name of the model to use for generating completions (e.g. "o3-mini").

849 

850 - `sampling_params: optional object { max_completion_tokens, reasoning_effort, seed, 4 more }`

851 

852 - `max_completion_tokens: optional number`

853 

854 The maximum number of tokens in the generated output.

855 

856 - `reasoning_effort: optional ReasoningEffort or null`

857 

858 Constrains effort on reasoning for reasoning models. Currently supported

859 values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.

860 Reducing reasoning effort can result in faster responses and fewer tokens

861 used on reasoning in a response. Not all reasoning models support every

862 value. See the

863 [reasoning guide](/api/docs/guides/reasoning)

864 for model-specific support.

865 

866 - `seed: optional number`

867 

868 A seed value to initialize the randomness, during sampling.

869 

870 - `temperature: optional number`

871 

872 A higher temperature increases randomness in the outputs.

873 

874 - `text: optional object { format }`

875 

876 Configuration options for a text response from the model. Can be plain

877 text or structured JSON data. Learn more:

878 

879 - [Text inputs and outputs](/api/docs/guides/text)

880 - [Structured Outputs](/api/docs/guides/structured-outputs)

881 

882 - `format: optional ResponseFormatTextConfig`

883 

884 An object specifying the format that the model must output.

885 

886 Configuring `{ "type": "json_schema" }` enables Structured Outputs,

887 which ensures the model will match your supplied JSON schema. Learn more in the

888 [Structured Outputs guide](/api/docs/guides/structured-outputs).

889 

890 The default format is `{ "type": "text" }` with no additional options.

891 

892 **Not recommended for gpt-4o and newer models:**

893 

894 Setting to `{ "type": "json_object" }` enables the older JSON mode, which

895 ensures the message the model generates is valid JSON. Using `json_schema`

896 is preferred for models that support it.

897 

898 - `ResponseFormatText object { type }`

899 

900 Default response format. Used to generate text responses.

901 

902 - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }`

903 

904 JSON Schema response format. Used to generate structured JSON responses.

905 Learn more about [Structured Outputs](/api/docs/guides/structured-outputs).

906 

907 - `name: string`

908 

909 The name of the response format. Must be a-z, A-Z, 0-9, or contain

910 underscores and dashes, with a maximum length of 64.

911 

912 - `schema: map[unknown]`

913 

914 The schema for the response format, described as a JSON Schema object.

915 Learn how to build JSON schemas [here](https://json-schema.org/).

916 

917 - `type: "json_schema"`

918 

919 The type of response format being defined. Always `json_schema`.

920 

921 - `"json_schema"`

922 

923 - `description: optional string`

924 

925 A description of what the response format is for, used by the model to

926 determine how to respond in the format.

927 

928 - `strict: optional boolean or null`

929 

930 Whether to enable strict schema adherence when generating the output.

931 If set to true, the model will always follow the exact schema defined

932 in the `schema` field. Only a subset of JSON Schema is supported when

933 `strict` is `true`. To learn more, read the [Structured Outputs

934 guide](/api/docs/guides/structured-outputs).

935 

936 - `ResponseFormatJSONObject object { type }`

937 

938 JSON object response format. An older method of generating JSON responses.

939 Using `json_schema` is recommended for models that support it. Note that the

940 model will not generate JSON without a system or user message instructing it

941 to do so.

942 

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

944 

945 An array of tools the model may call while generating a response. You

946 can specify which tool to use by setting the `tool_choice` parameter.

947 

948 The two categories of tools you can provide the model are:

949 

950 - **Built-in tools**: Tools that are provided by OpenAI that extend the

951 model's capabilities, like [web search](/api/docs/guides/tools-web-search)

952 or [file search](/api/docs/guides/tools-file-search). Learn more about

953 [built-in tools](/api/docs/guides/tools).

954 - **Function calls (custom tools)**: Functions that are defined by you,

955 enabling the model to call your own code. Learn more about

956 [function calling](/api/docs/guides/function-calling).

957 

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

959 

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

961 

962 - `name: string`

963 

964 The name of the function to call.

965 

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

967 

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

969 

970 - `strict: boolean or null`

971 

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

973 

974 - `type: "function"`

975 

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

977 

978 - `"function"`

979 

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

981 

982 The tool invocation context(s).

983 

984 - `"direct"`

985 

986 - `"programmatic"`

987 

988 - `async: optional boolean`

989 

990 - `defer_loading: optional boolean`

991 

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

993 

994 - `description: optional string or null`

995 

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

997 

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

999 

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

1001 

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

1003 

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

1005 

1006 - `type: "file_search"`

1007 

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

1009 

1010 - `"file_search"`

1011 

1012 - `vector_store_ids: array of string`

1013 

1014 The IDs of the vector stores to search.

1015 

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

1017 

1018 A filter to apply.

1019 

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

1021 

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

1023 

1024 - `key: string`

1025 

1026 The key to compare against the value.

1027 

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

1029 

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

1031 

1032 - `eq`: equals

1033 - `ne`: not equal

1034 - `gt`: greater than

1035 - `gte`: greater than or equal

1036 - `lt`: less than

1037 - `lte`: less than or equal

1038 - `in`: in

1039 - `nin`: not in

1040 

1041 - `"eq"`

1042 

1043 - `"ne"`

1044 

1045 - `"gt"`

1046 

1047 - `"gte"`

1048 

1049 - `"lt"`

1050 

1051 - `"lte"`

1052 

1053 - `"in"`

1054 

1055 - `"nin"`

1056 

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

1058 

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

1060 

1061 - `string`

1062 

1063 - `number`

1064 

1065 - `boolean`

1066 

1067 - `array of string or number`

1068 

1069 - `string`

1070 

1071 - `number`

1072 

1073 - `CompoundFilter object { filters, type }`

1074 

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

1076 

1077 - `filters: array of ComparisonFilter or unknown`

1078 

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

1080 

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

1082 

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

1084 

1085 - `unknown`

1086 

1087 - `type: "and" or "or"`

1088 

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

1090 

1091 - `"and"`

1092 

1093 - `"or"`

1094 

1095 - `max_num_results: optional number`

1096 

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

1098 

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

1100 

1101 Ranking options for search.

1102 

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

1104 

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

1106 

1107 - `embedding_weight: number`

1108 

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

1110 

1111 - `text_weight: number`

1112 

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

1114 

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

1116 

1117 The ranker to use for the file search.

1118 

1119 - `"auto"`

1120 

1121 - `"default-2024-11-15"`

1122 

1123 - `score_threshold: optional number`

1124 

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

1126 

1127 - `Computer object { type }`

1128 

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

1130 

1131 - `type: "computer"`

1132 

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

1134 

1135 - `"computer"`

1136 

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

1138 

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

1140 

1141 - `display_height: number`

1142 

1143 The height of the computer display.

1144 

1145 - `display_width: number`

1146 

1147 The width of the computer display.

1148 

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

1150 

1151 The type of computer environment to control.

1152 

1153 - `"windows"`

1154 

1155 - `"mac"`

1156 

1157 - `"linux"`

1158 

1159 - `"ubuntu"`

1160 

1161 - `"browser"`

1162 

1163 - `type: "computer_use_preview"`

1164 

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

1166 

1167 - `"computer_use_preview"`

1168 

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

1170 

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

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

1173 

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

1175 

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

1177 

1178 - `"web_search"`

1179 

1180 - `"web_search_2025_08_26"`

1181 

1182 - `external_web_access: optional boolean`

1183 

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

1185 

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

1187 

1188 Filters for the search.

1189 

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

1191 

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

1193 Subdomains of the provided domains are allowed as well.

1194 

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

1196 

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

1198 

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

1200 

1201 - `"low"`

1202 

1203 - `"medium"`

1204 

1205 - `"high"`

1206 

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

1208 

1209 The approximate location of the user.

1210 

1211 - `city: optional string or null`

1212 

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

1214 

1215 - `country: optional string or null`

1216 

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

1218 

1219 - `region: optional string or null`

1220 

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

1222 

1223 - `timezone: optional string or null`

1224 

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

1226 

1227 - `type: optional "approximate"`

1228 

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

1230 

1231 - `"approximate"`

1232 

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

1234 

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

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

1237 

1238 - `server_label: string`

1239 

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

1241 

1242 - `type: "mcp"`

1243 

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

1245 

1246 - `"mcp"`

1247 

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

1249 

1250 The tool invocation context(s).

1251 

1252 - `"direct"`

1253 

1254 - `"programmatic"`

1255 

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

1257 

1258 List of allowed tool names or a filter object.

1259 

1260 - `McpAllowedTools = array of string`

1261 

1262 A string array of allowed tool names

1263 

1264 - `McpToolFilter object { read_only, tool_names }`

1265 

1266 A filter object to specify which tools are allowed.

1267 

1268 - `read_only: optional boolean`

1269 

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

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

1272 it will match this filter.

1273 

1274 - `tool_names: optional array of string`

1275 

1276 List of allowed tool names.

1277 

1278 - `authorization: optional string`

1279 

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

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

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

1283 

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

1285 

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

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

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

1289 

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

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

1292 connect through a Secure MCP Tunnel.

1293 

1294 Currently supported `connector_id` values are:

1295 

1296 - Dropbox: `connector_dropbox`

1297 - Gmail: `connector_gmail`

1298 - Google Calendar: `connector_googlecalendar`

1299 - Google Drive: `connector_googledrive`

1300 - Microsoft Teams: `connector_microsoftteams`

1301 - Outlook Calendar: `connector_outlookcalendar`

1302 - Outlook Email: `connector_outlookemail`

1303 - SharePoint: `connector_sharepoint`

1304 

1305 - `"connector_dropbox"`

1306 

1307 - `"connector_gmail"`

1308 

1309 - `"connector_googlecalendar"`

1310 

1311 - `"connector_googledrive"`

1312 

1313 - `"connector_microsoftteams"`

1314 

1315 - `"connector_outlookcalendar"`

1316 

1317 - `"connector_outlookemail"`

1318 

1319 - `"connector_sharepoint"`

1320 

1321 - `defer_loading: optional boolean`

1322 

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

1324 

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

1326 

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

1328 or other purposes.

1329 

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

1331 

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

1333 

1334 - `McpToolApprovalFilter object { always, never }`

1335 

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

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

1338 that require approval.

1339 

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

1341 

1342 A filter object to specify which tools are allowed.

1343 

1344 - `read_only: optional boolean`

1345 

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

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

1348 it will match this filter.

1349 

1350 - `tool_names: optional array of string`

1351 

1352 List of allowed tool names.

1353 

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

1355 

1356 A filter object to specify which tools are allowed.

1357 

1358 - `read_only: optional boolean`

1359 

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

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

1362 it will match this filter.

1363 

1364 - `tool_names: optional array of string`

1365 

1366 List of allowed tool names.

1367 

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

1369 

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

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

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

1373 

1374 - `"always"`

1375 

1376 - `"never"`

1377 

1378 - `server_description: optional string`

1379 

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

1381 

1382 - `server_url: optional string`

1383 

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

1385 `tunnel_id` must be provided.

1386 

1387 - `tunnel_id: optional string`

1388 

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

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

1391 

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

1393 

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

1395 

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

1397 

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

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

1400 optional `memory_limit` setting.

1401 

1402 - `string`

1403 

1404 The container ID.

1405 

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

1407 

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

1409 

1410 - `type: "auto"`

1411 

1412 Always `auto`.

1413 

1414 - `"auto"`

1415 

1416 - `file_ids: optional array of string`

1417 

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

1419 

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

1421 

1422 The memory limit for the code interpreter container.

1423 

1424 - `"1g"`

1425 

1426 - `"4g"`

1427 

1428 - `"16g"`

1429 

1430 - `"64g"`

1431 

1432 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1433 

1434 Network access policy for the container.

1435 

1436 - `ContainerNetworkPolicyDisabled object { type }`

1437 

1438 - `type: "disabled"`

1439 

1440 Disable outbound network access. Always `disabled`.

1441 

1442 - `"disabled"`

1443 

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

1445 

1446 - `allowed_domains: array of string`

1447 

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

1449 

1450 - `type: "allowlist"`

1451 

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

1453 

1454 - `"allowlist"`

1455 

1456 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1457 

1458 Optional domain-scoped secrets for allowlisted domains.

1459 

1460 - `domain: string`

1461 

1462 The domain associated with the secret.

1463 

1464 - `name: string`

1465 

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

1467 

1468 - `value: string`

1469 

1470 The secret value to inject for the domain.

1471 

1472 - `type: "code_interpreter"`

1473 

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

1475 

1476 - `"code_interpreter"`

1477 

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

1479 

1480 The tool invocation context(s).

1481 

1482 - `"direct"`

1483 

1484 - `"programmatic"`

1485 

1486 - `ProgrammaticToolCalling object { type }`

1487 

1488 - `type: "programmatic_tool_calling"`

1489 

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

1491 

1492 - `"programmatic_tool_calling"`

1493 

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

1495 

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

1497 

1498 - `type: "image_generation"`

1499 

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

1501 

1502 - `"image_generation"`

1503 

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

1505 

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

1507 

1508 - `"generate"`

1509 

1510 - `"edit"`

1511 

1512 - `"auto"`

1513 

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

1515 

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

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

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

1519 backgrounds. Transparent backgrounds are available for supported GPT Image

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

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

1522 Default: `auto`.

1523 

1524 - `"transparent"`

1525 

1526 - `"opaque"`

1527 

1528 - `"auto"`

1529 

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

1531 

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

1533 

1534 - `"high"`

1535 

1536 - `"low"`

1537 

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

1539 

1540 Optional mask for inpainting. Contains `image_url`

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

1542 

1543 - `file_id: optional string`

1544 

1545 File ID for the mask image.

1546 

1547 - `image_url: optional string`

1548 

1549 Base64-encoded mask image.

1550 

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

1552 

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

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

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

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

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

1558 `gpt-image-1`.

1559 

1560 - `string`

1561 

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

1563 

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

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

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

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

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

1569 `gpt-image-1`.

1570 

1571 - `"gpt-image-1"`

1572 

1573 - `"gpt-image-1-mini"`

1574 

1575 - `"gpt-image-1.5"`

1576 

1577 - `"gpt-image-2"`

1578 

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

1580 

1581 - `"gpt-image-2.5-sunburst"`

1582 

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

1584 

1585 - `"gpt-image-2.5-flare"`

1586 

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

1588 

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

1590 

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

1592 

1593 - `"auto"`

1594 

1595 - `"low"`

1596 

1597 - `output_compression: optional number`

1598 

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

1600 

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

1602 

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

1604 `jpeg`. Default: `png`.

1605 

1606 - `"png"`

1607 

1608 - `"webp"`

1609 

1610 - `"jpeg"`

1611 

1612 - `partial_images: optional number`

1613 

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

1615 

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

1617 

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

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

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

1621 Default: `auto`.

1622 

1623 - `"low"`

1624 

1625 - `"medium"`

1626 

1627 - `"high"`

1628 

1629 - `"xhigh"`

1630 

1631 - `"max"`

1632 

1633 - `"auto"`

1634 

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

1636 

1637 The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1638 

1639 - `string`

1640 

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

1642 

1643 The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1644 

1645 - `"1024x1024"`

1646 

1647 - `"1024x1536"`

1648 

1649 - `"1536x1024"`

1650 

1651 - `"auto"`

1652 

1653 - `LocalShell object { type }`

1654 

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

1656 

1657 - `type: "local_shell"`

1658 

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

1660 

1661 - `"local_shell"`

1662 

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

1664 

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

1666 

1667 - `type: "shell"`

1668 

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

1670 

1671 - `"shell"`

1672 

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

1674 

1675 The tool invocation context(s).

1676 

1677 - `"direct"`

1678 

1679 - `"programmatic"`

1680 

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

1682 

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

1684 

1685 - `type: "container_auto"`

1686 

1687 Automatically creates a container for this request

1688 

1689 - `"container_auto"`

1690 

1691 - `file_ids: optional array of string`

1692 

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

1694 

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

1696 

1697 The memory limit for the container.

1698 

1699 - `"1g"`

1700 

1701 - `"4g"`

1702 

1703 - `"16g"`

1704 

1705 - `"64g"`

1706 

1707 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1708 

1709 Network access policy for the container.

1710 

1711 - `ContainerNetworkPolicyDisabled object { type }`

1712 

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

1714 

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

1716 

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

1718 

1719 - `SkillReference object { skill_id, type, version }`

1720 

1721 - `skill_id: string`

1722 

1723 The ID of the referenced skill.

1724 

1725 - `type: "skill_reference"`

1726 

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

1728 

1729 - `"skill_reference"`

1730 

1731 - `version: optional string`

1732 

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

1734 

1735 - `InlineSkill object { description, name, source, type }`

1736 

1737 - `description: string`

1738 

1739 The description of the skill.

1740 

1741 - `name: string`

1742 

1743 The name of the skill.

1744 

1745 - `source: InlineSkillSource`

1746 

1747 Inline skill payload

1748 

1749 - `data: string`

1750 

1751 Base64-encoded skill zip bundle.

1752 

1753 - `media_type: "application/zip"`

1754 

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

1756 

1757 - `"application/zip"`

1758 

1759 - `type: "base64"`

1760 

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

1762 

1763 - `"base64"`

1764 

1765 - `type: "inline"`

1766 

1767 Defines an inline skill for this request.

1768 

1769 - `"inline"`

1770 

1771 - `LocalEnvironment object { type, skills }`

1772 

1773 - `type: "local"`

1774 

1775 Use a local computer environment.

1776 

1777 - `"local"`

1778 

1779 - `skills: optional array of LocalSkill`

1780 

1781 An optional list of skills.

1782 

1783 - `description: string`

1784 

1785 The description of the skill.

1786 

1787 - `name: string`

1788 

1789 The name of the skill.

1790 

1791 - `path: string`

1792 

1793 The path to the directory containing the skill.

1794 

1795 - `ContainerReference object { container_id, type }`

1796 

1797 - `container_id: string`

1798 

1799 The ID of the referenced container.

1800 

1801 - `type: "container_reference"`

1802 

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

1804 

1805 - `"container_reference"`

1806 

1807 - `Custom object { name, type, allowed_callers, 4 more }`

1808 

1809 A custom tool that processes input using a specified format. Learn more about [custom tools](/api/docs/guides/function-calling#custom-tools)

1810 

1811 - `name: string`

1812 

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

1814 

1815 - `type: "custom"`

1816 

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

1818 

1819 - `"custom"`

1820 

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

1822 

1823 The tool invocation context(s).

1824 

1825 - `"direct"`

1826 

1827 - `"programmatic"`

1828 

1829 - `async: optional boolean`

1830 

1831 Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

1832 

1833 - `defer_loading: optional boolean`

1834 

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

1836 

1837 - `description: optional string`

1838 

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

1840 

1841 - `format: optional CustomToolInputFormat`

1842 

1843 The input format for the custom tool. Default is unconstrained text.

1844 

1845 - `Text object { type }`

1846 

1847 Unconstrained free-form text.

1848 

1849 - `type: "text"`

1850 

1851 Unconstrained text format. Always `text`.

1852 

1853 - `"text"`

1854 

1855 - `Grammar object { definition, syntax, type }`

1856 

1857 A grammar defined by the user.

1858 

1859 - `definition: string`

1860 

1861 The grammar definition.

1862 

1863 - `syntax: "lark" or "regex"`

1864 

1865 The syntax of the grammar definition. One of `lark` or `regex`.

1866 

1867 - `"lark"`

1868 

1869 - `"regex"`

1870 

1871 - `type: "grammar"`

1872 

1873 Grammar format. Always `grammar`.

1874 

1875 - `"grammar"`

1876 

1877 - `Namespace object { description, name, tools, type }`

1878 

1879 Groups function/custom tools under a shared namespace.

1880 

1881 - `description: string`

1882 

1883 A description of the namespace shown to the model.

1884 

1885 - `name: string`

1886 

1887 The namespace name used in tool calls (for example, `crm`).

1888 

1889 - `tools: array of object { name, type, allowed_callers, 6 more } or object { name, type, allowed_callers, 4 more }`

1890 

1891 The function/custom tools available inside this namespace.

1892 

1893 - `Function object { name, type, allowed_callers, 6 more }`

1894 

1895 - `name: string`

1896 

1897 - `type: "function"`

1898 

1899 - `"function"`

1900 

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

1902 

1903 The tool invocation context(s).

1904 

1905 - `"direct"`

1906 

1907 - `"programmatic"`

1908 

1909 - `async: optional boolean`

1910 

1911 Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

1912 

1913 - `defer_loading: optional boolean`

1914 

1915 Whether this function should be deferred and discovered via tool search.

1916 

1917 - `description: optional string or null`

1918 

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

1920 

1921 A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs.

1922 

1923 - `parameters: optional unknown or null`

1924 

1925 - `strict: optional boolean or null`

1926 

1927 Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise.

1928 

1929 - `Custom object { name, type, allowed_callers, 4 more }`

1930 

1931 A custom tool that processes input using a specified format. Learn more about [custom tools](/api/docs/guides/function-calling#custom-tools)

1932 

1933 - `name: string`

1934 

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

1936 

1937 - `type: "custom"`

1938 

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

1940 

1941 - `"custom"`

1942 

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

1944 

1945 The tool invocation context(s).

1946 

1947 - `"direct"`

1948 

1949 - `"programmatic"`

1950 

1951 - `async: optional boolean`

1952 

1953 Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

1954 

1955 - `defer_loading: optional boolean`

1956 

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

1958 

1959 - `description: optional string`

1960 

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

1962 

1963 - `format: optional CustomToolInputFormat`

1964 

1965 The input format for the custom tool. Default is unconstrained text.

1966 

1967 - `type: "namespace"`

1968 

1969 The type of the tool. Always `namespace`.

1970 

1971 - `"namespace"`

1972 

1973 - `ToolSearch object { type, description, execution, parameters }`

1974 

1975 Hosted or BYOT tool search configuration for deferred tools.

1976 

1977 - `type: "tool_search"`

1978 

1979 The type of the tool. Always `tool_search`.

1980 

1981 - `"tool_search"`

1982 

1983 - `description: optional string or null`

1984 

1985 Description shown to the model for a client-executed tool search tool.

1986 

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

1988 

1989 Whether tool search is executed by the server or by the client.

1990 

1991 - `"server"`

1992 

1993 - `"client"`

1994 

1995 - `parameters: optional unknown or null`

1996