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

1## Create eval run

2 

3**post** `/evals/{eval_id}/runs`

4 

5Kicks off a new run for a given evaluation, specifying the data source, and what model configuration to use to test. The datasource will be validated against the schema specified in the config of the evaluation.

6 

7### Path Parameters

8 

9- `eval_id: string`

10 

11### Body Parameters

12 

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

14 

15 Details about the run's data source.

16 

17 - `CreateEvalJSONLRunDataSource object { source, type }`

18 

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

20 

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

22 

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

24 

25 - `EvalJSONLFileContentSource object { content, type }`

26 

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

28 

29 The content of the jsonl file.

30 

31 - `item: map[unknown]`

32 

33 - `sample: optional map[unknown]`

34 

35 - `type: "file_content"`

36 

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

38 

39 - `"file_content"`

40 

41 - `EvalJSONLFileIDSource object { id, type }`

42 

43 - `id: string`

44 

45 The identifier of the file.

46 

47 - `type: "file_id"`

48 

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

50 

51 - `"file_id"`

52 

53 - `type: "jsonl"`

54 

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

56 

57 - `"jsonl"`

58 

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

60 

61 A CompletionsRunDataSource object describing a model sampling configuration.

62 

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

64 

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

66 

67 - `EvalJSONLFileContentSource object { content, type }`

68 

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

70 

71 The content of the jsonl file.

72 

73 - `item: map[unknown]`

74 

75 - `sample: optional map[unknown]`

76 

77 - `type: "file_content"`

78 

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

80 

81 - `"file_content"`

82 

83 - `EvalJSONLFileIDSource object { id, type }`

84 

85 - `id: string`

86 

87 The identifier of the file.

88 

89 - `type: "file_id"`

90 

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

92 

93 - `"file_id"`

94 

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

96 

97 A StoredCompletionsRunDataSource configuration describing a set of filters

98 

99 - `type: "stored_completions"`

100 

101 The type of source. Always `stored_completions`.

102 

103 - `"stored_completions"`

104 

105 - `created_after: optional number or null`

106 

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

108 

109 - `created_before: optional number or null`

110 

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

112 

113 - `limit: optional number or null`

114 

115 An optional maximum number of items to return.

116 

117 - `metadata: optional Metadata or null`

118 

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

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

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

122 

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

124 with a maximum length of 512 characters.

125 

126 - `model: optional string or null`

127 

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

129 

130 - `type: "completions"`

131 

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

133 

134 - `"completions"`

135 

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

137 

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

139 

140 - `TemplateInputMessages object { template, type }`

141 

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

143 

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

145 

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

147 

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

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

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

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

152 interactions.

153 

154 - `content: string or ResponseInputMessageContentList`

155 

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

157 Can also contain previous assistant responses.

158 

159 - `TextInput = string`

160 

161 A text input to the model.

162 

163 - `ResponseInputMessageContentList = array of ResponseInputContent`

164 

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

166 types.

167 

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

169 

170 A text input to the model.

171 

172 - `text: string`

173 

174 The text input to the model.

175 

176 - `type: "input_text"`

177 

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

179 

180 - `"input_text"`

181 

182 - `prompt_cache_breakpoint: optional object { mode }`

183 

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

185 

186 - `mode: "explicit"`

187 

188 The breakpoint mode. Always `explicit`.

189 

190 - `"explicit"`

191 

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

193 

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

195 

196 - `detail: ImageDetail`

197 

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

199 

200 - `"low"`

201 

202 - `"high"`

203 

204 - `"auto"`

205 

206 - `"original"`

207 

208 - `type: "input_image"`

209 

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

211 

212 - `"input_image"`

213 

214 - `file_id: optional string or null`

215 

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

217 

218 - `image_url: optional string or null`

219 

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

221 

222 - `prompt_cache_breakpoint: optional object { mode }`

223 

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

225 

226 - `mode: "explicit"`

227 

228 The breakpoint mode. Always `explicit`.

229 

230 - `"explicit"`

231 

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

233 

234 A file input to the model.

235 

236 - `type: "input_file"`

