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

1## Create chat completion

2 

3**post** `/chat/completions`

4 

5**Starting a new project?** We recommend trying [Responses](/api/reference/resources/responses)

6to take advantage of the latest OpenAI platform features. Compare

7[Chat Completions with Responses](/api/docs/guides/migrate-to-responses?api-mode=responses).

8 

9 

10Creates a model response for the given chat conversation. Learn more in the

11[text generation](/api/docs/guides/text), [vision](/api/docs/guides/images-vision),

12and [audio](/api/docs/guides/audio) guides.

13 

14Parameter support can differ depending on the model used to generate the

15response, particularly for newer reasoning models. Parameters that are only

16supported for reasoning models are noted below. For the current state of

17unsupported parameters in reasoning models,

18[refer to the reasoning guide](/api/docs/guides/reasoning).

19 

20Returns a chat completion object, or a streamed sequence of chat completion

21chunk objects if the request is streamed.

22 

23### Body Parameters

24 

25- `messages: array of ChatCompletionMessageParam`

26 

27 A list of messages comprising the conversation so far. Depending on the

28 [model](/api/docs/models) you use, different message types (modalities) are

29 supported, like [text](/api/docs/guides/text),

30 [images](/api/docs/guides/images-vision), and [audio](/api/docs/guides/audio).

31 

32 - `ChatCompletionDeveloperMessageParam object { content, role, name }`

33 

34 Developer-provided instructions that the model should follow, regardless of

35 messages sent by the user. With o1 models and newer, `developer` messages

36 replace the previous `system` messages.

37 

38 - `content: string or array of ChatCompletionContentPartText`

39 

40 The contents of the developer message.

41 

42 - `TextContent = string`

43 

44 The contents of the developer message.

45 

46 - `ArrayOfContentParts = array of ChatCompletionContentPartText`

47 

48 An array of content parts with a defined type. For developer messages, only type `text` is supported.

49 

50 - `text: string`

51 

52 The text content.

53 

54 - `type: "text"`

55 

56 The type of the content part.

57 

58 - `"text"`

59 

60 - `prompt_cache_breakpoint: optional object { mode }`

61 

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

63 

64 - `mode: "explicit"`

65 

66 The breakpoint mode. Always `explicit`.

67 

68 - `"explicit"`

69 

70 - `role: "developer"`

71 

72 The role of the messages author, in this case `developer`.

73 

74 - `"developer"`

75 

76 - `name: optional string`

77 

78 An optional name for the participant. Provides the model information to differentiate between participants of the same role.

79 

80 - `ChatCompletionSystemMessageParam object { content, role, name }`

81 

82 Developer-provided instructions that the model should follow, regardless of

83 messages sent by the user. With o1 models and newer, use `developer` messages

84 for this purpose instead.

85 

86 - `content: string or array of ChatCompletionContentPartText`

87 

88 The contents of the system message.

89 

90 - `TextContent = string`

91 

92 The contents of the system message.

93 

94 - `ArrayOfContentParts = array of ChatCompletionContentPartText`

95 

96 An array of content parts with a defined type. For system messages, only type `text` is supported.

97 

98 - `text: string`

99 

100 The text content.

101 

102 - `type: "text"`

103 

104 The type of the content part.

105 

106 - `prompt_cache_breakpoint: optional object { mode }`

107 

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

109 

110 - `role: "system"`

111 

112 The role of the messages author, in this case `system`.

113 

114 - `"system"`

115 

116 - `name: optional string`

117 

118 An optional name for the participant. Provides the model information to differentiate between participants of the same role.

119 

120 - `ChatCompletionUserMessageParam object { content, role, name }`

121 

122 Messages sent by an end user, containing prompts or additional context

123 information.

124 

125 - `content: string or array of ChatCompletionContentPart`

126 

127 The contents of the user message.

128 

129 - `TextContent = string`

130 

131 The text contents of the message.

132 

133 - `ArrayOfContentParts = array of ChatCompletionContentPart`

134 

135 An array of content parts with a defined type. Supported options differ based on the [model](/api/docs/models) being used to generate the response. Can contain text, image, or audio inputs.

136 

137 - `ChatCompletionContentPartText object { text, type, prompt_cache_breakpoint }`

138 

139 Learn about [text inputs](/api/docs/guides/text).

140 

141 - `text: string`

142 

143 The text content.

144 

145 - `type: "text"`

146 

147 The type of the content part.

148 

149 - `prompt_cache_breakpoint: optional object { mode }`

150 

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

152 

153 - `ChatCompletionContentPartImage object { image_url, type, prompt_cache_breakpoint }`

154 

155 Learn about [image inputs](/api/docs/guides/images-vision).

156 

157 - `image_url: object { url, detail }`

158 

159 - `url: string`

160 

161 Either a URL of the image or the base64 encoded image data.

162 

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

164 

