cli/resources/chat/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

1# Chat

2 

3# Completions

4 

5## Create chat completion

6 

7`$ openai chat:completions create`

8 

9**post** `/chat/completions`

10 

11**Starting a new project?** We recommend trying [Responses](https://platform.openai.com/docs/api-reference/responses)

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

13[Chat Completions with Responses](https://platform.openai.com/docs/guides/responses-vs-chat-completions?api-mode=responses).

14 

15 

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

17[text generation](https://platform.openai.com/docs/guides/text-generation), [vision](https://platform.openai.com/docs/guides/vision),

18and [audio](https://platform.openai.com/docs/guides/audio) guides.

19 

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

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

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

23unsupported parameters in reasoning models,

24[refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).

25 

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

27chunk objects if the request is streamed.

28 

29### Parameters

30 

31- `--message: array of ChatCompletionMessageParam`

32 

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

34 [model](https://platform.openai.com/docs/models) you use, different message types (modalities) are

35 supported, like [text](https://platform.openai.com/docs/guides/text-generation),

36 [images](https://platform.openai.com/docs/guides/vision), and [audio](https://platform.openai.com/docs/guides/audio).

37 

38- `--model: string or ChatModel`

39 

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

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

42 characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models)

43 to browse and compare available models.

44 

45- `--audio: optional object { format, voice }`

46 

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

48 `modalities: ["audio"]`. [Learn more](https://platform.openai.com/docs/guides/audio).

49 

50- `--frequency-penalty: optional number`

51 

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

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

54 likelihood to repeat the same line verbatim.

55 

56- `--function-call: optional "none" or "auto" or ChatCompletionFunctionCallOption`

57 

58 Deprecated in favor of `tool_choice`.

59 

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

61 

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

63 message.

64 

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

66 function.

67 

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

69 model to call that function.

70 

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

72 if functions are present.

73 

74- `--function: optional array of object { name, description, parameters }`

75 

76 Deprecated in favor of `tools`.

77 

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

79 

80- `--logit-bias: optional map[number]`

81 

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

83 

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

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

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

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

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

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

90 

91- `--logprobs: optional boolean`

92 

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

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

95 `content` of `message`.

96 

97- `--max-completion-tokens: optional number`

98 

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

100 

101- `--max-tokens: optional number`

102 

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

104 chat completion. This value can be used to control

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

106 

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

108 not compatible with [o-series models](https://platform.openai.com/docs/guides/reasoning).

109 

110- `--metadata: optional map[string]`

111 

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

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

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

115 

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

117 with a maximum length of 512 characters.

118 

119- `--modality: optional array of "text" or "audio"`

120 

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

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

123 

124 `["text"]`

125 

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

127 [generate audio](https://platform.openai.com/docs/guides/audio). To request that this model generate

128 both text and audio responses, you can use:

129 

130 `["text", "audio"]`

131 

132- `--n: optional number`

133 

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

135 

136- `--parallel-tool-calls: optional boolean`

137 

138 Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use.

139 

140- `--prediction: optional object { content, type }`

141 

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

143 being regenerated.

144 

145- `--presence-penalty: optional number`

146 

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

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

149 to talk about new topics.

150 

151- `--prompt-cache-key: optional string`

152 

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

154 

155- `--prompt-cache-retention: optional "in_memory" or "24h"`

156 

157 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](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).

158 

159- `--reasoning-effort: optional "none" or "minimal" or "low" or 3 more`

160 

161 Constrains effort on reasoning for

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

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

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

165 on reasoning in a response.

166 

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

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

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

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

171 

172- `--response-format: optional ResponseFormatText or ResponseFormatJSONSchema or ResponseFormatJSONObject`

173 

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

175 

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

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

178 schema. Learn more in the [Structured Outputs

179 guide](https://platform.openai.com/docs/guides/structured-outputs).

180 

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

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

183 is preferred for models that support it.

184 

185- `--safety-identifier: optional string`

186 

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

188 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).

189 

190- `--seed: optional number`

191 

192 This feature is in Beta.

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

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

195 

196- `--service-tier: optional "auto" or "default" or "flex" or 2 more`

197 

198 Specifies the processing type used for serving the request.

199 

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

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

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

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

204 

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

206 

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

208 

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

210 

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

212 returned text will not contain the stop sequence.

213 

214- `--store: optional boolean`

215 

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

217 use in our [model distillation](https://platform.openai.com/docs/guides/distillation) or

218 [evals](https://platform.openai.com/docs/guides/evals) products.

219 

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

221 

222- `--stream-options: optional object { include_obfuscation, include_usage }`

223 

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

225 

226- `--temperature: optional number`

227 

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

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

230 

231- `--tool-choice: optional "none" or "auto" or "required" or ChatCompletionAllowedToolChoice or ChatCompletionNamedToolChoice or ChatCompletionNamedToolChoiceCustom`

232 

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

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

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

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

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

238 

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

240 

241- `--tool: optional array of ChatCompletionTool`

242 

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

244 [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) or

245 [function tools](https://platform.openai.com/docs/guides/function-calling).

246 

247- `--top-logprobs: optional number`

248 

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

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

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

252 requested.

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

254 

255- `--top-p: optional number`

256 

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

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

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

260 are considered.

261 

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

263 

264- `--user: optional string`

265 

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

267 A stable identifier for your end-users.

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

269 

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

271 

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

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

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

275 

276- `--web-search-options: optional object { search_context_size, user_location }`

277 

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

279 Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

280 

281### Returns

282 

283- `chat_completion: object { id, choices, created, 5 more }`

284 

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

286 

287 - `id: string`

288 

289 A unique identifier for the chat completion.

290 

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

292 

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

294 

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

296 

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

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

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

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

301 

302 - `"stop"`

303 

304 - `"length"`

305 

306 - `"tool_calls"`

307 

308 - `"content_filter"`

309 

310 - `"function_call"`

311 

312 - `index: number`

313 

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

315 

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

317 

318 Log probability information for the choice.

319 

320 - `content: array of ChatCompletionTokenLogprob`

321 

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

323 

324 - `token: string`

325 

326 The token.

327 

328 - `bytes: array of number`

329 

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

331 

332 - `logprob: number`

333 

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

335 

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

337 

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

339 

340 - `token: string`

341 

342 The token.

343 

344 - `bytes: array of number`

345 

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

347 

348 - `logprob: number`

349 

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

351 

352 - `refusal: array of ChatCompletionTokenLogprob`

353 

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

355 

356 - `token: string`

357 

358 The token.

359 

360 - `bytes: array of number`

361 

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

363 

364 - `logprob: number`

365 

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

367 

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

369 

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

371 

372 - `message: object { content, refusal, role, 4 more }`

373 

374 A chat completion message generated by the model.

375 

376 - `content: string`

377 

378 The contents of the message.

379 

380 - `refusal: string`

381 

382 The refusal message generated by the model.

383 

384 - `role: "assistant"`

385 

386 The role of the author of this message.

387 

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

389 

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

391 [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

392 

393 - `type: "url_citation"`

394 

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

396 

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

398 

399 A URL citation when using web search.

400 

401 - `end_index: number`

402 

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

404 

405 - `start_index: number`

406 

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

408 

409 - `title: string`

410 

411 The title of the web resource.

412 

413 - `url: string`

414 

415 The URL of the web resource.

416 

417 - `audio: optional object { id, data, expires_at, transcript }`

418 

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

420 about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).

421 

422 - `id: string`

423 

424 Unique identifier for this audio response.

425 

426 - `data: string`

427 

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

429 specified in the request.

430 

431 - `expires_at: number`

432 

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

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

435 conversations.

436 

437 - `transcript: string`

438 

439 Transcript of the audio generated by the model.

440 

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

442 

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

444 

445 - `arguments: string`

446 

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

448 

449 - `name: string`

450 

451 The name of the function to call.

452 

453 - `tool_calls: optional array of ChatCompletionMessageToolCall`

454 

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

456 

457 - `chat_completion_message_function_tool_call: object { id, function, type }`

458 

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

460 

461 - `id: string`

462 

463 The ID of the tool call.

464 

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

466 

467 The function that the model called.

468 

469 - `arguments: string`

470 

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

472 

473 - `name: string`

474 

475 The name of the function to call.

476 

477 - `type: "function"`

478 

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

480 

481 - `chat_completion_message_custom_tool_call: object { id, custom, type }`

482 

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

484 

485 - `id: string`

486 

487 The ID of the tool call.

488 

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

490 

491 The custom tool that the model called.

492 

493 - `input: string`

494 

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

496 

497 - `name: string`

498 

499 The name of the custom tool to call.

500 

501 - `type: "custom"`

502 

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

504 

505 - `created: number`

506 

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

508 

509 - `model: string`

510 

511 The model used for the chat completion.

512 

513 - `object: "chat.completion"`

514 

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

516 

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

518 

519 Specifies the processing type used for serving the request.

520 

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

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

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

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

525 

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

527 

528 - `"auto"`

529 

530 - `"default"`

531 

532 - `"flex"`

533 

534 - `"scale"`

535 

536 - `"priority"`

537 

538 - `system_fingerprint: optional string`

539 

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

541 

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

543 

544 - `usage: optional object { completion_tokens, prompt_tokens, total_tokens, 2 more }`

545 

546 Usage statistics for the completion request.

547 

548 - `completion_tokens: number`

549 

550 Number of tokens in the generated completion.

551 

552 - `prompt_tokens: number`

553 

554 Number of tokens in the prompt.

555 

556 - `total_tokens: number`

557 

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

559 

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

561 

562 Breakdown of tokens used in a completion.

563 

564 - `accepted_prediction_tokens: optional number`

565 

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

567 prediction that appeared in the completion.

568 

569 - `audio_tokens: optional number`

570 

571 Audio input tokens generated by the model.

572 

573 - `reasoning_tokens: optional number`

574 

575 Tokens generated by the model for reasoning.

576 

577 - `rejected_prediction_tokens: optional number`

578 

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

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

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

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

583 limits.

584 

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

586 

587 Breakdown of tokens used in the prompt.

588 

589 - `audio_tokens: optional number`

590 

591 Audio input tokens present in the prompt.

592 

593 - `cached_tokens: optional number`

594 

595 Cached tokens present in the prompt.

596 

597### Example

598 

599```cli

600openai chat:completions create \

601 --api-key 'My API Key' \

602 --message '{content: string, role: developer}' \

603 --model gpt-5.4

604```

605 

606#### Response

607 

608```json

609{

610 "id": "id",

611 "choices": [

612 {

613 "finish_reason": "stop",

614 "index": 0,

615 "logprobs": {

616 "content": [

617 {

618 "token": "token",

619 "bytes": [

620 0

621 ],

622 "logprob": 0,

623 "top_logprobs": [

624 {

625 "token": "token",

626 "bytes": [

627 0

628 ],

629 "logprob": 0

630 }

631 ]

632 }

633 ],

634 "refusal": [

635 {

636 "token": "token",

637 "bytes": [

638 0

639 ],

640 "logprob": 0,

641 "top_logprobs": [

642 {

643 "token": "token",

644 "bytes": [

645 0

646 ],

647 "logprob": 0

648 }

649 ]

650 }

651 ]

652 },

653 "message": {

654 "content": "content",

655 "refusal": "refusal",

656 "role": "assistant",

657 "annotations": [

658 {

659 "type": "url_citation",

660 "url_citation": {

661 "end_index": 0,

662 "start_index": 0,

663 "title": "title",

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

665 }

666 }

667 ],

668 "audio": {

669 "id": "id",

670 "data": "data",

671 "expires_at": 0,

672 "transcript": "transcript"

673 },

674 "function_call": {

675 "arguments": "arguments",

676 "name": "name"

677 },

678 "tool_calls": [

679 {

680 "id": "id",

681 "function": {

682 "arguments": "arguments",

683 "name": "name"

684 },

685 "type": "function"

686 }

687 ]

688 }

689 }

690 ],

691 "created": 0,

692 "model": "model",

693 "object": "chat.completion",

694 "service_tier": "auto",

695 "system_fingerprint": "system_fingerprint",

696 "usage": {

697 "completion_tokens": 0,

698 "prompt_tokens": 0,

699 "total_tokens": 0,

700 "completion_tokens_details": {

701 "accepted_prediction_tokens": 0,

702 "audio_tokens": 0,

703 "reasoning_tokens": 0,

704 "rejected_prediction_tokens": 0

705 },

706 "prompt_tokens_details": {

707 "audio_tokens": 0,

708 "cached_tokens": 0

709 }

710 }

711}

712```

713 

714## List Chat Completions

715 

716`$ openai chat:completions list`

717 

718**get** `/chat/completions`

719 

720List stored Chat Completions. Only Chat Completions that have been stored

721with the `store` parameter set to `true` will be returned.

722 

723### Parameters

724 

725- `--after: optional string`

726 

727 Identifier for the last chat completion from the previous pagination request.

728 

729- `--limit: optional number`

730 

731 Number of Chat Completions to retrieve.

732 

733- `--metadata: optional map[string]`

734 

735 A list of metadata keys to filter the Chat Completions by. Example:

736 

737 `metadata[key1]=value1&metadata[key2]=value2`

738 

739- `--model: optional string`

740 

741 The model used to generate the Chat Completions.

742 

743- `--order: optional "asc" or "desc"`

744 

745 Sort order for Chat Completions by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.

746 

747### Returns

748 

749- `ChatCompletionList: object { data, first_id, has_more, 2 more }`

750 

751 An object representing a list of Chat Completions.

752 

753 - `data: array of ChatCompletion`

754 

755 An array of chat completion objects.

756 

757 - `id: string`

758 

759 A unique identifier for the chat completion.

760 

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

762 

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

764 

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

766 

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

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

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

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

771 

772 - `"stop"`

773 

774 - `"length"`

775 

776 - `"tool_calls"`

777 

778 - `"content_filter"`

779 

780 - `"function_call"`

781 

782 - `index: number`

783 

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

785 

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

787 

788 Log probability information for the choice.

789 

790 - `content: array of ChatCompletionTokenLogprob`

791 

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

793 

794 - `token: string`

795 

796 The token.

797 

798 - `bytes: array of number`

799 

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

801 

802 - `logprob: number`

803 

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

805 

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

807 

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

809 

810 - `token: string`

811 

812 The token.

813 

814 - `bytes: array of number`

815 

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

817 

818 - `logprob: number`

819 

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

821 

822 - `refusal: array of ChatCompletionTokenLogprob`

823 

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

825 

826 - `token: string`

827 

828 The token.

829 

830 - `bytes: array of number`

831 

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

833 

834 - `logprob: number`

835 

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

837 

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

839 

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

841 

842 - `message: object { content, refusal, role, 4 more }`

843 

844 A chat completion message generated by the model.

845 

846 - `content: string`

847 

848 The contents of the message.

849 

850 - `refusal: string`

851 

852 The refusal message generated by the model.

853 

854 - `role: "assistant"`

855 

856 The role of the author of this message.

857 

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

859 

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

861 [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

862 

863 - `type: "url_citation"`

864 

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

866 

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

868 

869 A URL citation when using web search.

870 

871 - `end_index: number`

872 

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

874 

875 - `start_index: number`

876 

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

878 

879 - `title: string`

880 

881 The title of the web resource.

882 

883 - `url: string`

884 

885 The URL of the web resource.

886 

887 - `audio: optional object { id, data, expires_at, transcript }`

888 

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

890 about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).

891 

892 - `id: string`

893 

894 Unique identifier for this audio response.

895 

896 - `data: string`

897 

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

899 specified in the request.

900 

901 - `expires_at: number`

902 

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

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

905 conversations.

906 

907 - `transcript: string`

908 

909 Transcript of the audio generated by the model.

910 

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

912 

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

914 

915 - `arguments: string`

916 

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

918 

919 - `name: string`

920 

921 The name of the function to call.

922 

923 - `tool_calls: optional array of ChatCompletionMessageToolCall`

924 

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

926 

927 - `chat_completion_message_function_tool_call: object { id, function, type }`

928 

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

930 

931 - `id: string`

932 

933 The ID of the tool call.

934 

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

936 

937 The function that the model called.

938 

939 - `arguments: string`

940 

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

942 

943 - `name: string`

944 

945 The name of the function to call.

946 

947 - `type: "function"`

948 

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

950 

951 - `chat_completion_message_custom_tool_call: object { id, custom, type }`

952 

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

954 

955 - `id: string`

956 

957 The ID of the tool call.

958 

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

960 

961 The custom tool that the model called.

962 

963 - `input: string`

964 

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

966 

967 - `name: string`

968 

969 The name of the custom tool to call.

970 

971 - `type: "custom"`

972 

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

974 

975 - `created: number`

976 

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

978 

979 - `model: string`

980 

981 The model used for the chat completion.

982 

983 - `object: "chat.completion"`

984 

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

986 

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

988 

989 Specifies the processing type used for serving the request.

990 

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

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

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

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

995 

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

997 

998 - `"auto"`

999 

1000 - `"default"`

1001 

1002 - `"flex"`

1003 

1004 - `"scale"`

1005 

1006 - `"priority"`

1007 

1008 - `system_fingerprint: optional string`

1009 

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

1011 

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

1013 

1014 - `usage: optional object { completion_tokens, prompt_tokens, total_tokens, 2 more }`

1015 

1016 Usage statistics for the completion request.

1017 

1018 - `completion_tokens: number`

1019 

1020 Number of tokens in the generated completion.

1021 

1022 - `prompt_tokens: number`

1023 

1024 Number of tokens in the prompt.

1025 

1026 - `total_tokens: number`

1027 

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

1029 

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

1031 

1032 Breakdown of tokens used in a completion.

1033 

1034 - `accepted_prediction_tokens: optional number`

1035 

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

1037 prediction that appeared in the completion.

1038 

1039 - `audio_tokens: optional number`

1040 

1041 Audio input tokens generated by the model.

1042 

1043 - `reasoning_tokens: optional number`

1044 

1045 Tokens generated by the model for reasoning.

1046 

1047 - `rejected_prediction_tokens: optional number`

1048 

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

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

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

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

1053 limits.

1054 

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

1056 

1057 Breakdown of tokens used in the prompt.

1058 

1059 - `audio_tokens: optional number`

1060 

1061 Audio input tokens present in the prompt.

1062 

1063 - `cached_tokens: optional number`

1064 

1065 Cached tokens present in the prompt.

1066 

1067 - `first_id: string`

1068 

1069 The identifier of the first chat completion in the data array.

1070 

1071 - `has_more: boolean`

1072 

1073 Indicates whether there are more Chat Completions available.

1074 

1075 - `last_id: string`

1076 

1077 The identifier of the last chat completion in the data array.

1078 

1079 - `object: "list"`

1080 

1081 The type of this object. It is always set to "list".

1082 

1083### Example

1084 

1085```cli

1086openai chat:completions list \

1087 --api-key 'My API Key'

1088```

1089 

1090#### Response

1091 

1092```json

1093{

1094 "data": [

1095 {

1096 "id": "id",

1097 "choices": [

1098 {

1099 "finish_reason": "stop",

1100 "index": 0,

1101 "logprobs": {

1102 "content": [

1103 {

1104 "token": "token",

1105 "bytes": [

1106 0

1107 ],

1108 "logprob": 0,

1109 "top_logprobs": [

1110 {

1111 "token": "token",

1112 "bytes": [

1113 0

1114 ],

1115 "logprob": 0

1116 }

1117 ]

1118 }

1119 ],

1120 "refusal": [

1121 {

1122 "token": "token",

1123 "bytes": [

1124 0

1125 ],

1126 "logprob": 0,

1127 "top_logprobs": [

1128 {

1129 "token": "token",

1130 "bytes": [

1131 0

1132 ],

1133 "logprob": 0

1134 }

1135 ]

1136 }

1137 ]

1138 },

1139 "message": {

1140 "content": "content",

1141 "refusal": "refusal",

1142 "role": "assistant",

1143 "annotations": [

1144 {

1145 "type": "url_citation",

1146 "url_citation": {

1147 "end_index": 0,

1148 "start_index": 0,

1149 "title": "title",

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

1151 }

1152 }

1153 ],

1154 "audio": {

1155 "id": "id",

1156 "data": "data",

1157 "expires_at": 0,

1158 "transcript": "transcript"

1159 },

1160 "function_call": {

1161 "arguments": "arguments",

1162 "name": "name"

1163 },

1164 "tool_calls": [

1165 {

1166 "id": "id",

1167 "function": {

1168 "arguments": "arguments",

1169 "name": "name"

1170 },

1171 "type": "function"

1172 }

1173 ]

1174 }

1175 }

1176 ],

1177 "created": 0,

1178 "model": "model",

1179 "object": "chat.completion",

1180 "service_tier": "auto",

1181 "system_fingerprint": "system_fingerprint",

1182 "usage": {

1183 "completion_tokens": 0,

1184 "prompt_tokens": 0,

1185 "total_tokens": 0,

1186 "completion_tokens_details": {

1187 "accepted_prediction_tokens": 0,

1188 "audio_tokens": 0,

1189 "reasoning_tokens": 0,

1190 "rejected_prediction_tokens": 0

1191 },

1192 "prompt_tokens_details": {

1193 "audio_tokens": 0,

1194 "cached_tokens": 0

1195 }

1196 }

1197 }

1198 ],

1199 "first_id": "first_id",

1200 "has_more": true,

1201 "last_id": "last_id",

1202 "object": "list"

1203}

1204```

1205 

1206## Get chat completion

1207 

1208`$ openai chat:completions retrieve`

1209 

1210**get** `/chat/completions/{completion_id}`

1211 

1212Get a stored chat completion. Only Chat Completions that have been created

1213with the `store` parameter set to `true` will be returned.

1214 

1215### Parameters

1216 

1217- `--completion-id: string`

1218 

1219 The ID of the chat completion to retrieve.

1220 

1221### Returns

1222 

1223- `chat_completion: object { id, choices, created, 5 more }`

1224 

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

1226 

1227 - `id: string`

1228 

1229 A unique identifier for the chat completion.

1230 

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

1232 

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

1234 

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

1236 

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

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

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

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

1241 

1242 - `"stop"`

1243 

1244 - `"length"`

1245 

1246 - `"tool_calls"`

1247 

1248 - `"content_filter"`

1249 

1250 - `"function_call"`

1251 

1252 - `index: number`

1253 

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

1255 

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

1257 

1258 Log probability information for the choice.

1259 

1260 - `content: array of ChatCompletionTokenLogprob`

1261 

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

1263 

1264 - `token: string`

1265 

1266 The token.

1267 

1268 - `bytes: array of number`

1269 

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

1271 

1272 - `logprob: number`

1273 

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

1275 

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

1277 

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

1279 

1280 - `token: string`

1281 

1282 The token.

1283 

1284 - `bytes: array of number`

1285 

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

1287 

1288 - `logprob: number`

1289 

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

1291 

1292 - `refusal: array of ChatCompletionTokenLogprob`

1293 

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

1295 

1296 - `token: string`

1297 

1298 The token.

1299 

1300 - `bytes: array of number`

1301 

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

1303 

1304 - `logprob: number`

1305 

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

1307 

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

1309 

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

1311 

1312 - `message: object { content, refusal, role, 4 more }`

1313 

1314 A chat completion message generated by the model.

1315 

1316 - `content: string`

1317 

1318 The contents of the message.

1319 

1320 - `refusal: string`

1321 

1322 The refusal message generated by the model.

1323 

1324 - `role: "assistant"`

1325 

1326 The role of the author of this message.

1327 

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

1329 

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

1331 [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

1332 

1333 - `type: "url_citation"`

1334 

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

1336 

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

1338 

1339 A URL citation when using web search.

1340 

1341 - `end_index: number`

1342 

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

1344 

1345 - `start_index: number`

1346 

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

1348 

1349 - `title: string`

1350 

1351 The title of the web resource.

1352 

1353 - `url: string`

1354 

1355 The URL of the web resource.

1356 

1357 - `audio: optional object { id, data, expires_at, transcript }`

1358 

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

1360 about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).

1361 

1362 - `id: string`

1363 

1364 Unique identifier for this audio response.

1365 

1366 - `data: string`

1367 

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

1369 specified in the request.

1370 

1371 - `expires_at: number`

1372 

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

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

1375 conversations.

1376 

1377 - `transcript: string`

1378 

1379 Transcript of the audio generated by the model.

1380 

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

1382 

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

1384 

1385 - `arguments: string`

1386 

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

1388 

1389 - `name: string`

1390 

1391 The name of the function to call.

1392 

1393 - `tool_calls: optional array of ChatCompletionMessageToolCall`

1394 

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

1396 

1397 - `chat_completion_message_function_tool_call: object { id, function, type }`

1398 

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

1400 

1401 - `id: string`

1402 

1403 The ID of the tool call.

1404 

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

1406 

1407 The function that the model called.

1408 

1409 - `arguments: string`

1410 

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

1412 

1413 - `name: string`

1414 

1415 The name of the function to call.

1416 

1417 - `type: "function"`

1418 

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

1420 

1421 - `chat_completion_message_custom_tool_call: object { id, custom, type }`

1422 

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

1424 

1425 - `id: string`

1426 

1427 The ID of the tool call.

1428 

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

1430 

1431 The custom tool that the model called.

1432 

1433 - `input: string`

1434 

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

1436 

1437 - `name: string`

1438 

1439 The name of the custom tool to call.

1440 

1441 - `type: "custom"`

1442 

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

1444 

1445 - `created: number`

1446 

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

1448 

1449 - `model: string`

1450 

1451 The model used for the chat completion.

1452 

1453 - `object: "chat.completion"`

1454 

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

1456 

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

1458 

1459 Specifies the processing type used for serving the request.

1460 

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

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

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

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

1465 

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

1467 

1468 - `"auto"`

1469 

1470 - `"default"`

1471 

1472 - `"flex"`

1473 

1474 - `"scale"`

1475 

1476 - `"priority"`

1477 

1478 - `system_fingerprint: optional string`

1479 

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

1481 

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

1483 

1484 - `usage: optional object { completion_tokens, prompt_tokens, total_tokens, 2 more }`

1485 

1486 Usage statistics for the completion request.

1487 

1488 - `completion_tokens: number`

1489 

1490 Number of tokens in the generated completion.

1491 

1492 - `prompt_tokens: number`

1493 

1494 Number of tokens in the prompt.

1495 

1496 - `total_tokens: number`

1497 

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

1499 

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

1501 

1502 Breakdown of tokens used in a completion.

1503 

1504 - `accepted_prediction_tokens: optional number`

1505 

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

1507 prediction that appeared in the completion.

1508 

1509 - `audio_tokens: optional number`

1510 

1511 Audio input tokens generated by the model.

1512 

1513 - `reasoning_tokens: optional number`

1514 

1515 Tokens generated by the model for reasoning.

1516 

1517 - `rejected_prediction_tokens: optional number`

1518 

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

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

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

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

1523 limits.

1524 

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

1526 

1527 Breakdown of tokens used in the prompt.

1528 

1529 - `audio_tokens: optional number`

1530 

1531 Audio input tokens present in the prompt.

1532 

1533 - `cached_tokens: optional number`

1534 

1535 Cached tokens present in the prompt.

1536 

1537### Example

1538 

1539```cli

1540openai chat:completions retrieve \

1541 --api-key 'My API Key' \

1542 --completion-id completion_id

1543```

1544 

1545#### Response

1546 

1547```json

1548{

1549 "id": "id",

1550 "choices": [

1551 {

1552 "finish_reason": "stop",

1553 "index": 0,

1554 "logprobs": {

1555 "content": [

1556 {

1557 "token": "token",

1558 "bytes": [

1559 0

1560 ],

1561 "logprob": 0,

1562 "top_logprobs": [

1563 {

1564 "token": "token",

1565 "bytes": [

1566 0

1567 ],

1568 "logprob": 0

1569 }

1570 ]

1571 }

1572 ],

1573 "refusal": [

1574 {

1575 "token": "token",

1576 "bytes": [

1577 0

1578 ],

1579 "logprob": 0,

1580 "top_logprobs": [

1581 {

1582 "token": "token",

1583 "bytes": [

1584 0

1585 ],

1586 "logprob": 0

1587 }

1588 ]

1589 }

1590 ]

1591 },

1592 "message": {

1593 "content": "content",

1594 "refusal": "refusal",

1595 "role": "assistant",

1596 "annotations": [

1597 {

1598 "type": "url_citation",

1599 "url_citation": {

1600 "end_index": 0,

1601 "start_index": 0,

1602 "title": "title",

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

1604 }

1605 }

1606 ],

1607 "audio": {

1608 "id": "id",

1609 "data": "data",

1610 "expires_at": 0,

1611 "transcript": "transcript"

1612 },

1613 "function_call": {

1614 "arguments": "arguments",

1615 "name": "name"

1616 },

1617 "tool_calls": [

1618 {

1619 "id": "id",

1620 "function": {

1621 "arguments": "arguments",

1622 "name": "name"

1623 },

1624 "type": "function"

1625 }

1626 ]

1627 }

1628 }

1629 ],

1630 "created": 0,

1631 "model": "model",

1632 "object": "chat.completion",

1633 "service_tier": "auto",

1634 "system_fingerprint": "system_fingerprint",

1635 "usage": {

1636 "completion_tokens": 0,

1637 "prompt_tokens": 0,

1638 "total_tokens": 0,

1639 "completion_tokens_details": {

1640 "accepted_prediction_tokens": 0,

1641 "audio_tokens": 0,

1642 "reasoning_tokens": 0,

1643 "rejected_prediction_tokens": 0

1644 },

1645 "prompt_tokens_details": {

1646 "audio_tokens": 0,

1647 "cached_tokens": 0

1648 }

1649 }

1650}

1651```

1652 

1653## Update chat completion

1654 

1655`$ openai chat:completions update`

1656 

1657**post** `/chat/completions/{completion_id}`

1658 

1659Modify a stored chat completion. Only Chat Completions that have been

1660created with the `store` parameter set to `true` can be modified. Currently,

1661the only supported modification is to update the `metadata` field.

1662 

1663### Parameters

1664 

1665- `--completion-id: string`

1666 

1667 The ID of the chat completion to update.

1668 

1669- `--metadata: map[string]`

1670 

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

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

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

1674 

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

1676 with a maximum length of 512 characters.

1677 

1678### Returns

1679 

1680- `chat_completion: object { id, choices, created, 5 more }`

1681 

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

1683 

1684 - `id: string`

1685 

1686 A unique identifier for the chat completion.

1687 

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

1689 

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

1691 

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

1693 

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

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

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

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

1698 

1699 - `"stop"`

1700 

1701 - `"length"`

1702 

1703 - `"tool_calls"`

1704 

1705 - `"content_filter"`

1706 

1707 - `"function_call"`

1708 

1709 - `index: number`

1710 

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

1712 

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

1714 

1715 Log probability information for the choice.

1716 

1717 - `content: array of ChatCompletionTokenLogprob`

1718 

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

1720 

1721 - `token: string`

1722 

1723 The token.

1724 

1725 - `bytes: array of number`

1726 

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

1728 

1729 - `logprob: number`

1730 

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

1732 

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

1734 

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

1736 

1737 - `token: string`

1738 

1739 The token.

1740 

1741 - `bytes: array of number`

1742 

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

1744 

1745 - `logprob: number`

1746 

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

1748 

1749 - `refusal: array of ChatCompletionTokenLogprob`

1750 

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

1752 

1753 - `token: string`

1754 

1755 The token.

1756 

1757 - `bytes: array of number`

1758 

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

1760 

1761 - `logprob: number`

1762 

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

1764 

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

1766 

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

1768 

1769 - `message: object { content, refusal, role, 4 more }`

1770 

1771 A chat completion message generated by the model.

1772 

1773 - `content: string`

1774 

1775 The contents of the message.

1776 

1777 - `refusal: string`

1778 

1779 The refusal message generated by the model.

1780 

1781 - `role: "assistant"`

1782 

1783 The role of the author of this message.

1784 

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

1786 

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

1788 [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

1789 

1790 - `type: "url_citation"`

1791 

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

1793 

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

1795 

1796 A URL citation when using web search.

1797 

1798 - `end_index: number`

1799 

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

1801 

1802 - `start_index: number`

1803 

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

1805 

1806 - `title: string`

1807 

1808 The title of the web resource.

1809 

1810 - `url: string`

1811 

1812 The URL of the web resource.

1813 

1814 - `audio: optional object { id, data, expires_at, transcript }`

1815 

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

1817 about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).

1818 

1819 - `id: string`

1820 

1821 Unique identifier for this audio response.

1822 

1823 - `data: string`

1824 

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

1826 specified in the request.

1827 

1828 - `expires_at: number`

1829 

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

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

1832 conversations.

1833 

1834 - `transcript: string`

1835 

1836 Transcript of the audio generated by the model.

1837 

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

1839 

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

1841 

1842 - `arguments: string`

1843 

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

1845 

1846 - `name: string`

1847 

1848 The name of the function to call.

1849 

1850 - `tool_calls: optional array of ChatCompletionMessageToolCall`

1851 

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

1853 

1854 - `chat_completion_message_function_tool_call: object { id, function, type }`

1855 

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

1857 

1858 - `id: string`

1859 

1860 The ID of the tool call.

1861 

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

1863 

1864 The function that the model called.

1865 

1866 - `arguments: string`

1867 

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

1869 

1870 - `name: string`

1871 

1872 The name of the function to call.

1873 

1874 - `type: "function"`

1875 

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

1877 

1878 - `chat_completion_message_custom_tool_call: object { id, custom, type }`

1879 

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

1881 

1882 - `id: string`

1883 

1884 The ID of the tool call.

1885 

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

1887 

1888 The custom tool that the model called.

1889 

1890 - `input: string`

1891 

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

1893 

1894 - `name: string`

1895 

1896 The name of the custom tool to call.

1897 

1898 - `type: "custom"`

1899 

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

1901 

1902 - `created: number`

1903 

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

1905 

1906 - `model: string`

1907 

1908 The model used for the chat completion.

1909 

1910 - `object: "chat.completion"`

1911 

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

1913 

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

1915 

1916 Specifies the processing type used for serving the request.

1917 

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

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

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

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

1922 

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

1924 

1925 - `"auto"`

1926 

1927 - `"default"`

1928 

1929 - `"flex"`

1930 

1931 - `"scale"`

1932 

1933 - `"priority"`

1934 

1935 - `system_fingerprint: optional string`

1936 

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

1938 

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

1940 

1941 - `usage: optional object { completion_tokens, prompt_tokens, total_tokens, 2 more }`

1942 

1943 Usage statistics for the completion request.

1944 

1945 - `completion_tokens: number`

1946 

1947 Number of tokens in the generated completion.

1948 

1949 - `prompt_tokens: number`

1950 

1951 Number of tokens in the prompt.

1952 

1953 - `total_tokens: number`

1954 

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

1956 

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

1958 

1959 Breakdown of tokens used in a completion.

1960 

1961 - `accepted_prediction_tokens: optional number`

1962 

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

1964 prediction that appeared in the completion.

1965 

1966 - `audio_tokens: optional number`

1967 

1968 Audio input tokens generated by the model.

1969 

1970 - `reasoning_tokens: optional number`

1971 

1972 Tokens generated by the model for reasoning.

1973 

1974 - `rejected_prediction_tokens: optional number`

1975 

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

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

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

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

1980 limits.

1981 

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

1983 

1984 Breakdown of tokens used in the prompt.

1985 

1986 - `audio_tokens: optional number`

1987 

1988 Audio input tokens present in the prompt.

1989 

1990 - `cached_tokens: optional number`

1991 

1992 Cached tokens present in the prompt.

1993 

1994### Example

1995 

1996```cli