237 

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

239 

240 - `"input_file"`

241 

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

243 

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

245 

246 - `"auto"`

247 

248 - `"low"`

249 

250 - `"high"`

251 

252 - `file_data: optional string`

253 

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

255 

256 - `file_id: optional string or null`

257 

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

259 

260 - `file_url: optional string`

261 

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

263 

264 - `filename: optional string`

265 

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

267 

268 - `prompt_cache_breakpoint: optional object { mode }`

269 

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

271 

272 - `mode: "explicit"`

273 

274 The breakpoint mode. Always `explicit`.

275 

276 - `"explicit"`

277 

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

279 

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

281 `developer`.

282 

283 - `"user"`

284 

285 - `"assistant"`

286 

287 - `"system"`

288 

289 - `"developer"`

290 

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

292 

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

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

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

296 

297 - `"commentary"`

298 

299 - `"final_answer"`

300 

301 - `type: optional "message"`

302 

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

304 

305 - `"message"`

306 

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

308 

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

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

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

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

313 interactions.

314 

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

316 

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

318 

319 - `TextInput = string`

320 

321 A text input to the model.

322 

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

324 

325 A text input to the model.

326 

327 - `OutputText object { text, type }`

328 

329 A text output from the model.

330 

331 - `text: string`

332 

333 The text output from the model.

334 

335 - `type: "output_text"`

336 

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

338 

339 - `"output_text"`

340 

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

342 

343 An image input block used within EvalItem content arrays.

344 

345 - `image_url: string`

346 

347 The URL of the image input.

348 

349 - `type: "input_image"`

350 

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

352 

353 - `"input_image"`

354 

355 - `detail: optional string`

356 

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

358 

359 - `ResponseInputAudio object { input_audio, type }`

360 

361 An audio input to the model.

362 

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

364 

365 - `data: string`

366 

367 Base64-encoded audio data.

368 

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

370 

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

372 `wav`.

373 

374 - `"mp3"`

375 

376 - `"wav"`

377 

378 - `type: "input_audio"`

379 

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

381 

382 - `"input_audio"`

383 

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

385 

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

387 image, or input audio object.

388 

389 - `TextInput = string`

390 

391 A text input to the model.

392 

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

394 

395 A text input to the model.

396 

397 - `OutputText object { text, type }`

398 

399 A text output from the model.

400 

401 - `text: string`

402 

403 The text output from the model.

404 

405 - `type: "output_text"`

406 

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

408 

409 - `"output_text"`

410 

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

412 

413 An image input block used within EvalItem content arrays.

414 

415 - `image_url: string`

416 

417 The URL of the image input.

418 

419 - `type: "input_image"`

420 

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

422 

423 - `"input_image"`

424 

425 - `detail: optional string`

426 

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

428 

429 - `ResponseInputAudio object { input_audio, type }`

430 

431 An audio input to the model.

432 

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

434 

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

436 `developer`.

437 

438 - `"user"`

439 

440 - `"assistant"`

441 

442 - `"system"`

443 

444 - `"developer"`

445 

446 - `type: optional "message"`

447 

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

449 

450 - `"message"`

451 

452 - `type: "template"`

453 

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

455 

456 - `"template"`

457 

458 - `ItemReferenceInputMessages object { item_reference, type }`

459 

460 - `item_reference: string`

461 

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

463 

464 - `type: "item_reference"`

465 

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

467 

468 - `"item_reference"`

469 

470 - `model: optional string`

471 

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

473 

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

475 

476 - `max_completion_tokens: optional number`

477 

478 The maximum number of tokens in the generated output.

479 

480 - `reasoning_effort: optional ReasoningEffort or null`

481 

482 Constrains effort on reasoning for reasoning models. Currently supported

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

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

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

486 value. See the

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

488 for model-specific support.

489 

490 - `"none"`

491 

492 - `"minimal"`

493 

494 - `"low"`

495 

496 - `"medium"`

497 

498 - `"high"`

499 

500 - `"xhigh"`

501 

502 - `"max"`

503 

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

505 

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

507 

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

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

