resources/chat/subresources/completions/methods/update/index.md +0 −749 deleted
File Deleted View Diff
1## Update chat completion
2
3**post** `/chat/completions/{completion_id}`
4
5Modify a stored chat completion. Only Chat Completions that have been
6created with the `store` parameter set to `true` can be modified. Currently,
7the only supported modification is to update the `metadata` field.
8
9### Path Parameters
10
11- `completion_id: string`
12
13### Body Parameters
14
15- `metadata: Metadata or null`
16
17 Set of 16 key-value pairs that can be attached to an object. This can be
18 useful for storing additional information about the object in a structured
19 format, and querying for objects via API or the dashboard.
20
21 Keys are strings with a maximum length of 64 characters. Values are strings
22 with a maximum length of 512 characters.
23
24### Returns
25
26- `ChatCompletion object { id, choices, created, 7 more }`
27
28 Represents a chat completion response returned by model, based on the provided input.
29
30 - `id: string`
31
32 A unique identifier for the chat completion.
33
34 - `choices: array of object { finish_reason, index, logprobs, message }`
35
36 A list of chat completion choices. Can be more than one if `n` is greater than 1.
37
38 - `finish_reason: "stop" or "length" or "tool_calls" or 2 more`
39
40 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
41 `length` if the maximum number of tokens specified in the request was reached,
42 `content_filter` if content was omitted due to a flag from our content filters,
43 `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.
44 Read the [Model Spec](https://model-spec.openai.com/2025-12-18.html) for more.
45
46 - `"stop"`
47
48 - `"length"`
49
50 - `"tool_calls"`
51
52 - `"content_filter"`
53
54 - `"function_call"`
55
56 - `index: number`
57
58 The index of the choice in the list of choices.
59
60 - `logprobs: object { content, refusal } or null`
61
62 Log probability information for the choice.
63
64 - `content: array of ChatCompletionTokenLogprob or null`
65
66 A list of message content tokens with log probability information.
67
68 - `token: string`
69
70 The token.
71
72 - `bytes: array of number or null`
73
74 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.
75
76 - `logprob: number`
77
78 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.
79
80 - `top_logprobs: array of object { token, bytes, logprob }`
81
82 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`.
83
84 - `token: string`
85
86 The token.
87
88 - `bytes: array of number or null`
89
90 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.
91
92 - `logprob: number`
93
94 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.
95
96 - `refusal: array of ChatCompletionTokenLogprob or null`
97
98 A list of message refusal tokens with log probability information.
99
100 - `token: string`
101
102 The token.
103
104 - `bytes: array of number or null`
105
106 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.
107
108 - `logprob: number`
109
110 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.
111
112 - `top_logprobs: array of object { token, bytes, logprob }`
113
114 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`.
115
116 - `message: ChatCompletionMessage`
117
118 A chat completion message generated by the model.
119
120 - `content: string or null`
121
122 The contents of the message.
123
124 - `refusal: string or null`
125
126 The refusal message generated by the model.
127
128 - `role: "assistant"`
129
130 The role of the author of this message.
131
132 - `"assistant"`
133
134 - `annotations: optional array of object { type, url_citation }`
135
136 Annotations for the message, when applicable, as when using the
137 [web search tool](/api/docs/guides/tools-web-search).
138
139 - `type: "url_citation"`
140
141 The type of the URL citation. Always `url_citation`.
142
143 - `"url_citation"`
144
145 - `url_citation: object { end_index, start_index, title, url }`
146
147 A URL citation when using web search.
148
149 - `end_index: number`
150
151 The index of the last character of the URL citation in the message.
152
153 - `start_index: number`
154
155 The index of the first character of the URL citation in the message.
156
157 - `title: string`
158
159 The title of the web resource.
160
161 - `url: string`
162
163 The URL of the web resource.
164
165 - `audio: optional ChatCompletionAudio or null`
166
167 If the audio output modality is requested, this object contains data
168 about the audio response from the model. [Learn more](/api/docs/guides/audio).
169
170 - `id: string`
171
172 Unique identifier for this audio response.
173
174 - `data: string`
175
176 Base64 encoded audio bytes generated by the model, in the format
177 specified in the request.
178
179 - `expires_at: number`
180
181 The Unix timestamp (in seconds) for when this audio response will
182 no longer be accessible on the server for use in multi-turn
183 conversations.
184
185 - `transcript: string`
186
187 Transcript of the audio generated by the model.
188
189 - `function_call: optional object { arguments, name }`
190
191 Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
192
193 - `arguments: string`
194
195 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.
196
197 - `name: string`
198
199 The name of the function to call.
200
201 - `tool_calls: optional array of ChatCompletionMessageToolCall`
202
203 The tool calls generated by the model, such as function calls.
204
205 - `ChatCompletionMessageFunctionToolCall object { id, function, type }`
206
207 A call to a function tool created by the model.
208
209 - `id: string`
210
211 The ID of the tool call.
212
213 - `function: object { arguments, name }`
214
215 The function that the model called.
216
217 - `arguments: string`
218
219 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.
220
221 - `name: string`
222
223 The name of the function to call.
224
225 - `type: "function"`
226
227 The type of the tool. Currently, only `function` is supported.
228
229 - `"function"`
230
231 - `ChatCompletionMessageCustomToolCall object { id, custom, type }`
232
233 A call to a custom tool created by the model.
234
235 - `id: string`
236
237 The ID of the tool call.
238
239 - `custom: object { input, name }`
240
241 The custom tool that the model called.
242
243 - `input: string`
244
245 The input for the custom tool call generated by the model.
246
247 - `name: string`
248
249 The name of the custom tool to call.
250
251 - `type: "custom"`
252
253 The type of the tool. Always `custom`.
254
255 - `"custom"`
256
257 - `created: number`
258
259 The Unix timestamp (in seconds) of when the chat completion was created.
260
261 - `model: string`
262
263 The model used for the chat completion.
264
265 - `object: "chat.completion"`
266
267 The object type, which is always `chat.completion`.
268
269 - `"chat.completion"`
270
271 - `metadata: optional Metadata or null`
272
273 Set of 16 key-value pairs that can be attached to an object. This can be
274 useful for storing additional information about the object in a structured
275 format, and querying for objects via API or the dashboard.
276
277 Keys are strings with a maximum length of 64 characters. Values are strings
278 with a maximum length of 512 characters.
279
280 - `moderation: optional object { input, output } or null`
281
282 Moderation results for the request input and generated output, if moderated
283 completions were requested.
284
285 - `input: object { model, results, type } or object { code, message, type }`
286
287 Moderation for the request input.
288
289 - `ModerationResults object { model, results, type }`
290
291 Successful moderation results for the request input or generated output.
292
293 - `model: string`
294
295 The moderation model used to generate the results.
296
297 - `results: array of object { categories, category_applied_input_types, category_scores, 3 more }`
298
299 A list of moderation results.
300
301 - `categories: map[boolean]`
302
303 A dictionary of moderation categories to booleans, True if the input is flagged under this category.
304
305 - `category_applied_input_types: map[array of "text" or "image"]`
306
307 Which modalities of input are reflected by the score for each category.
308
309 - `"text"`
310
311 - `"image"`
312
313 - `category_scores: map[number]`
314
315 A dictionary of moderation categories to scores.
316
317 - `flagged: boolean`
318
319 A boolean indicating whether the content was flagged by any category.
320
321 - `model: string`
322
323 The moderation model that produced this result.
324
325 - `type: "moderation_result"`
326
327 The object type, which was always `moderation_result` for successful moderation results.
328
329 - `"moderation_result"`
330
331 - `type: "moderation_results"`
332
333 The object type, which is always `moderation_results`.
334
335 - `"moderation_results"`
336
337 - `Error object { code, message, type }`
338
339 An error produced while attempting moderation.
340
341 - `code: string`
342
343 The error code.
344
345 - `message: string`
346
347 The error message.
348
349 - `type: "error"`
350
351 The object type, which is always `error`.
352
353 - `"error"`
354
355 - `output: object { model, results, type } or object { code, message, type }`
356
357 Moderation for the generated output.
358
359 - `ModerationResults object { model, results, type }`
360
361 Successful moderation results for the request input or generated output.
362
363 - `model: string`
364
365 The moderation model used to generate the results.
366
367 - `results: array of object { categories, category_applied_input_types, category_scores, 3 more }`
368
369 A list of moderation results.
370
371 - `categories: map[boolean]`
372
373 A dictionary of moderation categories to booleans, True if the input is flagged under this category.
374
375 - `category_applied_input_types: map[array of "text" or "image"]`
376
377 Which modalities of input are reflected by the score for each category.
378
379 - `"text"`
380
381 - `"image"`
382
383 - `category_scores: map[number]`
384
385 A dictionary of moderation categories to scores.
386
387 - `flagged: boolean`
388
389 A boolean indicating whether the content was flagged by any category.
390
391 - `model: string`
392
393 The moderation model that produced this result.
394
395 - `type: "moderation_result"`
396
397 The object type, which was always `moderation_result` for successful moderation results.
398
399 - `"moderation_result"`
400
401 - `type: "moderation_results"`
402
403 The object type, which is always `moderation_results`.
404
405 - `"moderation_results"`
406
407 - `Error object { code, message, type }`
408
409 An error produced while attempting moderation.
410
411 - `code: string`
412
413 The error code.
414
415 - `message: string`
416
417 The error message.
418
419 - `type: "error"`
420
421 The object type, which is always `error`.
422
423 - `"error"`
424
425 - `service_tier: optional "auto" or "default" or "flex" or 3 more or null`
426
427 Specifies the processing type used for serving the request.
428
429 - 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'.
430 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.
431 - If set to '[flex](/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier.
432 - To opt-in to [Fast mode](/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. The response will show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority` in your request.
433 - When not set, the default behavior is 'auto'.
434
435 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.
436
437 - `"auto"`
438
439 - `"default"`
440
441 - `"flex"`
442
443 - `"scale"`
444
445 - `"priority"`
446
447 - `"fast"`
448
449 - `system_fingerprint: optional string`
450
451 This fingerprint represents the backend configuration that the model runs with.
452
453 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.
454
455 - `usage: optional CompletionUsage`
456
457 Usage statistics for the completion request.
458
459 - `completion_tokens: number`
460
461 Number of tokens in the generated completion.
462
463 - `prompt_tokens: number`
464
465 Number of tokens in the prompt.
466
467 - `total_tokens: number`
468
469 Total number of tokens used in the request (prompt + completion).
470
471 - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, 2 more }`
472
473 Breakdown of tokens used in a completion.
474
475 - `accepted_prediction_tokens: optional number`
476
477 When using Predicted Outputs, the number of tokens in the
478 prediction that appeared in the completion.
479
480 - `audio_tokens: optional number`
481
482 Audio input tokens generated by the model.
483
484 - `reasoning_tokens: optional number`
485
486 Tokens generated by the model for reasoning.
487
488 - `rejected_prediction_tokens: optional number`
489
490 When using Predicted Outputs, the number of tokens in the
491 prediction that did not appear in the completion. However, like
492 reasoning tokens, these tokens are still counted in the total
493 completion tokens for purposes of billing, output, and context window
494 limits.
495
496 - `text_tokens: optional number`
497
498 Text output tokens generated by the model.
499
500 - `prompt_tokens_details: optional object { audio_tokens, cache_write_tokens, cached_tokens, 2 more }`
501
502 Breakdown of tokens used in the prompt.
503
504 - `audio_tokens: optional number`
505
506 Audio input tokens present in the prompt.
507
508 - `cache_write_tokens: optional number`
509
510 The unadjusted number of prompt tokens written to cache.
511
512 - `cached_tokens: optional number`
513
514 Cached tokens present in the prompt.
515
516 - `image_tokens: optional number`
517
518 Image input tokens present in the prompt.
519
520 - `text_tokens: optional number`
521
522 Text input tokens present in the prompt.
523
524### Example
525
526```http
527curl https://api.openai.com/v1/chat/completions/$COMPLETION_ID \
528 -H 'Content-Type: application/json' \
529 -H "Authorization: Bearer $OPENAI_API_KEY" \
530 -d '{
531 "metadata": {
532 "foo": "string"
533 }
534 }'
535```
536
537#### Response
538
539```json
540{
541 "id": "id",
542 "choices": [
543 {
544 "finish_reason": "stop",
545 "index": 0,
546 "logprobs": {
547 "content": [
548 {
549 "token": "token",
550 "bytes": [
551 0
552 ],
553 "logprob": 0,
554 "top_logprobs": [
555 {
556 "token": "token",
557 "bytes": [
558 0
559 ],
560 "logprob": 0
561 }
562 ]
563 }
564 ],
565 "refusal": [
566 {
567 "token": "token",
568 "bytes": [
569 0
570 ],
571 "logprob": 0,
572 "top_logprobs": [
573 {
574 "token": "token",
575 "bytes": [
576 0
577 ],
578 "logprob": 0
579 }
580 ]
581 }
582 ]
583 },
584 "message": {
585 "content": "content",
586 "refusal": "refusal",
587 "role": "assistant",
588 "annotations": [
589 {
590 "type": "url_citation",
591 "url_citation": {
592 "end_index": 0,
593 "start_index": 0,
594 "title": "title",
595 "url": "https://example.com"
596 }
597 }
598 ],
599 "audio": {
600 "id": "id",
601 "data": "data",
602 "expires_at": 0,
603 "transcript": "transcript"
604 },
605 "function_call": {
606 "arguments": "arguments",
607 "name": "name"
608 },
609 "tool_calls": [
610 {
611 "id": "id",
612 "function": {
613 "arguments": "arguments",
614 "name": "name"
615 },
616 "type": "function"
617 }
618 ]
619 }
620 }
621 ],
622 "created": 0,
623 "model": "model",
624 "object": "chat.completion",
625 "metadata": {
626 "foo": "string"
627 },
628 "moderation": {
629 "input": {
630 "model": "model",
631 "results": [
632 {
633 "categories": {
634 "foo": true
635 },
636 "category_applied_input_types": {
637 "foo": [
638 "text"
639 ]
640 },
641 "category_scores": {
642 "foo": 0
643 },
644 "flagged": true,
645 "model": "model",
646 "type": "moderation_result"
647 }
648 ],
649 "type": "moderation_results"
650 },
651 "output": {
652 "model": "model",
653 "results": [
654 {
655 "categories": {
656 "foo": true
657 },
658 "category_applied_input_types": {
659 "foo": [
660 "text"
661 ]
662 },
663 "category_scores": {
664 "foo": 0
665 },
666 "flagged": true,
667 "model": "model",
668 "type": "moderation_result"
669 }
670 ],
671 "type": "moderation_results"
672 }
673 },
674 "service_tier": "auto",
675 "system_fingerprint": "system_fingerprint",
676 "usage": {
677 "completion_tokens": 0,
678 "prompt_tokens": 0,
679 "total_tokens": 0,
680 "completion_tokens_details": {
681 "accepted_prediction_tokens": 0,
682 "audio_tokens": 0,
683 "reasoning_tokens": 0,
684 "rejected_prediction_tokens": 0,
685 "text_tokens": 0
686 },
687 "prompt_tokens_details": {
688 "audio_tokens": 0,
689 "cache_write_tokens": 0,
690 "cached_tokens": 0,
691 "image_tokens": 0,
692 "text_tokens": 0
693 }
694 }
695}
696```
697
698### Example
699
700```http
701curl -X POST https://api.openai.com/v1/chat/completions/chat_abc123 \
702 -H "Authorization: Bearer $OPENAI_API_KEY" \
703 -H "Content-Type: application/json" \
704 -d '{"metadata": {"foo": "bar"}}'
705```
706
707#### Response
708
709```json
710{
711 "object": "chat.completion",
712 "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
713 "model": "gpt-6-astra",
714 "created": 1738960610,
715 "request_id": "req_ded8ab984ec4bf840f37566c1011c417",
716 "tool_choice": null,
717 "usage": {
718 "total_tokens": 31,
719 "completion_tokens": 18,
720 "prompt_tokens": 13
721 },
722 "seed": 4944116822809979520,
723 "top_p": 1.0,
724 "temperature": 1.0,
725 "presence_penalty": 0.0,
726 "frequency_penalty": 0.0,
727 "system_fingerprint": "fp_50cad350e4",
728 "input_user": null,
729 "service_tier": "default",
730 "tools": null,
731 "metadata": {
732 "foo": "bar"
733 },
734 "choices": [
735 {
736 "index": 0,
737 "message": {
738 "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.",
739 "role": "assistant",
740 "tool_calls": null,
741 "function_call": null
742 },
743 "finish_reason": "stop",
744 "logprobs": null
745 }
746 ],
747 "response_format": null
748}
749```