resources/chat/subresources/completions/methods/create/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

1## Create chat completion

2 

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

4 

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

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

7[Chat Completions with Responses](/docs/guides/responses-vs-chat-completions?api-mode=responses).

8 

9 

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

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

12and [audio](/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](/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](/docs/models) you use, different message types (modalities) are

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

30 [images](/docs/guides/vision), and [audio](/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 - `role: "developer"`

61 

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

63 

64 - `"developer"`

65 

66 - `name: optional string`

67 

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

69 

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

71 

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

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

74 for this purpose instead.

75 

76 - `content: string or array of ChatCompletionContentPartText`

77 

78 The contents of the system message.

79 

80 - `TextContent = string`

81 

82 The contents of the system message.

83 

84 - `ArrayOfContentParts = array of ChatCompletionContentPartText`

85 

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

87 

88 - `text: string`

89 

90 The text content.

91 

92 - `type: "text"`

93 

94 The type of the content part.

95 

96 - `role: "system"`

97 

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

99 

100 - `"system"`

101 

102 - `name: optional string`

103 

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

105 

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

107 

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

109 information.

110 

111 - `content: string or array of ChatCompletionContentPart`

112 

113 The contents of the user message.

114 

115 - `TextContent = string`

116 

117 The text contents of the message.

118 

119 - `ArrayOfContentParts = array of ChatCompletionContentPart`

120 

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

122 

123 - `ChatCompletionContentPartText object { text, type }`

124 

125 Learn about [text inputs](/docs/guides/text-generation).

126 

127 - `text: string`

128 

129 The text content.

130 

131 - `type: "text"`

132 

133 The type of the content part.

134 

135 - `ChatCompletionContentPartImage object { image_url, type }`

136 

137 Learn about [image inputs](/docs/guides/vision).

138 

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

140 

141 - `url: string`

142 

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

144 

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

146 

147 Specifies the detail level of the image. Learn more in the [Vision guide](/docs/guides/vision#low-or-high-fidelity-image-understanding).

148 

149 - `"auto"`

150 

151 - `"low"`

152 

153 - `"high"`

154 

155 - `type: "image_url"`

156 

157 The type of the content part.

158 

159 - `"image_url"`

160 

161 - `ChatCompletionContentPartInputAudio object { input_audio, type }`

162 

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

164 

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

166 

167 - `data: string`

168 

169 Base64 encoded audio data.

170 

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

172 

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

174 

175 - `"wav"`

176 

177 - `"mp3"`

178 

179 - `type: "input_audio"`

180 

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

182 

183 - `"input_audio"`

184 

185 - `FileContentPart object { file, type }`

186 

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

188 

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

190 

191 - `file_data: optional string`

192 

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

194 as a string.

195 

196 - `file_id: optional string`

197 

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

199 

200 - `filename: optional string`

201 

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

203 string.

204 

205 - `type: "file"`

206 

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

208 

209 - `"file"`

210 

211 - `role: "user"`

212 

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

214 

215 - `"user"`

216 

217 - `name: optional string`

218 

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

220 

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

222 

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

224 

225 - `role: "assistant"`

226 

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

228 

229 - `"assistant"`

230 

231 - `audio: optional object { id }`

232 

233 Data about a previous audio response from the model.

234 [Learn more](/docs/guides/audio).

235 

236 - `id: string`

237 

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

239 

240 - `content: optional string or array of ChatCompletionContentPartText or ChatCompletionContentPartRefusal`

241 

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

243 

244 - `TextContent = string`

245 

246 The contents of the assistant message.

247 

248 - `ArrayOfContentParts = array of ChatCompletionContentPartText or ChatCompletionContentPartRefusal`

249 

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

251 

252 - `ChatCompletionContentPartText object { text, type }`

253 

254 Learn about [text inputs](/docs/guides/text-generation).

255 

256 - `ChatCompletionContentPartRefusal object { refusal, type }`

257 

258 - `refusal: string`

259 

260 The refusal message generated by the model.

261 

262 - `type: "refusal"`

263 

264 The type of the content part.

265 

266 - `"refusal"`

267 

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

269 

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

271 

272 - `arguments: string`

273 

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

275 

276 - `name: string`

277 

278 The name of the function to call.

279 

280 - `name: optional string`

281 

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

283 

284 - `refusal: optional string`

285 

286 The refusal message by the assistant.

287 

288 - `tool_calls: optional array of ChatCompletionMessageToolCall`

289 

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

291 

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

293 

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

295 

296 - `id: string`

297 

298 The ID of the tool call.

299 

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

301 

302 The function that the model called.

303 

304 - `arguments: string`

305 

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

307 

308 - `name: string`

309 

310 The name of the function to call.

311 

312 - `type: "function"`

313 

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

315 

316 - `"function"`

317 

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

319 

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

321 

322 - `id: string`

323 

324 The ID of the tool call.

325 

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

327 

328 The custom tool that the model called.

329 

330 - `input: string`

331 

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

333 

334 - `name: string`

335 

336 The name of the custom tool to call.

337 

338 - `type: "custom"`

339 

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

341 

342 - `"custom"`

343 

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

345 

346 - `content: string or array of ChatCompletionContentPartText`

347 

348 The contents of the tool message.

349 

350 - `TextContent = string`

351 

352 The contents of the tool message.

353 

354 - `ArrayOfContentParts = array of ChatCompletionContentPartText`

355 

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

357 

358 - `text: string`

359 

360 The text content.

361 

362 - `type: "text"`

363 

364 The type of the content part.

365 

366 - `role: "tool"`

367 

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

369 

370 - `"tool"`

371 

372 - `tool_call_id: string`

373 

374 Tool call that this message is responding to.

375 

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

377 

378 - `content: string`

379 

380 The contents of the function message.

381 

382 - `name: string`

383 

384 The name of the function to call.

385 

386 - `role: "function"`

387 

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

389 

390 - `"function"`

391 

392- `model: string or "gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 75 more`

393 

394 Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI

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

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

397 to browse and compare available models.

398 

399 - `string`

400 

401 - `"gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 75 more`

402 

403 Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI

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

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

406 to browse and compare available models.

407 

408 - `"gpt-5.4"`

409 

410 - `"gpt-5.4-mini"`

411 

412 - `"gpt-5.4-nano"`

413 

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

415 

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

417 

418 - `"gpt-5.3-chat-latest"`

419 

420 - `"gpt-5.2"`

421 

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

423 

424 - `"gpt-5.2-chat-latest"`

425 

426 - `"gpt-5.2-pro"`

427 

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

429 

430 - `"gpt-5.1"`

431 

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

433 

434 - `"gpt-5.1-codex"`

435 

436 - `"gpt-5.1-mini"`

437 

438 - `"gpt-5.1-chat-latest"`

439 

440 - `"gpt-5"`

441 

442 - `"gpt-5-mini"`

443 

444 - `"gpt-5-nano"`

445 

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

447 

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

449 

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

451 

452 - `"gpt-5-chat-latest"`

453 

454 - `"gpt-4.1"`

455 

456 - `"gpt-4.1-mini"`

457 

458 - `"gpt-4.1-nano"`

459 

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

461 

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

463 

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

465 

466 - `"o4-mini"`

467 

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

469 

470 - `"o3"`

471 

472 - `"o3-2025-04-16"`

473 

474 - `"o3-mini"`

475 

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

477 

478 - `"o1"`

479 

480 - `"o1-2024-12-17"`

481 

482 - `"o1-preview"`

483 

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

485 

486 - `"o1-mini"`

487 

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

489 

490 - `"gpt-4o"`

491 

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

493 

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

495 

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

497 

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

499 

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

501 

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

503 

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

505 

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

507 

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

509 

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

511 

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

513 

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

515 

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

517 

518 - `"chatgpt-4o-latest"`

519 

520 - `"codex-mini-latest"`

521 

522 - `"gpt-4o-mini"`

523 

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

525 

526 - `"gpt-4-turbo"`

527 

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

529 

530 - `"gpt-4-0125-preview"`

531 

532 - `"gpt-4-turbo-preview"`

533 

534 - `"gpt-4-1106-preview"`

535 

536 - `"gpt-4-vision-preview"`

537 

538 - `"gpt-4"`

539 

540 - `"gpt-4-0314"`

541 

542 - `"gpt-4-0613"`

543 

544 - `"gpt-4-32k"`

545 

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

547 

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

549 

550 - `"gpt-3.5-turbo"`

551 

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

553 

554 - `"gpt-3.5-turbo-0301"`

555 

556 - `"gpt-3.5-turbo-0613"`

557 

558 - `"gpt-3.5-turbo-1106"`

559 

560 - `"gpt-3.5-turbo-0125"`

561 

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

563 

564- `audio: optional ChatCompletionAudioParam`

565 

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

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

568 

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

570 

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

572 `opus`, or `pcm16`.

573 

574 - `"wav"`

575 

576 - `"aac"`

577 

578 - `"mp3"`

579 

580 - `"flac"`

581 

582 - `"opus"`

583 

584 - `"pcm16"`

585 

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

587 

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

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

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

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

592 

593 - `string`

594 

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

596 

597 - `"alloy"`

598 

599 - `"ash"`

600 

601 - `"ballad"`

602 

603 - `"coral"`

604 

605 - `"echo"`

606 

607 - `"sage"`

608 

609 - `"shimmer"`

610 

611 - `"verse"`

612 

613 - `"marin"`

614 

615 - `"cedar"`

616 

617 - `ID object { id }`

618 

619 Custom voice reference.

620 

621 - `id: string`

622 

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

624 

625- `frequency_penalty: optional number`

626 

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

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

629 likelihood to repeat the same line verbatim.

630 

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

632 

633 Deprecated in favor of `tool_choice`.

634 

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

636 

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

638 message.

639 

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

641 function.

642 

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

644 model to call that function.

645 

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

647 if functions are present.

648 

649 - `"none" or "auto"`

650 

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

652 

653 - `"none"`

654 

655 - `"auto"`

656 

657 - `ChatCompletionFunctionCallOption object { name }`

658 

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

660 

661 - `name: string`

662 

663 The name of the function to call.

664 

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

666 

667 Deprecated in favor of `tools`.

668 

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

670 

671 - `name: string`

672 

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

674 

675 - `description: optional string`

676 

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

678 

679 - `parameters: optional FunctionParameters`

680 

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

682 

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

684 

685- `logit_bias: optional map[number]`

686 

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

688 

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

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

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

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

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

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

695 

696- `logprobs: optional boolean`

697 

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

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

700 `content` of `message`.

701 

702- `max_completion_tokens: optional number`

703 

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

705 

706- `max_tokens: optional number`

707 

708 The maximum number of [tokens](/tokenizer) that can be generated in the

709 chat completion. This value can be used to control

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

711 

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

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

714 

715- `metadata: optional Metadata`

716 

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

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

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

720 

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

722 with a maximum length of 512 characters.

723 

724- `modalities: optional array of "text" or "audio"`

725 

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

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

728 

729 `["text"]`

730 

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

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

733 both text and audio responses, you can use:

734 

735 `["text", "audio"]`

736 

737 - `"text"`

738 

739 - `"audio"`

740 

741- `n: optional number`

742 

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

744 

745- `parallel_tool_calls: optional boolean`

746 

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

748 

749- `prediction: optional ChatCompletionPredictionContent`

750 

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

752 being regenerated.

753 

754 - `content: string or array of ChatCompletionContentPartText`

755 

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

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

758 can be returned much more quickly.

759 

760 - `TextContent = string`

761 

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

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

764 

765 - `ArrayOfContentParts = array of ChatCompletionContentPartText`

766 

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

768 

769 - `text: string`

770 

771 The text content.

772 

773 - `type: "text"`

774 

775 The type of the content part.

776 

777 - `type: "content"`

778 

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

780 currently always `content`.

781 

782 - `"content"`

783 

784- `presence_penalty: optional number`

785 

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

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

788 to talk about new topics.

789 

790- `prompt_cache_key: optional string`

791 

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

793 

794- `prompt_cache_retention: optional "in_memory" or "24h"`

795 

796 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](/docs/guides/prompt-caching#prompt-cache-retention).

797 

798 - `"in_memory"`

799 

800 - `"24h"`

801 

802- `reasoning_effort: optional ReasoningEffort`

803 

804 Constrains effort on reasoning for

805 [reasoning models](https://platform.openai.com/docs/guides/reasoning).

806 Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing

807 reasoning effort can result in faster responses and fewer tokens used

808 on reasoning in a response.

809 

810 - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1.

811 - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`.

812 - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort.

813 - `xhigh` is supported for all models after `gpt-5.1-codex-max`.

814 

815 - `"none"`

816 

817 - `"minimal"`

818 

819 - `"low"`

820 

821 - `"medium"`

822 

823 - `"high"`

824 

825 - `"xhigh"`

826 

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

828 

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

830 

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

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

833 schema. Learn more in the [Structured Outputs

834 guide](/docs/guides/structured-outputs).

835 

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

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

838 is preferred for models that support it.

839 

840 - `ResponseFormatText object { type }`

841 

842 Default response format. Used to generate text responses.

843 

844 - `type: "text"`

845 

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

847 

848 - `"text"`

849 

850 - `ResponseFormatJSONSchema object { json_schema, type }`

851 

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

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

854 

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

856 

857 Structured Outputs configuration options, including a JSON Schema.

858 

859 - `name: string`

860 

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

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

863 

864 - `description: optional string`

865 

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

867 determine how to respond in the format.

868 

869 - `schema: optional map[unknown]`

870 

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

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

873 

874 - `strict: optional boolean`

875 

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

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

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

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

880 guide](/docs/guides/structured-outputs).

881 

882 - `type: "json_schema"`

883 

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

885 

886 - `"json_schema"`

887 

888 - `ResponseFormatJSONObject object { type }`

889 

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

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

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

893 to do so.

894 

895 - `type: "json_object"`

896 

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

898 

899 - `"json_object"`

900 

901- `safety_identifier: optional string`

902 

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

904 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](/docs/guides/safety-best-practices#safety-identifiers).

905 

906- `seed: optional number`

907 

908 This feature is in Beta.

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

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

911 

912- `service_tier: optional "auto" or "default" or "flex" or 2 more`

913 

914 Specifies the processing type used for serving the request.

915 

916 - 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'.

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

918 - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.

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

920 

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

922 

923 - `"auto"`

924 

925 - `"default"`

926 

927 - `"flex"`

928 

929 - `"scale"`

930 

931 - `"priority"`

932 

933- `stop: optional string or array of string`

934 

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

936 

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

938 returned text will not contain the stop sequence.

939 

940 - `string`

941 

942 - `array of string`

943 

944- `store: optional boolean`

945 

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

947 use in our [model distillation](/docs/guides/distillation) or

948 [evals](/docs/guides/evals) products.

949 

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

951 

952- `stream: optional boolean`

953 

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

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

956 See the [Streaming section below](/docs/api-reference/chat/streaming)

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

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

959 

960- `stream_options: optional ChatCompletionStreamOptions`

961 

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

963 

964 - `include_obfuscation: optional boolean`

965 

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

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

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

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

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

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

972 your application and the OpenAI API.

973 

974 - `include_usage: optional boolean`

975 

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

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

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

979 array.

980 

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

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

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

984 

985- `temperature: optional number`

986 

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

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

989 

990- `tool_choice: optional ChatCompletionToolChoiceOption`

991 

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

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

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

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

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

997 

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

999 

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

1001 

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

1003 

1004 - `"none"`

1005 

1006 - `"auto"`

1007 

1008 - `"required"`

1009 

1010 - `ChatCompletionAllowedToolChoice object { allowed_tools, type }`

1011 

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

1013 

1014 - `allowed_tools: ChatCompletionAllowedTools`

1015 

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

1017 

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

1019 

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

1021 

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

1023 message.

1024 

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

1026 

1027 - `"auto"`

1028 

1029 - `"required"`

1030 

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

1032 

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

1034 

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

1036 

1037 ```json

1038 [

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

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

1041 ]

1042 ```

1043 

1044 - `type: "allowed_tools"`

1045 

1046 Allowed tool configuration type. Always `allowed_tools`.

1047 

1048 - `"allowed_tools"`

1049 

1050 - `ChatCompletionNamedToolChoice object { function, type }`

1051 

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

1053 

1054 - `function: object { name }`

1055 

1056 - `name: string`

1057 

1058 The name of the function to call.

1059 

1060 - `type: "function"`

1061 

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

1063 

1064 - `"function"`

1065 

1066 - `ChatCompletionNamedToolChoiceCustom object { custom, type }`

1067 

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

1069 

1070 - `custom: object { name }`

1071 

1072 - `name: string`

1073 

1074 The name of the custom tool to call.

1075 

1076 - `type: "custom"`

1077 

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

1079 

1080 - `"custom"`

1081 

1082- `tools: optional array of ChatCompletionTool`

1083 

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

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

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

1087 

1088 - `ChatCompletionFunctionTool object { function, type }`

1089 

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

1091 

1092 - `function: FunctionDefinition`

1093 

1094 - `name: string`

1095 

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

1097 

1098 - `description: optional string`

1099 

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

1101 

1102 - `parameters: optional FunctionParameters`

1103 

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

1105 

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

1107 

1108 - `strict: optional boolean`

1109 

1110 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](/docs/guides/function-calling).

1111 

1112 - `type: "function"`

1113 

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

1115 

1116 - `"function"`

1117 

1118 - `ChatCompletionCustomTool object { custom, type }`

1119 

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

1121 

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

1123 

1124 Properties of the custom tool.

1125 

1126 - `name: string`

1127 

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

1129 

1130 - `description: optional string`

1131 

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

1133 

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

1135 

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

1137 

1138 - `TextFormat object { type }`

1139 

1140 Unconstrained free-form text.

1141 

1142 - `type: "text"`

1143 

1144 Unconstrained text format. Always `text`.

1145 

1146 - `"text"`

1147 

1148 - `GrammarFormat object { grammar, type }`

1149 

1150 A grammar defined by the user.

1151 

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

1153 

1154 Your chosen grammar.

1155 

1156 - `definition: string`

1157 

1158 The grammar definition.

1159 

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

1161 

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

1163 

1164 - `"lark"`

1165 

1166 - `"regex"`

1167 

1168 - `type: "grammar"`

1169 

1170 Grammar format. Always `grammar`.

1171 

1172 - `"grammar"`

1173 

1174 - `type: "custom"`

1175 

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

1177 

1178 - `"custom"`

1179 

1180- `top_logprobs: optional number`

1181 

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

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

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

1185 requested.

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

1187 

1188- `top_p: optional number`

1189 

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

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

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

1193 are considered.

1194 

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

1196 

1197- `user: optional string`

1198 

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

1200 A stable identifier for your end-users.

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

1202 

1203- `verbosity: optional "low" or "medium" or "high"`

1204 

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

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

1207 Currently supported values are `low`, `medium`, and `high`.

1208 

1209 - `"low"`

1210 

1211 - `"medium"`

1212 

1213 - `"high"`

1214 

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

1216 

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

1218 Learn more about the [web search tool](/docs/guides/tools-web-search?api-mode=chat).

1219 

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

1221 

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

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

1224 

1225 - `"low"`

1226 

1227 - `"medium"`

1228 

1229 - `"high"`

1230 

1231 - `user_location: optional object { approximate, type }`

1232 

1233 Approximate location parameters for the search.

1234 

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

1236 

1237 Approximate location parameters for the search.

1238 

1239 - `city: optional string`

1240 

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

1242 

1243 - `country: optional string`

1244 

1245 The two-letter

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

1247 e.g. `US`.

1248 

1249 - `region: optional string`

1250 

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

1252 

1253 - `timezone: optional string`

1254 

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

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

1257 

1258 - `type: "approximate"`

1259 

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

1261 

1262 - `"approximate"`

1263 

1264### Returns

1265 

1266- `ChatCompletion object { id, choices, created, 5 more }`

1267 

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

1269 

1270 - `id: string`

1271 

1272 A unique identifier for the chat completion.

1273 

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

1275 

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

1277 

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

1279 

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

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

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

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

1284 

1285 - `"stop"`

1286 

1287 - `"length"`

1288 

1289 - `"tool_calls"`

1290 

1291 - `"content_filter"`

1292 

1293 - `"function_call"`

1294 

1295 - `index: number`

1296 

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

1298 

1299 - `logprobs: object { content, refusal }`

1300 

1301 Log probability information for the choice.

1302 

1303 - `content: array of ChatCompletionTokenLogprob`

1304 

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

1306 

1307 - `token: string`

1308 

1309 The token.

1310 

1311 - `bytes: array of number`

1312 

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

1314 

1315 - `logprob: number`

1316 

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

1318 

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

1320 

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

1322 

1323 - `token: string`

1324 

1325 The token.

1326 

1327 - `bytes: array of number`

1328 

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

1330 

1331 - `logprob: number`

1332 

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

1334 

1335 - `refusal: array of ChatCompletionTokenLogprob`

1336 

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

1338 

1339 - `token: string`

1340 

1341 The token.

1342 

1343 - `bytes: array of number`

1344 

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

1346 

1347 - `logprob: number`

1348 

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

1350 

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

1352 

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

1354 

1355 - `message: ChatCompletionMessage`

1356 

1357 A chat completion message generated by the model.

1358 

1359 - `content: string`

1360 

1361 The contents of the message.

1362 

1363 - `refusal: string`

1364 

1365 The refusal message generated by the model.

1366 

1367 - `role: "assistant"`

1368 

1369 The role of the author of this message.

1370 

1371 - `"assistant"`

1372 

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

1374 

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

1376 [web search tool](/docs/guides/tools-web-search?api-mode=chat).

1377 

1378 - `type: "url_citation"`

1379 

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

1381 

1382 - `"url_citation"`

1383 

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

1385 

1386 A URL citation when using web search.

1387 

1388 - `end_index: number`

1389 

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

1391 

1392 - `start_index: number`

1393 

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

1395 

1396 - `title: string`

1397 

1398 The title of the web resource.

1399 

1400 - `url: string`

1401 

1402 The URL of the web resource.

1403 

1404 - `audio: optional ChatCompletionAudio`

1405 

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

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

1408 

1409 - `id: string`

1410 

1411 Unique identifier for this audio response.

1412 

1413 - `data: string`

1414 

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

1416 specified in the request.

1417 

1418 - `expires_at: number`

1419 

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

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

1422 conversations.

1423 

1424 - `transcript: string`

1425 

1426 Transcript of the audio generated by the model.

1427 

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

1429 

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

1431 

1432 - `arguments: string`

1433 

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

1435 

1436 - `name: string`

1437 

1438 The name of the function to call.

1439 

1440 - `tool_calls: optional array of ChatCompletionMessageToolCall`

1441 

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

1443 

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

1445 

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

1447 

1448 - `id: string`

1449 

1450 The ID of the tool call.

1451 

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

1453 

1454 The function that the model called.

1455 

1456 - `arguments: string`

1457 

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

1459 

1460 - `name: string`

1461 

1462 The name of the function to call.

1463 

1464 - `type: "function"`

1465 

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

1467 

1468 - `"function"`

1469 

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

1471 

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

1473 

1474 - `id: string`

1475 

1476 The ID of the tool call.

1477 

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

1479 

1480 The custom tool that the model called.

1481 

1482 - `input: string`

1483 

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

1485 

1486 - `name: string`

1487 

1488 The name of the custom tool to call.

1489 

1490 - `type: "custom"`

1491 

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

1493 

1494 - `"custom"`

1495 

1496 - `created: number`

1497 

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

1499 

1500 - `model: string`

1501 

1502 The model used for the chat completion.

1503 

1504 - `object: "chat.completion"`

1505 

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

1507 

1508 - `"chat.completion"`

1509 

1510 - `service_tier: optional "auto" or "default" or "flex" or 2 more`

1511 

1512 Specifies the processing type used for serving the request.

1513 

1514 - 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'.

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

1516 - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.

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

1518 

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

1520 

1521 - `"auto"`

1522 

1523 - `"default"`

1524 

1525 - `"flex"`

1526 

1527 - `"scale"`

1528 

1529 - `"priority"`

1530 

1531 - `system_fingerprint: optional string`

1532 

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

1534 

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

1536 

1537 - `usage: optional CompletionUsage`

1538 

1539 Usage statistics for the completion request.

1540 

1541 - `completion_tokens: number`

1542 

1543 Number of tokens in the generated completion.

1544 

1545 - `prompt_tokens: number`

1546 

1547 Number of tokens in the prompt.

1548 

1549 - `total_tokens: number`

1550 

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

1552 

1553 - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, rejected_prediction_tokens }`

1554 

1555 Breakdown of tokens used in a completion.

1556 

1557 - `accepted_prediction_tokens: optional number`

1558 

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

1560 prediction that appeared in the completion.

1561 

1562 - `audio_tokens: optional number`

1563 

1564 Audio input tokens generated by the model.

1565 

1566 - `reasoning_tokens: optional number`

1567 

1568 Tokens generated by the model for reasoning.

1569 

1570 - `rejected_prediction_tokens: optional number`

1571 

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

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

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

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

1576 limits.

1577 

1578 - `prompt_tokens_details: optional object { audio_tokens, cached_tokens }`

1579 

1580 Breakdown of tokens used in the prompt.

1581 

1582 - `audio_tokens: optional number`

1583 

1584 Audio input tokens present in the prompt.

1585 

1586 - `cached_tokens: optional number`

1587 

1588 Cached tokens present in the prompt.

1589 

1590### Example

1591 

1592```http

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

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

1595 -H "Authorization: Bearer $OPENAI_API_KEY" \

1596 -d '{

1597 "messages": [

1598 {

1599 "content": "string",

1600 "role": "developer"

1601 }

1602 ],

1603 "model": "gpt-5.4",

1604 "n": 1,

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

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

1607 "temperature": 1,

1608 "top_p": 1,

1609 "user": "user-1234"

1610 }'

1611```

1612 

1613#### Response

1614 

1615```json

1616{

1617 "id": "id",

1618 "choices": [

1619 {

1620 "finish_reason": "stop",

1621 "index": 0,

1622 "logprobs": {

1623 "content": [

1624 {

1625 "token": "token",

1626 "bytes": [

1627 0

1628 ],

1629 "logprob": 0,

1630 "top_logprobs": [

1631 {

1632 "token": "token",

1633 "bytes": [

1634 0

1635 ],

1636 "logprob": 0

1637 }

1638 ]

1639 }

1640 ],

1641 "refusal": [

1642 {

1643 "token": "token",

1644 "bytes": [

1645 0

1646 ],

1647 "logprob": 0,

1648 "top_logprobs": [

1649 {

1650 "token": "token",

1651 "bytes": [

1652 0

1653 ],

1654 "logprob": 0

1655 }

1656 ]

1657 }

1658 ]

1659 },

1660 "message": {

1661 "content": "content",

1662 "refusal": "refusal",

1663 "role": "assistant",

1664 "annotations": [

1665 {

1666 "type": "url_citation",

1667 "url_citation": {

1668 "end_index": 0,

1669 "start_index": 0,

1670 "title": "title",

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

1672 }

1673 }

1674 ],

1675 "audio": {

1676 "id": "id",

1677 "data": "data",

1678 "expires_at": 0,

1679 "transcript": "transcript"

1680 },

1681 "function_call": {

1682 "arguments": "arguments",

1683 "name": "name"

1684 },

1685 "tool_calls": [

1686 {

1687 "id": "id",

1688 "function": {

1689 "arguments": "arguments",

1690 "name": "name"

1691 },

1692 "type": "function"

1693 }

1694 ]

1695 }

1696 }

1697 ],

1698 "created": 0,

1699 "model": "model",

1700 "object": "chat.completion",

1701 "service_tier": "auto",

1702 "system_fingerprint": "system_fingerprint",

1703 "usage": {

1704 "completion_tokens": 0,

1705 "prompt_tokens": 0,

1706 "total_tokens": 0,

1707 "completion_tokens_details": {

1708 "accepted_prediction_tokens": 0,

1709 "audio_tokens": 0,

1710 "reasoning_tokens": 0,

1711 "rejected_prediction_tokens": 0

1712 },

1713 "prompt_tokens_details": {

1714 "audio_tokens": 0,

1715 "cached_tokens": 0

1716 }

1717 }

1718}

1719```

1720 

1721### Example

1722 

1723```http

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

1725 -H "Content-Type: application/json" \

1726 -H "Authorization: Bearer $OPENAI_API_KEY" \

1727 -d '{

1728 "model": "VAR_chat_model_id",

1729 "messages": [

1730 {

1731 "role": "developer",

1732 "content": "You are a helpful assistant."

1733 },

1734 {

1735 "role": "user",

1736 "content": "Hello!"

1737 }

1738 ]

1739 }'

1740```

1741 

1742#### Response

1743 

1744```json

1745{

1746 "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",

1747 "object": "chat.completion",

1748 "created": 1741569952,

1749 "model": "gpt-5.4",

1750 "choices": [

1751 {

1752 "index": 0,

1753 "message": {

1754 "role": "assistant",

1755 "content": "Hello! How can I assist you today?",

1756 "refusal": null,

1757 "annotations": []

1758 },

1759 "logprobs": null,

1760 "finish_reason": "stop"

1761 }

1762 ],

1763 "usage": {

1764 "prompt_tokens": 19,

1765 "completion_tokens": 10,

1766 "total_tokens": 29,

1767 "prompt_tokens_details": {

1768 "cached_tokens": 0,

1769 "audio_tokens": 0

1770 },

1771 "completion_tokens_details": {

1772 "reasoning_tokens": 0,

1773 "audio_tokens": 0,

1774 "accepted_prediction_tokens": 0,

1775 "rejected_prediction_tokens": 0

1776 }

1777 },

1778 "service_tier": "default"

1779}

1780```

1781 

1782### Image input

1783 

1784```http

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

1786 -H "Content-Type: application/json" \

1787 -H "Authorization: Bearer $OPENAI_API_KEY" \

1788 -d '{

1789 "model": "gpt-5.4",

1790 "messages": [

1791 {

1792 "role": "user",

1793 "content": [

1794 {

1795 "type": "text",

1796 "text": "What is in this image?"

1797 },

1798 {

1799 "type": "image_url",

1800 "image_url": {

1801 "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"

1802 }

1803 }

1804 ]

1805 }

1806 ],

1807 "max_tokens": 300

1808 }'

1809```

1810 

1811#### Response

1812 

1813```json

1814{

1815 "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",

1816 "object": "chat.completion",

1817 "created": 1741570283,

1818 "model": "gpt-5.4",

1819 "choices": [

1820 {

1821 "index": 0,

1822 "message": {

1823 "role": "assistant",

1824 "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.",

1825 "refusal": null,

1826 "annotations": []

1827 },

1828 "logprobs": null,

1829 "finish_reason": "stop"

1830 }

1831 ],

1832 "usage": {

1833 "prompt_tokens": 1117,

1834 "completion_tokens": 46,

1835 "total_tokens": 1163,

1836 "prompt_tokens_details": {

1837 "cached_tokens": 0,

1838 "audio_tokens": 0

1839 },

1840 "completion_tokens_details": {

1841 "reasoning_tokens": 0,

1842 "audio_tokens": 0,

1843 "accepted_prediction_tokens": 0,

1844 "rejected_prediction_tokens": 0

1845 }

1846 },

1847 "service_tier": "default"

1848}

1849```

1850 

1851### Streaming

1852 

1853```http

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

1855 -H "Content-Type: application/json" \

1856 -H "Authorization: Bearer $OPENAI_API_KEY" \

1857 -d '{

1858 "model": "VAR_chat_model_id",

1859 "messages": [

1860 {

1861 "role": "developer",

1862 "content": "You are a helpful assistant."

1863 },

1864 {

1865 "role": "user",

1866 "content": "Hello!"

1867 }

1868 ],

1869 "stream": true

1870 }'

1871```

1872 

1873#### Response

1874 

1875```json

1876{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

1877 

1878{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]}

1879 

1880....

1881 

1882{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

1883```

1884 

1885### Functions

1886 

1887```http

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

1889-H "Content-Type: application/json" \

1890-H "Authorization: Bearer $OPENAI_API_KEY" \

1891-d '{

1892 "model": "gpt-5.4",

1893 "messages": [

1894 {

1895 "role": "user",

1896 "content": "What is the weather like in Boston today?"

1897 }

1898 ],

1899 "tools": [

1900 {

1901 "type": "function",

1902 "function": {

1903 "name": "get_current_weather",

1904 "description": "Get the current weather in a given location",

1905 "parameters": {

1906 "type": "object",

1907 "properties": {

1908 "location": {

1909 "type": "string",

1910 "description": "The city and state, e.g. San Francisco, CA"

1911 },

1912 "unit": {

1913 "type": "string",

1914 "enum": ["celsius", "fahrenheit"]

1915 }

1916 },

1917 "required": ["location"]

1918 }

1919 }

1920 }

1921 ],

1922 "tool_choice": "auto"

1923}'

1924```

1925 

1926#### Response

1927 

1928```json

1929{

1930 "id": "chatcmpl-abc123",

1931 "object": "chat.completion",

1932 "created": 1699896916,

1933 "model": "gpt-4o-mini",

1934 "choices": [

1935 {

1936 "index": 0,

1937 "message": {

1938 "role": "assistant",

1939 "content": null,

1940 "tool_calls": [

1941 {

1942 "id": "call_abc123",

1943 "type": "function",

1944 "function": {

1945 "name": "get_current_weather",

1946 "arguments": "{\n\"location\": \"Boston, MA\"\n}"

1947 }

1948 }

1949 ]

1950 },

1951 "logprobs": null,

1952 "finish_reason": "tool_calls"

1953 }

1954 ],

1955 "usage": {

1956 "prompt_tokens": 82,

1957 "completion_tokens": 17,

1958 "total_tokens": 99,

1959 "completion_tokens_details": {

1960 "reasoning_tokens": 0,

1961 "accepted_prediction_tokens": 0,

1962 "rejected_prediction_tokens": 0

1963 }

1964 }

1965}

1966```

1967 

1968### Logprobs

1969 

1970```http

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

1972 -H "Content-Type: application/json" \

1973 -H "Authorization: Bearer $OPENAI_API_KEY" \

1974 -d '{

1975 "model": "VAR_chat_model_id",

1976 "messages": [

1977 {

1978 "role": "user",

1979 "content": "Hello!"

1980 }

1981 ],

1982 "logprobs": true,

1983 "top_logprobs": 2

1984 }'

1985```

1986 

1987#### Response

1988 

1989```json

1990{

1991 "id": "chatcmpl-123",

1992 "object": "chat.completion",

1993 "created": 1702685778,

1994 "model": "gpt-4o-mini",

1995 "choices": [

1996 {