510 schema. Learn more in the [Structured Outputs

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

512 

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

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

515 is preferred for models that support it.

516 

517 - `ResponseFormatText object { type }`

518 

519 Default response format. Used to generate text responses.

520 

521 - `type: "text"`

522 

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

524 

525 - `"text"`

526 

527 - `ResponseFormatJSONSchema object { json_schema, type }`

528 

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

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

531 

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

533 

534 Structured Outputs configuration options, including a JSON Schema.

535 

536 - `name: string`

537 

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

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

540 

541 - `description: optional string`

542 

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

544 determine how to respond in the format.

545 

546 - `schema: optional map[unknown]`

547 

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

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

550 

551 - `strict: optional boolean or null`

552 

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

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

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

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

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

558 

559 - `type: "json_schema"`

560 

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

562 

563 - `"json_schema"`

564 

565 - `ResponseFormatJSONObject object { type }`

566 

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

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

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

570 to do so.

571 

572 - `type: "json_object"`

573 

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

575 

576 - `"json_object"`

577 

578 - `seed: optional number`

579 

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

581 

582 - `temperature: optional number`

583 

584 A higher temperature increases randomness in the outputs.

585 

586 - `tools: optional array of ChatCompletionFunctionTool`

587 

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

589 

590 - `function: FunctionDefinition`

591 

592 - `name: string`

593 

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

595 

596 - `description: optional string`

597 

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

599 

600 - `parameters: optional FunctionParameters`

601 

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

603 

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

605 

606 - `strict: optional boolean or null`

607 

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

609 

610 - `type: "function"`

611 

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

613 

614 - `"function"`

615 

616 - `top_p: optional number`

617 

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

619 

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

621 

622 A ResponsesRunDataSource object describing a model sampling configuration.

623 

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

625 

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

627 

628 - `EvalJSONLFileContentSource object { content, type }`

629 

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

631 

632 The content of the jsonl file.

633 

634 - `item: map[unknown]`

635 

636 - `sample: optional map[unknown]`

637 

638 - `type: "file_content"`

639 

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

641 

642 - `"file_content"`

643 

644 - `EvalJSONLFileIDSource object { id, type }`

645 

646 - `id: string`

647 

648 The identifier of the file.

649 

650 - `type: "file_id"`

651 

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

653 

654 - `"file_id"`

655 

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

657 

658 A EvalResponsesSource object describing a run data source configuration.

659 

660 - `type: "responses"`

661 

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

663 

664 - `"responses"`

665 

666 - `created_after: optional number or null`

667 

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

669 

670 - `created_before: optional number or null`

671 

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

673 

674 - `instructions_search: optional string or null`

675 

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

677 

678 - `metadata: optional unknown or null`

679 

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

681 

682 - `model: optional string or null`

683 

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

685 

686 - `reasoning_effort: optional ReasoningEffort or null`

687 

688 Constrains effort on reasoning for reasoning models. Currently supported

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

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

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

692 value. See the

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

694 for model-specific support.

695 

696 - `temperature: optional number or null`

697 

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

699 

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

701 

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

703 

704 - `top_p: optional number or null`

705 

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

707 

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

709 

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

711 

712 - `type: "responses"`

713 

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

715 

716 - `"responses"`

717 

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

719 

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

721 

722 - `InputMessagesTemplate object { template, type }`

723 

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

725 

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

727 

728 - `ChatMessage object { content, role }`

729 

730 - `content: string`

731 

732 The content of the message.

733 

734 - `role: string`

735 

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

737 

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

739 

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

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

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

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

744 interactions.

745 

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

747 

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

749 

750 - `TextInput = string`

751 

752 A text input to the model.

753 

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

755 

756 A text input to the model.

757 

758 - `OutputText object { text, type }`

759 

760 A text output from the model.

761 

762 - `text: string`

763 

764 The text output from the model.

765 

766 - `type: "output_text"`

767 

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

769 

770 - `"output_text"`

771 

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

773 

774 An image input block used within EvalItem content arrays.

775 

776 - `image_url: string`

777 

778 The URL of the image input.

779 

780 - `type: "input_image"`

781 

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

783 

784 - `"input_image"`

785 

786 - `detail: optional string`

787 

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

789 

790 - `ResponseInputAudio object { input_audio, type }`

791 

792 An audio input to the model.

793 

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

795 

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

797 image, or input audio object.

798 

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

800 

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

802 `developer`.

803 

804 - `"user"`

805 

806 - `"assistant"`

807 

808 - `"system"`

809 

810 - `"developer"`

811 

812 - `type: optional "message"`

813 

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

815 

816 - `"message"`

817 

818 - `type: "template"`

819 

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

821 

822 - `"template"`

823 

824 - `InputMessagesItemReference object { item_reference, type }`

825 

826 - `item_reference: string`

827 

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

829 

830 - `type: "item_reference"`

831 

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

833 

834 - `"item_reference"`

835 

836 - `model: optional string`

837 

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

839 

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

841 

842 - `max_completion_tokens: optional number`

843 

844 The maximum number of tokens in the generated output.

845 

846 - `reasoning_effort: optional ReasoningEffort or null`

847 

848 Constrains effort on reasoning for reasoning models. Currently supported

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

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

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

852 value. See the

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

854 for model-specific support.

855 

856 - `seed: optional number`

857 

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

859 

860 - `temperature: optional number`

861 

862 A higher temperature increases randomness in the outputs.

863 

864 - `text: optional object { format }`

865 

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

867 text or structured JSON data. Learn more:

868 

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

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

871 

872 - `format: optional ResponseFormatTextConfig`

873 

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

875 

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

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

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

879 

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

881 

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

883 

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

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

886 is preferred for models that support it.

887 

888 - `ResponseFormatText object { type }`

889 

890 Default response format. Used to generate text responses.

891 

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

893 

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

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

896 

897 - `name: string`

898 

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

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

901 

902 - `schema: map[unknown]`

903 

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

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

906 

907 - `type: "json_schema"`

908 

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

910 

911 - `"json_schema"`

912 

913 - `description: optional string`

914 

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

916 determine how to respond in the format.

917 

918 - `strict: optional boolean or null`

919 

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

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

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

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

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

925 

926 - `ResponseFormatJSONObject object { type }`

927 

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

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

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

931 to do so.

932 

933 - `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`

934 

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

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

937 

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

939 

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

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

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

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

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

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

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

947 

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

949 

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

951 

952 - `name: string`

953 

954 The name of the function to call.

955 

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

957 

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

959 

960 - `strict: boolean or null`

961 

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

963 

964 - `type: "function"`

965 

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

967 

968 - `"function"`

969 

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

971 

972 The tool invocation context(s).

973 

974 - `"direct"`

975 

976 - `"programmatic"`

977 

978 - `async: optional boolean`

979 

980 - `defer_loading: optional boolean`

981 

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

983 

984 - `description: optional string or null`

985 

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

987 

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

989 

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

991 

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

993 

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

995 

996 - `type: "file_search"`

997 

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

999 

1000 - `"file_search"`

1001 

1002 - `vector_store_ids: array of string`

1003 

1004 The IDs of the vector stores to search.

1005 

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

1007 

1008 A filter to apply.

1009 

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

1011 

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

1013 

1014 - `key: string`

1015 

1016 The key to compare against the value.

1017 

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

1019 

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

1021 

1022 - `eq`: equals

1023 - `ne`: not equal

1024 - `gt`: greater than

1025 - `gte`: greater than or equal

1026 - `lt`: less than

1027 - `lte`: less than or equal

1028 - `in`: in

1029 - `nin`: not in

1030 

1031 - `"eq"`

1032 

1033 - `"ne"`

1034 

1035 - `"gt"`

1036 

1037 - `"gte"`

1038 

1039 - `"lt"`

1040 

1041 - `"lte"`

1042 

1043 - `"in"`

1044 

1045 - `"nin"`

1046 

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

1048 

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

1050 

1051 - `string`

1052 

1053 - `number`

1054 

1055 - `boolean`

1056 

1057 - `array of string or number`

1058 

1059 - `string`

1060 

1061 - `number`

1062 

1063 - `CompoundFilter object { filters, type }`

1064 

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

1066 

1067 - `filters: array of ComparisonFilter or unknown`

1068 

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

1070 

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

1072 

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

1074 

1075 - `unknown`

1076 

1077 - `type: "and" or "or"`

1078 

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

1080 

1081 - `"and"`

1082 

1083 - `"or"`

1084 

1085 - `max_num_results: optional number`

1086 

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

1088 

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

1090 

1091 Ranking options for search.

1092 

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

1094 

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

1096 

1097 - `embedding_weight: number`

1098 

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

1100 

1101 - `text_weight: number`

1102 

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

1104 

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

1106 

1107 The ranker to use for the file search.

1108 

1109 - `"auto"`

1110 

1111 - `"default-2024-11-15"`

1112 

1113 - `score_threshold: optional number`

1114 

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

1116 

1117 - `Computer object { type }`

1118 

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

1120 

1121 - `type: "computer"`

1122 

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

1124 

1125 - `"computer"`

1126 

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

1128 

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

1130 

1131 - `display_height: number`

1132 

1133 The height of the computer display.

1134 

1135 - `display_width: number`

1136 

1137 The width of the computer display.

1138 

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

1140 

1141 The type of computer environment to control.

1142 

1143 - `"windows"`

1144 

1145 - `"mac"`

1146 

1147 - `"linux"`

1148 

1149 - `"ubuntu"`

1150 

1151 - `"browser"`

1152 

1153 - `type: "computer_use_preview"`

1154 

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

1156 

1157 - `"computer_use_preview"`

1158 

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

1160 

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

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

1163 

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

1165 

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

1167 

1168 - `"web_search"`

1169 

1170 - `"web_search_2025_08_26"`

1171 

1172 - `external_web_access: optional boolean`

1173 

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

1175 

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

1177 

1178 Filters for the search.

1179 

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

1181 

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

1183 Subdomains of the provided domains are allowed as well.

1184 

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

1186 

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

1188 

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

1190 

1191 - `"low"`

1192 

1193 - `"medium"`

1194 

1195 - `"high"`

1196 

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

1198 

1199 The approximate location of the user.

1200 

1201 - `city: optional string or null`

1202 

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

1204 

1205 - `country: optional string or null`

1206 

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

1208 

1209 - `region: optional string or null`

1210 

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

1212 

1213 - `timezone: optional string or null`

1214 

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

1216 

1217 - `type: optional "approximate"`

1218 

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

1220 

1221 - `"approximate"`

1222 

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

1224 

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

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

1227 

1228 - `server_label: string`

1229 

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

1231 

1232 - `type: "mcp"`

1233 

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

1235 

1236 - `"mcp"`

1237 

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

1239 

1240 The tool invocation context(s).

1241 

1242 - `"direct"`

1243 

1244 - `"programmatic"`

1245 

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

1247 

1248 List of allowed tool names or a filter object.

1249 

1250 - `McpAllowedTools = array of string`

1251 

1252 A string array of allowed tool names

1253 

1254 - `McpToolFilter object { read_only, tool_names }`

1255 

1256 A filter object to specify which tools are allowed.

1257 

1258 - `read_only: optional boolean`

1259 

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

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

1262 it will match this filter.

1263 

1264 - `tool_names: optional array of string`

1265 

1266 List of allowed tool names.

1267 

1268 - `authorization: optional string`

1269 

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

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

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

1273 

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

1275 

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

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

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

1279 

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

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

1282 connect through a Secure MCP Tunnel.

1283 

1284 Currently supported `connector_id` values are:

1285 

1286 - Dropbox: `connector_dropbox`

1287 - Gmail: `connector_gmail`

1288 - Google Calendar: `connector_googlecalendar`

1289 - Google Drive: `connector_googledrive`

1290 - Microsoft Teams: `connector_microsoftteams`

1291 - Outlook Calendar: `connector_outlookcalendar`

1292 - Outlook Email: `connector_outlookemail`

1293 - SharePoint: `connector_sharepoint`

1294 

1295 - `"connector_dropbox"`

1296 

1297 - `"connector_gmail"`

1298 

1299 - `"connector_googlecalendar"`

1300 

1301 - `"connector_googledrive"`

1302 

1303 - `"connector_microsoftteams"`

1304 

1305 - `"connector_outlookcalendar"`

1306 

1307 - `"connector_outlookemail"`

1308 

1309 - `"connector_sharepoint"`

1310 

1311 - `defer_loading: optional boolean`

1312 

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

1314 

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

1316 

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

1318 or other purposes.

1319 

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

1321 

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

1323 

1324 - `McpToolApprovalFilter object { always, never }`

1325 

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

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

1328 that require approval.

1329 

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

1331 

1332 A filter object to specify which tools are allowed.

1333 

1334 - `read_only: optional boolean`

1335 

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

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

1338 it will match this filter.

1339 

1340 - `tool_names: optional array of string`

1341 

1342 List of allowed tool names.

1343 

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

1345 

1346 A filter object to specify which tools are allowed.

1347 

1348 - `read_only: optional boolean`

1349 

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

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

1352 it will match this filter.

1353 

1354 - `tool_names: optional array of string`

1355 

1356 List of allowed tool names.

1357 

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

1359 

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

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

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

1363 

1364 - `"always"`

1365 

1366 - `"never"`

1367 

1368 - `server_description: optional string`

1369 

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

1371 

1372 - `server_url: optional string`

1373 

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

1375 `tunnel_id` must be provided.

1376 

1377 - `tunnel_id: optional string`

1378 

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

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

1381 

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

1383 

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

1385 

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

1387 

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

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

1390 optional `memory_limit` setting.

1391 

1392 - `string`

1393 

1394 The container ID.

1395 

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

1397 

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

1399 

1400 - `type: "auto"`

1401 

1402 Always `auto`.

1403 

1404 - `"auto"`

1405 

1406 - `file_ids: optional array of string`

1407 

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

1409 

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

1411 

1412 The memory limit for the code interpreter container.

1413 

1414 - `"1g"`

1415 

1416 - `"4g"`

1417 

1418 - `"16g"`

1419 

1420 - `"64g"`

1421 

1422 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1423 

1424 Network access policy for the container.

1425 

1426 - `ContainerNetworkPolicyDisabled object { type }`

1427 

1428 - `type: "disabled"`

1429 

1430 Disable outbound network access. Always `disabled`.

1431 

1432 - `"disabled"`

1433 

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

1435 

1436 - `allowed_domains: array of string`

1437 

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

1439 

1440 - `type: "allowlist"`

1441 

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

1443 

1444 - `"allowlist"`

1445 

1446 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1447 

1448 Optional domain-scoped secrets for allowlisted domains.

1449 

1450 - `domain: string`

1451 

1452 The domain associated with the secret.

1453 

1454 - `name: string`

1455 

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

1457 

1458 - `value: string`

1459 

1460 The secret value to inject for the domain.

1461 

1462 - `type: "code_interpreter"`

1463 

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

1465 

1466 - `"code_interpreter"`

1467 

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

1469 

1470 The tool invocation context(s).

1471 

1472 - `"direct"`

1473 

1474 - `"programmatic"`

1475 

1476 - `ProgrammaticToolCalling object { type }`

1477 

1478 - `type: "programmatic_tool_calling"`

1479 

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

1481 

1482 - `"programmatic_tool_calling"`

1483 

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

1485 

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

1487 

1488 - `type: "image_generation"`

1489 

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

1491 

1492 - `"image_generation"`

1493 

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

1495 

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

1497 

1498 - `"generate"`

1499 

1500 - `"edit"`

1501 

1502 - `"auto"`

1503 

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

1505 

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

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

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

1509 backgrounds. Transparent backgrounds are available for supported GPT Image

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

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

1512 Default: `auto`.

1513 

1514 - `"transparent"`

1515 

1516 - `"opaque"`

1517 

1518 - `"auto"`

1519 

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

1521 

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

1523 

1524 - `"high"`

1525 

1526 - `"low"`

1527 

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

1529 

1530 Optional mask for inpainting. Contains `image_url`

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

1532 

1533 - `file_id: optional string`

1534 

1535 File ID for the mask image.

1536 

1537 - `image_url: optional string`

1538 

1539 Base64-encoded mask image.

1540 

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

1542 

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

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

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

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

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

1548 `gpt-image-1`.

1549 

1550 - `string`

1551 

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

1553 

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

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

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

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

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

1559 `gpt-image-1`.

1560 

1561 - `"gpt-image-1"`

1562 

1563 - `"gpt-image-1-mini"`

1564 

1565 - `"gpt-image-1.5"`

1566 

1567 - `"gpt-image-2"`

1568 

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

1570 

1571 - `"gpt-image-2.5-sunburst"`

1572 

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

1574 

1575 - `"gpt-image-2.5-flare"`

1576 

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

1578 

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

1580 

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

1582 

1583 - `"auto"`

1584 

1585 - `"low"`

1586 

1587 - `output_compression: optional number`

1588 

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

1590 

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

1592 

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

1594 `jpeg`. Default: `png`.

1595 

1596 - `"png"`

1597 

1598 - `"webp"`

1599 

1600 - `"jpeg"`

1601 

1602 - `partial_images: optional number`

1603 

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

1605 

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

1607 

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

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

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

1611 Default: `auto`.

1612 

1613 - `"low"`

1614 

1615 - `"medium"`

1616 

1617 - `"high"`

1618 

1619 - `"xhigh"`

1620 

1621 - `"max"`

1622 

1623 - `"auto"`

1624 

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

1626 

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

1628 

1629 - `string`

1630 

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

1632 

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

1634 

1635 - `"1024x1024"`

1636 

1637 - `"1024x1536"`

1638 

1639 - `"1536x1024"`

1640 

1641 - `"auto"`

1642 

1643 - `LocalShell object { type }`

1644 

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

1646 

1647 - `type: "local_shell"`

1648 

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

1650 

1651 - `"local_shell"`

1652 

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

1654 

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

1656 

1657 - `type: "shell"`

1658 

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

1660 

1661 - `"shell"`

1662 

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

1664 

1665 The tool invocation context(s).

1666 

1667 - `"direct"`

1668 

1669 - `"programmatic"`

1670 

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

1672 

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

1674 

1675 - `type: "container_auto"`

1676 

1677 Automatically creates a container for this request

1678 

1679 - `"container_auto"`

1680 

1681 - `file_ids: optional array of string`

1682 

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

1684 

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

1686 

1687 The memory limit for the container.

1688 

1689 - `"1g"`

1690 

1691 - `"4g"`

1692 

1693 - `"16g"`

1694 

1695 - `"64g"`

1696 

1697 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1698 

1699 Network access policy for the container.

1700 

1701 - `ContainerNetworkPolicyDisabled object { type }`

1702 

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

1704 

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

1706 

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

1708 

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

1710 

1711 - `skill_id: string`

1712 

1713 The ID of the referenced skill.

1714 

1715 - `type: "skill_reference"`

1716 

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

1718 

1719 - `"skill_reference"`

1720 

1721 - `version: optional string`

1722 

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

1724 

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

1726 

1727 - `description: string`

1728 

1729 The description of the skill.

1730 

1731 - `name: string`

1732 

1733 The name of the skill.

1734 

1735 - `source: InlineSkillSource`

1736 

1737 Inline skill payload

1738 

1739 - `data: string`

1740 

1741 Base64-encoded skill zip bundle.

1742 

1743 - `media_type: "application/zip"`

1744 

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

1746 

1747 - `"application/zip"`

1748 

1749 - `type: "base64"`

1750 

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

1752 

1753 - `"base64"`

1754 

1755 - `type: "inline"`

1756 

1757 Defines an inline skill for this request.

1758 

1759 - `"inline"`

1760 

1761 - `LocalEnvironment object { type, skills }`

1762 

1763 - `type: "local"`

1764 

1765 Use a local computer environment.

1766 

1767 - `"local"`

1768 

1769 - `skills: optional array of LocalSkill`

1770 

1771 An optional list of skills.

1772 

1773 - `description: string`

1774 

1775 The description of the skill.

1776 

1777 - `name: string`

1778 

1779 The name of the skill.

1780 

1781 - `path: string`

1782 

1783 The path to the directory containing the skill.

1784 

1785 - `ContainerReference object { container_id, type }`

1786 

1787 - `container_id: string`

1788 

1789 The ID of the referenced container.

1790 

1791 - `type: "container_reference"`

1792 

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

1794 

1795 - `"container_reference"`

1796 

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

1798 

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

1800 

1801 - `name: string`

1802 

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

1804 

1805 - `type: "custom"`

1806 

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

1808 

1809 - `"custom"`

1810 

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

1812 

1813 The tool invocation context(s).

1814 

1815 - `"direct"`

1816 

1817 - `"programmatic"`

1818 

1819 - `async: optional boolean`

1820 

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

1822 

1823 - `defer_loading: optional boolean`

1824 

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

1826 

1827 - `description: optional string`

1828 

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

1830 

1831 - `format: optional CustomToolInputFormat`

1832 

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

1834 

1835 - `Text object { type }`

1836 

1837 Unconstrained free-form text.

1838 

1839 - `type: "text"`

1840 

1841 Unconstrained text format. Always `text`.

1842 

1843 - `"text"`

1844 

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

1846 

1847 A grammar defined by the user.

1848 

1849 - `definition: string`

1850 

1851 The grammar definition.

1852 

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

1854 

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

1856 

1857 - `"lark"`

1858 

1859 - `"regex"`

1860 

1861 - `type: "grammar"`

1862 

1863 Grammar format. Always `grammar`.

1864 

1865 - `"grammar"`

1866 

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

1868 

1869 Groups function/custom tools under a shared namespace.

1870 

1871 - `description: string`

1872 

1873 A description of the namespace shown to the model.

1874 

1875 - `name: string`

1876 

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

1878 

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

1880 

1881 The function/custom tools available inside this namespace.

1882 

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

1884 

1885 - `name: string`

1886 

1887 - `type: "function"`

1888 

1889 - `"function"`

1890 

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

1892 

1893 The tool invocation context(s).

1894 

1895 - `"direct"`

1896 

1897 - `"programmatic"`

1898 

1899 - `async: optional boolean`

1900 

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

1902 

1903 - `defer_loading: optional boolean`

1904 

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

1906 

1907 - `description: optional string or null`

1908 

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

1910 

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

1912 

1913 - `parameters: optional unknown or null`

1914 

1915 - `strict: optional boolean or null`

1916 

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

1918 

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

1920 

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

1922 

1923 - `name: string`

1924 

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

1926 

1927 - `type: "custom"`

1928 

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

1930 

1931 - `"custom"`

1932 

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

1934 

1935 The tool invocation context(s).

1936 

1937 - `"direct"`

1938 

1939 - `"programmatic"`

1940 

1941 - `async: optional boolean`

1942 

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

1944 

1945 - `defer_loading: optional boolean`

1946 

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

1948 

1949 - `description: optional string`

1950 

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

1952 

1953 - `format: optional CustomToolInputFormat`

1954 

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

1956 

1957 - `type: "namespace"`

1958 

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

1960 

1961 - `"namespace"`

1962 

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

1964 

1965 Hosted or BYOT tool search configuration for deferred tools.

1966 

1967 - `type: "tool_search"`

1968 

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

1970 

1971 - `"tool_search"`

1972 

1973 - `description: optional string or null`

1974 

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

1976 

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

1978 

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

1980 

1981 - `"server"`

1982 

1983 - `"client"`

1984 

1985 - `parameters: optional unknown or null`

1986 

1987 Parameter schema for a client-executed tool search tool.

1988 

1989 - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }`

1990 

1991 This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](/api/docs/guides/tools-web-search).

1992 

1993 - `type: "web_search_preview" or "web_search_preview_2025_03_11"`

1994 

1995 The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.

1996