165 Specifies the detail level of the image. Learn more in the [Vision guide](/api/docs/guides/images-vision#choose-an-image-detail-level).

166 

167 - `"auto"`

168 

169 - `"low"`

170 

171 - `"high"`

172 

173 - `type: "image_url"`

174 

175 The type of the content part.

176 

177 - `"image_url"`

178 

179 - `prompt_cache_breakpoint: optional object { mode }`

180 

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

182 

183 - `mode: "explicit"`

184 

185 The breakpoint mode. Always `explicit`.

186 

187 - `"explicit"`

188 

189 - `ChatCompletionContentPartInputAudio object { input_audio, type, prompt_cache_breakpoint }`

190 

191 Learn about [audio inputs](/api/docs/guides/audio).

192 

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

194 

195 - `data: string`

196 

197 Base64 encoded audio data.

198 

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

200 

201 The format of the encoded audio data. Currently supports "wav" and "mp3".

202 

203 - `"wav"`

204 

205 - `"mp3"`

206 

207 - `type: "input_audio"`

208 

209 The type of the content part. Always `input_audio`.

210 

211 - `"input_audio"`

212 

213 - `prompt_cache_breakpoint: optional object { mode }`

214 

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

216 

217 - `mode: "explicit"`

218 

219 The breakpoint mode. Always `explicit`.

220 

221 - `"explicit"`

222 

223 - `FileContentPart object { file, type, prompt_cache_breakpoint }`

224 

225 Learn about [file inputs](/api/docs/guides/text) for text generation.

226 

227 - `file: object { file_data, file_id, filename }`

228 

229 - `file_data: optional string`

230 

231 The base64 encoded file data, used when passing the file to the model

232 as a string.

233 

234 - `file_id: optional string`

235 

236 The ID of an uploaded file to use as input.

237 

238 - `filename: optional string`

239 

240 The name of the file, used when passing the file to the model as a

241 string.

242 

243 - `type: "file"`

244 

245 The type of the content part. Always `file`.

246 

247 - `"file"`

248 

249 - `prompt_cache_breakpoint: optional object { mode }`

250 

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

252 

253 - `mode: "explicit"`

254 

255 The breakpoint mode. Always `explicit`.

256 

257 - `"explicit"`

258 

259 - `role: "user"`

260 

261 The role of the messages author, in this case `user`.

262 

263 - `"user"`

264 

265 - `name: optional string`

266 

267 An optional name for the participant. Provides the model information to differentiate between participants of the same role.

268 

269 - `ChatCompletionAssistantMessageParam object { role, audio, content, 4 more }`

270 

271 Messages sent by the model in response to user messages.

272 

273 - `role: "assistant"`

274 

275 The role of the messages author, in this case `assistant`.

276 

277 - `"assistant"`

278 

279 - `audio: optional object { id } or null`

280 

281 Data about a previous audio response from the model.

282 [Learn more](/api/docs/guides/audio).

283 

284 - `id: string`

285 

286 Unique identifier for a previous audio response from the model.

287 

288 - `content: optional string or array of ChatCompletionContentPartText or ChatCompletionContentPartRefusal or null`

289 

290 The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified.

291 

292 - `TextContent = string`

293 

294 The contents of the assistant message.

295 

296 - `ArrayOfContentParts = array of ChatCompletionContentPartText or ChatCompletionContentPartRefusal`

297 

298 An array of content parts with a defined type. Can be one or more of type `text`, or exactly one of type `refusal`.

299 

300 - `ChatCompletionContentPartText object { text, type, prompt_cache_breakpoint }`

301 

302 Learn about [text inputs](/api/docs/guides/text).

303 

304 - `ChatCompletionContentPartRefusal object { refusal, type }`

305 

306 - `refusal: string`

307 

308 The refusal message generated by the model.

309 

310 - `type: "refusal"`

311 

312 The type of the content part.

313 

314 - `"refusal"`

315 

316 - `function_call: optional object { arguments, name } or null`

317 

318 Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.

319 

320 - `arguments: string`

321 

322 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

323 

324 - `name: string`

325 

326 The name of the function to call.

327 

328 - `name: optional string`

329 

330 An optional name for the participant. Provides the model information to differentiate between participants of the same role.

331 

332 - `refusal: optional string or null`

333 

334 The refusal message by the assistant.

335 

336 - `tool_calls: optional array of ChatCompletionMessageToolCall`

337 

338 The tool calls generated by the model, such as function calls.

339 

340 - `ChatCompletionMessageFunctionToolCall object { id, function, type }`

341 

342 A call to a function tool created by the model.

343 

344 - `id: string`

345 

346 The ID of the tool call.

347 

348 - `function: object { arguments, name }`

349 

350 The function that the model called.

351 

352 - `arguments: string`

353 

354 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

355 

356 - `name: string`

357 

358 The name of the function to call.

359 

360 - `type: "function"`

361 

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

363 

364 - `"function"`

365 

366 - `ChatCompletionMessageCustomToolCall object { id, custom, type }`

367 

368 A call to a custom tool created by the model.

369 

370 - `id: string`

371 

372 The ID of the tool call.

373 

374 - `custom: object { input, name }`

375 

376 The custom tool that the model called.

377 

378 - `input: string`

379 

380 The input for the custom tool call generated by the model.

381 

382 - `name: string`

383 

384 The name of the custom tool to call.

385 

386 - `type: "custom"`

387 

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

389 

390 - `"custom"`

391 

392 - `ChatCompletionToolMessageParam object { content, role, tool_call_id }`

393 

394 - `content: string or array of ChatCompletionContentPartText`

395 

396 The contents of the tool message.

397 

398 - `TextContent = string`

399 

400 The contents of the tool message.

401 

402 - `ArrayOfContentParts = array of ChatCompletionContentPartText`

403 

404 An array of content parts with a defined type. For tool messages, only type `text` is supported.

405 

406 - `text: string`

407 

408 The text content.

409 

410 - `type: "text"`

411 

412 The type of the content part.

413 

414 - `prompt_cache_breakpoint: optional object { mode }`

415 

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

417 

418 - `role: "tool"`

419 

420 The role of the messages author, in this case `tool`.

421 

422 - `"tool"`

423 

424 - `tool_call_id: string`

425 

426 Tool call that this message is responding to.

427 

428 - `ChatCompletionFunctionMessageParam object { content, name, role }`

429 

430 - `content: string or null`

431 

432 The contents of the function message.

433 

434 - `name: string`

435 

436 The name of the function to call.

437 

438 - `role: "function"`

439 

440 The role of the messages author, in this case `function`.

441 

442 - `"function"`

443 

444- `model: string or "gpt-6-astra" or "gpt-5.6-sol" or "gpt-5.6-terra" or 82 more`

445 

446 Model ID used to generate the response, like `gpt-6-astra` or `o3`. OpenAI

447 offers a wide range of models with different capabilities, performance

448 characteristics, and price points. Refer to the [model guide](/api/docs/models)

449 to browse and compare available models.

450 

451 - `string`

452 

453 - `"gpt-6-astra" or "gpt-5.6-sol" or "gpt-5.6-terra" or 82 more`

454 

455 Model ID used to generate the response, like `gpt-6-astra` or `o3`. OpenAI

456 offers a wide range of models with different capabilities, performance

457 characteristics, and price points. Refer to the [model guide](/api/docs/models)

458 to browse and compare available models.

459 

460 - `"gpt-6-astra"`

461 

462 - `"gpt-5.6-sol"`

463 

464 - `"gpt-5.6-terra"`

465 

466 - `"gpt-5.6-luna"`

467 

468 - `"gpt-5.5"`

469 

470 - `"gpt-5.5-2026-04-23"`

471 

472 - `"gpt-5.4"`

473 

474 - `"gpt-5.4-mini"`

475 

476 - `"gpt-5.4-nano"`

477 

478 - `"gpt-5.4-mini-2026-03-17"`

479 

480 - `"gpt-5.4-nano-2026-03-17"`

481 

482 - `"gpt-5.3-chat-latest"`

483 

484 - `"gpt-5.2"`

485 

486 - `"gpt-5.2-2025-12-11"`

487 

488 - `"gpt-5.2-chat-latest"`

489 

490 - `"gpt-5.2-pro"`

491 

492 - `"gpt-5.2-pro-2025-12-11"`

493 

494 - `"gpt-5.1"`

495 

496 - `"gpt-5.1-2025-11-13"`

497 

498 - `"gpt-5.1-codex"`

499 

500 - `"gpt-5.1-chat-latest"`

501 

502 - `"gpt-5"`

503 

504 - `"gpt-5-mini"`

505 

506 - `"gpt-5-nano"`

507 

508 - `"gpt-5-2025-08-07"`

509 

510 - `"gpt-5-mini-2025-08-07"`

511 

512 - `"gpt-5-nano-2025-08-07"`

513 

514 - `"gpt-5-chat-latest"`

515 

516 - `"gpt-4.1"`

517 

518 - `"gpt-4.1-mini"`

519 

520 - `"gpt-4.1-nano"`

521 

522 - `"gpt-4.1-2025-04-14"`

523 

524 - `"gpt-4.1-mini-2025-04-14"`

525 

526 - `"gpt-4.1-nano-2025-04-14"`

527 

528 - `"o4-mini"`

529 

530 - `"o4-mini-2025-04-16"`

531 

532 - `"o3"`

533 

534 - `"o3-2025-04-16"`

535 

536 - `"o3-mini"`

537 

538 - `"o3-mini-2025-01-31"`

539 

540 - `"o1"`

541 

542 - `"o1-2024-12-17"`

543 

544 - `"o1-preview"`

545 

546 - `"o1-preview-2024-09-12"`

547 

548 - `"o1-mini"`

549 

550 - `"o1-mini-2024-09-12"`

551 

552 - `"gpt-4o"`

553 

554 - `"gpt-4o-2024-11-20"`

555 

556 - `"gpt-4o-2024-08-06"`

557 

558 - `"gpt-4o-2024-05-13"`

559 

560 - `"gpt-audio-mini"`

561 

562 - `"gpt-audio-mini-2025-12-15"`

563 

564 - `"gpt-4o-audio-preview"`

565 

566 - `"gpt-4o-audio-preview-2024-10-01"`

567 

568 - `"gpt-4o-audio-preview-2024-12-17"`

569 

570 - `"gpt-4o-audio-preview-2025-06-03"`

571 

572 - `"gpt-4o-mini-audio-preview"`

573 

574 - `"gpt-4o-mini-audio-preview-2024-12-17"`

575 

576 - `"gpt-4o-search-preview"`

577 

578 - `"gpt-4o-mini-search-preview"`

579 

580 - `"gpt-4o-search-preview-2025-03-11"`

581 

582 - `"gpt-4o-mini-search-preview-2025-03-11"`

583 

584 - `"chatgpt-4o-latest"`

585 

586 - `"codex-mini-latest"`

587 

588 - `"gpt-4o-mini"`

589 

590 - `"gpt-4o-mini-2024-07-18"`

591 

592 - `"gpt-4-turbo"`

593 

594 - `"gpt-4-turbo-2024-04-09"`

595 

596 - `"gpt-4-0125-preview"`

597 

598 - `"gpt-4-turbo-preview"`

599 

600 - `"gpt-4-1106-preview"`

601 

602 - `"gpt-4-vision-preview"`

603 

604 - `"gpt-4"`

605 

606 - `"gpt-4-0314"`

607 

608 - `"gpt-4-0613"`

609 

610 - `"gpt-4-32k"`

611 

612 - `"gpt-4-32k-0314"`

613 

614 - `"gpt-4-32k-0613"`

615 

616 - `"gpt-3.5-turbo"`

617 

618 - `"gpt-3.5-turbo-16k"`

619 

620 - `"gpt-3.5-turbo-0301"`

621 

622 - `"gpt-3.5-turbo-0613"`

623 

624 - `"gpt-3.5-turbo-1106"`

625 

626 - `"gpt-3.5-turbo-0125"`

627 

628 - `"gpt-3.5-turbo-16k-0613"`

629 

630- `audio: optional ChatCompletionAudioParam or null`

631 

632 Parameters for audio output. Required when audio output is requested with

633 `modalities: ["audio"]`. [Learn more](/api/docs/guides/audio).

634 

635 - `format: "wav" or "aac" or "mp3" or 3 more`

636 

637 Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`,

638 `opus`, or `pcm16`.

639 

640 - `"wav"`

641 

642 - `"aac"`

643 

644 - `"mp3"`

645 

646 - `"flac"`

647 

648 - `"opus"`

649 

650 - `"pcm16"`

651 

652 - `voice: string or "alloy" or "ash" or "ballad" or 7 more or object { id }`

653 

654 The voice the model uses to respond. Supported built-in voices are

655 `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`,

656 `sage`, `shimmer`, `marin`, and `cedar`. You may also provide a

657 custom voice object with an `id`, for example `{ "id": "voice_1234" }`.

658 

659 - `string`

660 

661 - `"alloy" or "ash" or "ballad" or 7 more`

662 

663 - `"alloy"`

664 

665 - `"ash"`

666 

667 - `"ballad"`

668 

669 - `"coral"`

670 

671 - `"echo"`

672 

673 - `"sage"`

674 

675 - `"shimmer"`

676 

677 - `"verse"`

678 

679 - `"marin"`

680 

681 - `"cedar"`

682 

683 - `ID object { id }`

684 

685 Custom voice reference.

686 

687 - `id: string`

688 

689 The custom voice ID, e.g. `voice_1234`.

690 

691- `frequency_penalty: optional number or null`

692 

693 Number between -2.0 and 2.0. Positive values penalize new tokens based on

694 their existing frequency in the text so far, decreasing the model's

695 likelihood to repeat the same line verbatim.

696 

697- `function_call: optional "none" or "auto" or ChatCompletionFunctionCallOption`

698 

699 Deprecated in favor of `tool_choice`.

700 

701 Controls which (if any) function is called by the model.

702 

703 `none` means the model will not call a function and instead generates a

704 message.

705 

706 `auto` means the model can pick between generating a message or calling a

707 function.

708 

709 Specifying a particular function via `{"name": "my_function"}` forces the

710 model to call that function.

711 

712 `none` is the default when no functions are present. `auto` is the default

713 if functions are present.

714 

715 - `"none" or "auto"`

716 

717 `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function.

718 

719 - `"none"`

720 

721 - `"auto"`

722 

723 - `ChatCompletionFunctionCallOption object { name }`

724 

725 Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.

726 

727 - `name: string`

728 

729 The name of the function to call.

730 

731- `functions: optional array of object { name, description, parameters }`

732 

733 Deprecated in favor of `tools`.

734 

735 A list of functions the model may generate JSON inputs for.

736 

737 - `name: string`

738 

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

740 

741 - `description: optional string`

742 

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

744 

745 - `parameters: optional FunctionParameters`

746 

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

748 

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

750 

751- `logit_bias: optional map[number] or null`

752 

753 Modify the likelihood of specified tokens appearing in the completion.

754 

755 Accepts a JSON object that maps tokens (specified by their token ID in the

756 tokenizer) to an associated bias value from -100 to 100. Mathematically,

757 the bias is added to the logits generated by the model prior to sampling.

758 The exact effect will vary per model, but values between -1 and 1 should

759 decrease or increase likelihood of selection; values like -100 or 100

760 should result in a ban or exclusive selection of the relevant token.

761 

762- `logprobs: optional boolean or null`

763 

764 Whether to return log probabilities of the output tokens or not. If true,

765 returns the log probabilities of each output token returned in the

766 `content` of `message`.

767 

768- `max_completion_tokens: optional number or null`

769 

770 An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and [reasoning tokens](/api/docs/guides/reasoning).

771 

772- `max_tokens: optional number or null`

773 

774 The maximum number of [tokens](https://platform.openai.com/tokenizer) that can be generated in the

775 chat completion. This value can be used to control

776 [costs](https://openai.com/api/pricing/) for text generated via API.

777 

778 This value is now deprecated in favor of `max_completion_tokens`, and is

779 not compatible with [o-series models](/api/docs/guides/reasoning).

780 

781- `metadata: optional Metadata or null`

782 

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

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

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

786 

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

788 with a maximum length of 512 characters.

789 

790- `modalities: optional array of "text" or "audio" or null`

791 

792 Output types that you would like the model to generate.

793 Most models are capable of generating text, which is the default:

794 

795 `["text"]`

796 

797 The `gpt-4o-audio-preview` model can also be used to

798 [generate audio](/api/docs/guides/audio). To request that this model generate

799 both text and audio responses, you can use:

800 

801 `["text", "audio"]`

802 

803 - `"text"`

804 

805 - `"audio"`

806 

807- `moderation: optional object { model, policy } or null`

808 

809 Configuration for running moderation on the request input and generated output.

810 

811 - `model: string`

812 

813 The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'.

814 

815 - `policy: optional object { input, output } or null`

816 

817 The policy to apply to moderated response input and output.

818 

819 - `input: optional object { mode } or null`

820 

821 The moderation policy for the response input.

822 

823 - `mode: "score" or "block"`

824 

825 - `"score"`

826 

827 - `"block"`

828 

829 - `output: optional object { mode } or null`

830 

831 The moderation policy for the response output.

832 

833 - `mode: "score" or "block"`

834 

835 - `"score"`

836 

837 - `"block"`

838 

839- `n: optional number or null`

840 

841 How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs.

842 

843- `parallel_tool_calls: optional boolean`

844 

845 Whether to enable [parallel function calling](/api/docs/guides/function-calling#parallel-function-calling) during tool use.

846 

847- `prediction: optional ChatCompletionPredictionContent or null`

848 

849 Static predicted output content, such as the content of a text file that is

850 being regenerated.

851 

852 - `content: string or array of ChatCompletionContentPartText`

853 

854 The content that should be matched when generating a model response.

855 If generated tokens would match this content, the entire model response

856 can be returned much more quickly.

857 

858 - `TextContent = string`

859 

860 The content used for a Predicted Output. This is often the

861 text of a file you are regenerating with minor changes.

862 

863 - `ArrayOfContentParts = array of ChatCompletionContentPartText`

864 

865 An array of content parts with a defined type. Supported options differ based on the [model](/api/docs/models) being used to generate the response. Can contain text inputs.

866 

867 - `text: string`

868 

869 The text content.

870 

871 - `type: "text"`

872 

873 The type of the content part.

874 

875 - `prompt_cache_breakpoint: optional object { mode }`

876 

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

878 

879 - `type: "content"`

880 

881 The type of the predicted content you want to provide. This type is

882 currently always `content`.

883 

884 - `"content"`

885 

886- `presence_penalty: optional number or null`

887 

888 Number between -2.0 and 2.0. Positive values penalize new tokens based on

889 whether they appear in the text so far, increasing the model's likelihood

890 to talk about new topics.

891 

892- `prompt_cache_key: optional string or null`

893 

894 Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/api/docs/guides/prompt-caching).

895 

896- `prompt_cache_options: optional object { mode, ttl }`

897 

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

899 

900 - `mode: optional "implicit" or "explicit"`

901 

902 Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching.

903 

904 - `"implicit"`

905 

906 - `"explicit"`

907 

908 - `ttl: optional "30m"`

909 

910 The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer.

911 

912 - `"30m"`

913 

914- `prompt_cache_retention: optional "in_memory" or "24h" or null`

915 

916 Deprecated. Use `prompt_cache_options.ttl` instead.

917 

918 The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/api/docs/guides/prompt-caching#prompt-cache-retention).

919 This field expresses a maximum retention policy, while

920 `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two

921 fields are independent and do not interact.

922 For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported.

923 

924 For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy:

925 

926 - Organizations without ZDR enabled default to `24h`.

927 - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified.

928 

929 - `"in_memory"`

930 

931 - `"24h"`

932 

933- `reasoning_effort: optional ReasoningEffort or null`

934 

935 Constrains effort on reasoning for reasoning models. Currently supported

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

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

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

939 value. See the

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

941 for model-specific support.

942 

943 - `"none"`

944 

945 - `"minimal"`

946 

947 - `"low"`

948 

949 - `"medium"`

950 

951 - `"high"`

952 

953 - `"xhigh"`

954 

955 - `"max"`

956 

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

958 

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

960 

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

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

963 schema. Learn more in the [Structured Outputs

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

965 

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

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

968 is preferred for models that support it.

969 

970 - `ResponseFormatText object { type }`

971 

972 Default response format. Used to generate text responses.

973 

974 - `type: "text"`

975 

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

977 

978 - `"text"`

979 

980 - `ResponseFormatJSONSchema object { json_schema, type }`

981 

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

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

984 

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

986 

987 Structured Outputs configuration options, including a JSON Schema.

988 

989 - `name: string`

990 

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

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

993 

994 - `description: optional string`

995 

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

997 determine how to respond in the format.

998 

999 - `schema: optional map[unknown]`

1000 

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

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

1003 

1004 - `strict: optional boolean or null`

1005 

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

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

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

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

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

1011 

1012 - `type: "json_schema"`

1013 

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

1015 

1016 - `"json_schema"`

1017 

1018 - `ResponseFormatJSONObject object { type }`

1019 

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

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

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

1023 to do so.

1024 

1025 - `type: "json_object"`

1026 

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

1028 

1029 - `"json_object"`

1030 

1031- `safety_identifier: optional string or null`

1032 

1033 A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies.

1034 The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/api/docs/guides/safety-best-practices#implement-safety-identifiers).

1035 

1036- `seed: optional number or null`

1037 

1038 This feature is in Beta.

1039 If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.

1040 Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.

1041 

1042- `service_tier: optional "auto" or "default" or "flex" or 3 more or null`

1043 

1044 Specifies the processing type used for serving the request.

1045 

1046 - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.

1047 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.

1048 - If set to '[flex](/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier.

1049 - To opt-in to [Fast mode](/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. The response will show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority` in your request.

1050 - When not set, the default behavior is 'auto'.

1051 

1052 When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

1053 

1054 - `"auto"`

1055 

1056 - `"default"`

1057 

1058 - `"flex"`

1059 

1060 - `"scale"`

1061 

1062 - `"priority"`

1063 

1064 - `"fast"`

1065 

1066- `stop: optional string or array of string or null`

1067 

1068 Not supported with latest reasoning models `o3` and `o4-mini`.

1069 

1070 Up to 4 sequences where the API will stop generating further tokens. The

1071 returned text will not contain the stop sequence.

1072 

1073 - `string`

1074 

1075 - `array of string`

1076 

1077- `store: optional boolean or null`

1078 

1079 Whether or not to store the output of this chat completion request for

1080 use in our [model distillation](/api/docs/guides/supervised-fine-tuning#distilling-from-a-larger-model) or

1081 [evals](/api/docs/guides/evals) products.

1082 

1083 Supports text and image inputs. Note: image inputs over 8MB will be dropped.

1084 

1085- `stream: optional boolean or null`

1086 

1087 If set to true, the model response data will be streamed to the client

1088 as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).

1089 See the [Streaming section below](/api/reference/resources/chat/subresources/completions/streaming-events)

1090 for more information, along with the [streaming responses](/api/docs/guides/streaming-responses)

1091 guide for more information on how to handle the streaming events.

1092 

1093- `stream_options: optional ChatCompletionStreamOptions or null`

1094 

1095 Options for streaming response. Only set this when you set `stream: true`.

1096 

1097 - `include_obfuscation: optional boolean`

1098 

1099 When true, stream obfuscation will be enabled. Stream obfuscation adds

1100 random characters to an `obfuscation` field on streaming delta events to

1101 normalize payload sizes as a mitigation to certain side-channel attacks.

1102 These obfuscation fields are included by default, but add a small amount

1103 of overhead to the data stream. You can set `include_obfuscation` to

1104 false to optimize for bandwidth if you trust the network links between

1105 your application and the OpenAI API.

1106 

1107 - `include_usage: optional boolean`

1108 

1109 If set, an additional chunk will be streamed before the `data: [DONE]`

1110 message. The `usage` field on this chunk shows the token usage statistics

1111 for the entire request, and the `choices` field will always be an empty

1112 array.

1113 

1114 All other chunks will also include a `usage` field, but with a null

1115 value. **NOTE:** If the stream is interrupted, you may not receive the

1116 final usage chunk which contains the total token usage for the request.

1117 

1118- `temperature: optional number or null`

1119 

1120 What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

1121 We generally recommend altering this or `top_p` but not both.

1122 

1123- `tool_choice: optional ChatCompletionToolChoiceOption`

1124 

1125 Controls which (if any) tool is called by the model.

1126 `none` means the model will not call any tool and instead generates a message.

1127 `auto` means the model can pick between generating a message or calling one or more tools.

1128 `required` means the model must call one or more tools.

1129 Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.

1130 

1131 `none` is the default when no tools are present. `auto` is the default if tools are present.

1132 

1133 - `ToolChoiceMode = "none" or "auto" or "required"`

1134 

1135 `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools.

1136 

1137 - `"none"`

1138 

1139 - `"auto"`

1140 

1141 - `"required"`

1142 

1143 - `ChatCompletionAllowedToolChoice object { allowed_tools, type }`

1144 

1145 Constrains the tools available to the model to a pre-defined set.

1146 

1147 - `allowed_tools: ChatCompletionAllowedTools`

1148 

1149 Constrains the tools available to the model to a pre-defined set.

1150 

1151 - `mode: "auto" or "required"`

1152 

1153 Constrains the tools available to the model to a pre-defined set.

1154 

1155 `auto` allows the model to pick from among the allowed tools and generate a

1156 message.

1157 

1158 `required` requires the model to call one or more of the allowed tools.

1159 

1160 - `"auto"`

1161 

1162 - `"required"`

1163 

1164 - `tools: array of map[unknown]`

1165 

1166 A list of tool definitions that the model should be allowed to call.

1167 

1168 For the Chat Completions API, the list of tool definitions might look like:

1169 

1170 ```json

1171 [

1172 { "type": "function", "function": { "name": "get_weather" } },

1173 { "type": "function", "function": { "name": "get_time" } }

1174 ]

1175 ```

1176 

1177 - `type: "allowed_tools"`

1178 

1179 Allowed tool configuration type. Always `allowed_tools`.

1180 

1181 - `"allowed_tools"`

1182 

1183 - `ChatCompletionNamedToolChoice object { function, type }`

1184 

1185 Specifies a tool the model should use. Use to force the model to call a specific function.

1186 

1187 - `function: object { name }`

1188 

1189 - `name: string`

1190 

1191 The name of the function to call.

1192 

1193 - `type: "function"`

1194 

1195 For function calling, the type is always `function`.

1196 

1197 - `"function"`

1198 

1199 - `ChatCompletionNamedToolChoiceCustom object { custom, type }`

1200 

1201 Specifies a tool the model should use. Use to force the model to call a specific custom tool.

1202 

1203 - `custom: object { name }`

1204 

1205 - `name: string`

1206 

1207 The name of the custom tool to call.

1208 

1209 - `type: "custom"`

1210 

1211 For custom tool calling, the type is always `custom`.

1212 

1213 - `"custom"`

1214 

1215- `tools: optional array of ChatCompletionTool`

1216 

1217 A list of tools the model may call. You can provide either

1218 [custom tools](/api/docs/guides/function-calling#custom-tools) or

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

1220 

1221 - `ChatCompletionFunctionTool object { function, type }`

1222 

1223 A function tool that can be used to generate a response.

1224 

1225 - `function: FunctionDefinition`

1226 

1227 - `name: string`

1228 

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

1230 

1231 - `description: optional string`

1232 

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

1234 

1235 - `parameters: optional FunctionParameters`

1236 

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

1238 

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

1240 

1241 - `strict: optional boolean or null`

1242 

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

1244 

1245 - `type: "function"`

1246 

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

1248 

1249 - `"function"`

1250 

1251 - `ChatCompletionCustomTool object { custom, type }`

1252 

1253 A custom tool that processes input using a specified format.

1254 

1255 - `custom: object { name, description, format }`

1256 

1257 Properties of the custom tool.

1258 

1259 - `name: string`

1260 

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

1262 

1263 - `description: optional string`

1264 

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

1266 

1267 - `format: optional object { type } or object { grammar, type }`

1268 

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

1270 

1271 - `Text object { type }`

1272 

1273 Unconstrained free-form text.

1274 

1275 - `type: "text"`

1276 

1277 Unconstrained text format. Always `text`.

1278 

1279 - `"text"`

1280 

1281 - `Grammar object { grammar, type }`

1282 

1283 A grammar defined by the user.

1284 

1285 - `grammar: object { definition, syntax }`

1286 

1287 Your chosen grammar.

1288 

1289 - `definition: string`

1290 

1291 The grammar definition.

1292 

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

1294 

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

1296 

1297 - `"lark"`

1298 

1299 - `"regex"`

1300 

1301 - `type: "grammar"`

1302 

1303 Grammar format. Always `grammar`.

1304 

1305 - `"grammar"`

1306 

1307 - `type: "custom"`

1308 

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

1310 

1311 - `"custom"`

1312 

1313- `top_logprobs: optional number or null`

1314 

1315 An integer between 0 and 20 specifying the maximum number of most likely

1316 tokens to return at each token position, each with an associated log

1317 probability. In some cases, the number of returned tokens may be fewer than

1318 requested.

1319 `logprobs` must be set to `true` if this parameter is used.

1320 

1321- `top_p: optional number or null`

1322 

1323 An alternative to sampling with temperature, called nucleus sampling,

1324 where the model considers the results of the tokens with top_p probability

1325 mass. So 0.1 means only the tokens comprising the top 10% probability mass

1326 are considered.

1327 

1328 We generally recommend altering this or `temperature` but not both.

1329 

1330- `user: optional string`

1331 

1332 This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.

1333 A stable identifier for your end-users.

1334 Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/api/docs/guides/safety-best-practices#implement-safety-identifiers).

1335 

1336- `verbosity: optional "low" or "medium" or "high" or null`

1337 

1338 Constrains the verbosity of the model's response. Lower values will result in

1339 more concise responses, while higher values will result in more verbose responses.

1340 Currently supported values are `low`, `medium`, and `high`. The default is

1341 `medium`.

1342 

1343 - `"low"`

1344 

1345 - `"medium"`

1346 

1347 - `"high"`

1348 

1349- `web_search_options: optional object { search_context_size, user_location }`

1350 

1351 This tool searches the web for relevant results to use in a response.

1352 Learn more about the [web search tool](/api/docs/guides/tools-web-search).

1353 

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

1355 

1356 High level guidance for the amount of context window space to use for the

1357 search. One of `low`, `medium`, or `high`. `medium` is the default.

1358 

1359 - `"low"`

1360 

1361 - `"medium"`

1362 

1363 - `"high"`

1364 

1365 - `user_location: optional object { approximate, type } or null`

1366 

1367 Approximate location parameters for the search.

1368 

1369 - `approximate: object { city, country, region, timezone }`

1370 

1371 Approximate location parameters for the search.

1372 

1373 - `city: optional string`

1374 

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

1376 

1377 - `country: optional string`

1378 

1379 The two-letter

1380 [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user,

1381 e.g. `US`.

1382 

1383 - `region: optional string`

1384 

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

1386 

1387 - `timezone: optional string`

1388 

1389 The [IANA timezone](https://timeapi.io/documentation/iana-timezones)

1390 of the user, e.g. `America/Los_Angeles`.

1391 

1392 - `type: "approximate"`

1393 

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

1395 

1396 - `"approximate"`

1397 

1398### Returns

1399 

1400- `ChatCompletion object { id, choices, created, 7 more }`

1401 

1402 Represents a chat completion response returned by model, based on the provided input.

1403 

1404 - `id: string`

1405 

1406 A unique identifier for the chat completion.

1407 

1408 - `choices: array of object { finish_reason, index, logprobs, message }`

1409 

1410 A list of chat completion choices. Can be more than one if `n` is greater than 1.

1411 

1412 - `finish_reason: "stop" or "length" or "tool_calls" or 2 more`

1413 

1414 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,

1415 `length` if the maximum number of tokens specified in the request was reached,

1416 `content_filter` if content was omitted due to a flag from our content filters,

1417 `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.

1418 Read the [Model Spec](https://model-spec.openai.com/2025-12-18.html) for more.

1419 

1420 - `"stop"`

1421 

1422 - `"length"`

1423 

1424 - `"tool_calls"`

1425 

1426 - `"content_filter"`

1427 

1428 - `"function_call"`

1429 

1430 - `index: number`

1431 

1432 The index of the choice in the list of choices.

1433 

1434 - `logprobs: object { content, refusal } or null`

1435 

1436 Log probability information for the choice.

1437 

1438 - `content: array of ChatCompletionTokenLogprob or null`

1439 

1440 A list of message content tokens with log probability information.

1441 

1442 - `token: string`

1443 

1444 The token.

1445 

1446 - `bytes: array of number or null`

1447 

1448 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1449 

1450 - `logprob: number`

1451 

1452 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1453 

1454 - `top_logprobs: array of object { token, bytes, logprob }`

1455 

1456 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

1457 

1458 - `token: string`

1459 

1460 The token.

1461 

1462 - `bytes: array of number or null`

1463 

1464 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1465 

1466 - `logprob: number`

1467 

1468 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1469 

1470 - `refusal: array of ChatCompletionTokenLogprob or null`

1471 

1472 A list of message refusal tokens with log probability information.

1473 

1474 - `token: string`

1475 

1476 The token.

1477 

1478 - `bytes: array of number or null`

1479 

1480 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1481 

1482 - `logprob: number`

1483 

1484 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1485 

1486 - `top_logprobs: array of object { token, bytes, logprob }`

1487 

1488 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

1489 

1490 - `message: ChatCompletionMessage`

1491 

1492 A chat completion message generated by the model.

1493 

1494 - `content: string or null`

1495 

1496 The contents of the message.

1497 

1498 - `refusal: string or null`

1499 

1500 The refusal message generated by the model.

1501 

1502 - `role: "assistant"`

1503 

1504 The role of the author of this message.

1505 

1506 - `"assistant"`

1507 

1508 - `annotations: optional array of object { type, url_citation }`

1509 

1510 Annotations for the message, when applicable, as when using the

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

1512 

1513 - `type: "url_citation"`

1514 

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

1516 

1517 - `"url_citation"`

1518 

1519 - `url_citation: object { end_index, start_index, title, url }`

1520 

1521 A URL citation when using web search.

1522 

1523 - `end_index: number`

1524 

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

1526 

1527 - `start_index: number`

1528 

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

1530 

1531 - `title: string`

1532 

1533 The title of the web resource.

1534 

1535 - `url: string`

1536 

1537 The URL of the web resource.

1538 

1539 - `audio: optional ChatCompletionAudio or null`

1540 

1541 If the audio output modality is requested, this object contains data

1542 about the audio response from the model. [Learn more](/api/docs/guides/audio).

1543 

1544 - `id: string`

1545 

1546 Unique identifier for this audio response.

1547 

1548 - `data: string`

1549 

1550 Base64 encoded audio bytes generated by the model, in the format

1551 specified in the request.

1552 

1553 - `expires_at: number`

1554 

1555 The Unix timestamp (in seconds) for when this audio response will

1556 no longer be accessible on the server for use in multi-turn

1557 conversations.

1558 

1559 - `transcript: string`

1560 

1561 Transcript of the audio generated by the model.

1562 

1563 - `function_call: optional object { arguments, name }`

1564 

1565 Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.

1566 

1567 - `arguments: string`

1568 

1569 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

1570 

1571 - `name: string`

1572 

1573 The name of the function to call.

1574 

1575 - `tool_calls: optional array of ChatCompletionMessageToolCall`

1576 

1577 The tool calls generated by the model, such as function calls.

1578 

1579 - `ChatCompletionMessageFunctionToolCall object { id, function, type }`

1580 

1581 A call to a function tool created by the model.

1582 

1583 - `id: string`

1584 

1585 The ID of the tool call.

1586 

1587 - `function: object { arguments, name }`

1588 

1589 The function that the model called.

1590 

1591 - `arguments: string`

1592 

1593 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

1594 

1595 - `name: string`

1596 

1597 The name of the function to call.

1598 

1599 - `type: "function"`

1600 

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

1602 

1603 - `"function"`

1604 

1605 - `ChatCompletionMessageCustomToolCall object { id, custom, type }`

1606 

1607 A call to a custom tool created by the model.

1608 

1609 - `id: string`

1610 

1611 The ID of the tool call.

1612 

1613 - `custom: object { input, name }`

1614 

1615 The custom tool that the model called.

1616 

1617 - `input: string`

1618 

1619 The input for the custom tool call generated by the model.

1620 

1621 - `name: string`

1622 

1623 The name of the custom tool to call.

1624 

1625 - `type: "custom"`

1626 

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

1628 

1629 - `"custom"`

1630 

1631 - `created: number`

1632 

1633 The Unix timestamp (in seconds) of when the chat completion was created.

1634 

1635 - `model: string`

1636 

1637 The model used for the chat completion.

1638 

1639 - `object: "chat.completion"`

1640 

1641 The object type, which is always `chat.completion`.

1642 

1643 - `"chat.completion"`

1644 

1645 - `metadata: optional Metadata or null`

1646 

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

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

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

1650 

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

1652 with a maximum length of 512 characters.

1653 

1654 - `moderation: optional object { input, output } or null`

1655 

1656 Moderation results for the request input and generated output, if moderated

1657 completions were requested.

1658 

1659 - `input: object { model, results, type } or object { code, message, type }`

1660 

1661 Moderation for the request input.

1662 

1663 - `ModerationResults object { model, results, type }`

1664 

1665 Successful moderation results for the request input or generated output.

1666 

1667 - `model: string`

1668 

1669 The moderation model used to generate the results.

1670 

1671 - `results: array of object { categories, category_applied_input_types, category_scores, 3 more }`

1672 

1673 A list of moderation results.

1674 

1675 - `categories: map[boolean]`

1676 

1677 A dictionary of moderation categories to booleans, True if the input is flagged under this category.

1678 

1679 - `category_applied_input_types: map[array of "text" or "image"]`

1680 

1681 Which modalities of input are reflected by the score for each category.

1682 

1683 - `"text"`

1684 

1685 - `"image"`

1686 

1687 - `category_scores: map[number]`

1688 

1689 A dictionary of moderation categories to scores.

1690 

1691 - `flagged: boolean`

1692 

1693 A boolean indicating whether the content was flagged by any category.

1694 

1695 - `model: string`

1696 

1697 The moderation model that produced this result.

1698 

1699 - `type: "moderation_result"`

1700 

1701 The object type, which was always `moderation_result` for successful moderation results.

1702 

1703 - `"moderation_result"`

1704 

1705 - `type: "moderation_results"`

1706 

1707 The object type, which is always `moderation_results`.

1708 

1709 - `"moderation_results"`

1710 

1711 - `Error object { code, message, type }`

1712 

1713 An error produced while attempting moderation.

1714 

1715 - `code: string`

1716 

1717 The error code.

1718 

1719 - `message: string`

1720 

1721 The error message.

1722 

1723 - `type: "error"`

1724 

1725 The object type, which is always `error`.

1726 

1727 - `"error"`

1728 

1729 - `output: object { model, results, type } or object { code, message, type }`

1730 

1731 Moderation for the generated output.

1732 

1733 - `ModerationResults object { model, results, type }`

1734 

1735 Successful moderation results for the request input or generated output.

1736 

1737 - `model: string`

1738 

1739 The moderation model used to generate the results.

1740 

1741 - `results: array of object { categories, category_applied_input_types, category_scores, 3 more }`

1742 

1743 A list of moderation results.

1744 

1745 - `categories: map[boolean]`

1746 

1747 A dictionary of moderation categories to booleans, True if the input is flagged under this category.

1748 

1749 - `category_applied_input_types: map[array of "text" or "image"]`

1750 

1751 Which modalities of input are reflected by the score for each category.

1752 

1753 - `"text"`

1754 

1755 - `"image"`

1756 

1757 - `category_scores: map[number]`

1758 

1759 A dictionary of moderation categories to scores.

1760 

1761 - `flagged: boolean`

1762 

1763 A boolean indicating whether the content was flagged by any category.

1764 

1765 - `model: string`

1766 

1767 The moderation model that produced this result.

1768 

1769 - `type: "moderation_result"`

1770 

1771 The object type, which was always `moderation_result` for successful moderation results.

1772 

1773 - `"moderation_result"`

1774 

1775 - `type: "moderation_results"`

1776 

1777 The object type, which is always `moderation_results`.

1778 

1779 - `"moderation_results"`

1780 

1781 - `Error object { code, message, type }`

1782 

1783 An error produced while attempting moderation.

1784 

1785 - `code: string`

1786 

1787 The error code.

1788 

1789 - `message: string`

1790 

1791 The error message.

1792 

1793 - `type: "error"`

1794 

1795 The object type, which is always `error`.

1796 

1797 - `"error"`

1798 

1799 - `service_tier: optional "auto" or "default" or "flex" or 3 more or null`

1800 

1801 Specifies the processing type used for serving the request.

1802 

1803 - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.

1804 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.

1805 - If set to '[flex](/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier.

1806 - To opt-in to [Fast mode](/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. The response will show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority` in your request.

1807 - When not set, the default behavior is 'auto'.

1808 

1809 When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

1810 

1811 - `"auto"`

1812 

1813 - `"default"`

1814 

1815 - `"flex"`

1816 

1817 - `"scale"`

1818 

1819 - `"priority"`

1820 

1821 - `"fast"`

1822 

1823 - `system_fingerprint: optional string`

1824 

1825 This fingerprint represents the backend configuration that the model runs with.

1826 

1827 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.

1828 

1829 - `usage: optional CompletionUsage`

1830 

1831 Usage statistics for the completion request.

1832 

1833 - `completion_tokens: number`

1834 

1835 Number of tokens in the generated completion.

1836 

1837 - `prompt_tokens: number`

1838 

1839 Number of tokens in the prompt.

1840 

1841 - `total_tokens: number`

1842 

1843 Total number of tokens used in the request (prompt + completion).

1844 

1845 - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, 2 more }`

1846 

1847 Breakdown of tokens used in a completion.

1848 

1849 - `accepted_prediction_tokens: optional number`

1850 

1851 When using Predicted Outputs, the number of tokens in the

1852 prediction that appeared in the completion.

1853 

1854 - `audio_tokens: optional number`

1855 

1856 Audio input tokens generated by the model.

1857 

1858 - `reasoning_tokens: optional number`

1859 

1860 Tokens generated by the model for reasoning.

1861 

1862 - `rejected_prediction_tokens: optional number`

1863 

1864 When using Predicted Outputs, the number of tokens in the

1865 prediction that did not appear in the completion. However, like

1866 reasoning tokens, these tokens are still counted in the total

1867 completion tokens for purposes of billing, output, and context window

1868 limits.

1869 

1870 - `text_tokens: optional number`

1871 

1872 Text output tokens generated by the model.

1873 

1874 - `prompt_tokens_details: optional object { audio_tokens, cache_write_tokens, cached_tokens, 2 more }`

1875 

1876 Breakdown of tokens used in the prompt.

1877 

1878 - `audio_tokens: optional number`

1879 

1880 Audio input tokens present in the prompt.

1881 

1882 - `cache_write_tokens: optional number`

1883 

1884 The unadjusted number of prompt tokens written to cache.

1885 

1886 - `cached_tokens: optional number`

1887 

1888 Cached tokens present in the prompt.

1889 

1890 - `image_tokens: optional number`

1891 

1892 Image input tokens present in the prompt.

1893 

1894 - `text_tokens: optional number`

1895 

1896 Text input tokens present in the prompt.

1897 

1898### Example

1899 

1900```http

1901curl https://api.openai.com/v1/chat/completions \

1902 -H 'Content-Type: application/json' \

1903 -H "Authorization: Bearer $OPENAI_API_KEY" \

1904 -d '{

1905 "messages": [

1906 {

1907 "content": "string",

1908 "role": "developer"

1909 }

1910 ],

1911 "model": "gpt-6-astra",

1912 "n": 1,

1913 "prompt_cache_key": "prompt-cache-key-1234",

1914 "safety_identifier": "safety-identifier-1234",

1915 "temperature": 1,

1916 "top_p": 1,

1917 "user": "user-1234"

1918 }'

1919```

1920 

1921#### Response

1922 

1923```json

1924{

1925 "id": "id",

1926 "choices": [

1927 {

1928 "finish_reason": "stop",

1929 "index": 0,

1930 "logprobs": {

1931 "content": [

1932 {

1933 "token": "token",

1934 "bytes": [

1935 0

1936 ],

1937 "logprob": 0,

1938 "top_logprobs": [

1939 {

1940 "token": "token",

1941 "bytes": [

1942 0

1943 ],

1944 "logprob": 0

1945 }

1946 ]

1947 }

1948 ],

1949 "refusal": [

1950 {

1951 "token": "token",

1952 "bytes": [

1953 0

1954 ],

1955 "logprob": 0,

1956 "top_logprobs": [

1957 {

1958 "token": "token",

1959 "bytes": [

1960 0

1961 ],

1962 "logprob": 0

1963 }

1964 ]

1965 }

1966 ]

1967 },

1968 "message": {

1969 "content": "content",

1970 "refusal": "refusal",

1971 "role": "assistant",

1972 "annotations": [

1973 {

1974 "type": "url_citation",

1975 "url_citation": {

1976 "end_index": 0,

1977 "start_index": 0,

1978 "title": "title",

1979 "url": "https://example.com"

1980 }

1981 }

1982 ],

1983 "audio": {

1984 "id": "id",

1985 "data": "data",

1986 "expires_at": 0,

1987 "transcript": "transcript"

1988 },

1989 "function_call": {

1990 "arguments": "arguments",

1991 "name": "name"

1992 },

1993 "tool_calls": [

1994 {

1995 "id": "id",

1996 "function": {