resources/chat/subresources/completions/methods/update/index.md +0 −522 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`
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, 5 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
45 - `"stop"`
46
47 - `"length"`
48
49 - `"tool_calls"`
50
51 - `"content_filter"`
52
53 - `"function_call"`
54
55 - `index: number`
56
57 The index of the choice in the list of choices.
58
59 - `logprobs: object { content, refusal }`
60
61 Log probability information for the choice.
62
63 - `content: array of ChatCompletionTokenLogprob`
64
65 A list of message content tokens with log probability information.
66
67 - `token: string`
68
69 The token.
70
71 - `bytes: array of number`
72
73 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.
74
75 - `logprob: number`
76
77 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.
78
79 - `top_logprobs: array of object { token, bytes, logprob }`
80
81 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`.
82
83 - `token: string`
84
85 The token.
86
87 - `bytes: array of number`
88
89 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.
90
91 - `logprob: number`
92
93 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.
94
95 - `refusal: array of ChatCompletionTokenLogprob`
96
97 A list of message refusal tokens with log probability information.
98
99 - `token: string`
100
101 The token.
102
103 - `bytes: array of number`
104
105 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.
106
107 - `logprob: number`
108
109 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.
110
111 - `top_logprobs: array of object { token, bytes, logprob }`
112
113 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`.
114
115 - `message: ChatCompletionMessage`
116
117 A chat completion message generated by the model.
118
119 - `content: string`
120
121 The contents of the message.
122
123 - `refusal: string`
124
125 The refusal message generated by the model.
126
127 - `role: "assistant"`
128
129 The role of the author of this message.
130
131 - `"assistant"`
132
133 - `annotations: optional array of object { type, url_citation }`
134
135 Annotations for the message, when applicable, as when using the
136 [web search tool](/docs/guides/tools-web-search?api-mode=chat).
137
138 - `type: "url_citation"`
139
140 The type of the URL citation. Always `url_citation`.
141
142 - `"url_citation"`
143
144 - `url_citation: object { end_index, start_index, title, url }`
145
146 A URL citation when using web search.
147
148 - `end_index: number`
149
150 The index of the last character of the URL citation in the message.
151
152 - `start_index: number`
153
154 The index of the first character of the URL citation in the message.
155
156 - `title: string`
157
158 The title of the web resource.
159
160 - `url: string`
161
162 The URL of the web resource.
163
164 - `audio: optional ChatCompletionAudio`
165
166 If the audio output modality is requested, this object contains data
167 about the audio response from the model. [Learn more](/docs/guides/audio).
168
169 - `id: string`
170
171 Unique identifier for this audio response.
172
173 - `data: string`
174
175 Base64 encoded audio bytes generated by the model, in the format
176 specified in the request.
177
178 - `expires_at: number`
179
180 The Unix timestamp (in seconds) for when this audio response will
181 no longer be accessible on the server for use in multi-turn
182 conversations.
183
184 - `transcript: string`
185
186 Transcript of the audio generated by the model.
187
188 - `function_call: optional object { arguments, name }`
189
190 Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
191
192 - `arguments: string`
193
194 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.
195
196 - `name: string`
197
198 The name of the function to call.
199
200 - `tool_calls: optional array of ChatCompletionMessageToolCall`
201
202 The tool calls generated by the model, such as function calls.
203
204 - `ChatCompletionMessageFunctionToolCall object { id, function, type }`
205
206 A call to a function tool created by the model.
207
208 - `id: string`
209
210 The ID of the tool call.
211
212 - `function: object { arguments, name }`
213
214 The function that the model called.
215
216 - `arguments: string`
217
218 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.
219
220 - `name: string`
221
222 The name of the function to call.
223
224 - `type: "function"`
225
226 The type of the tool. Currently, only `function` is supported.
227
228 - `"function"`
229
230 - `ChatCompletionMessageCustomToolCall object { id, custom, type }`
231
232 A call to a custom tool created by the model.
233
234 - `id: string`
235
236 The ID of the tool call.
237
238 - `custom: object { input, name }`
239
240 The custom tool that the model called.
241
242 - `input: string`
243
244 The input for the custom tool call generated by the model.
245
246 - `name: string`
247
248 The name of the custom tool to call.
249
250 - `type: "custom"`
251
252 The type of the tool. Always `custom`.
253
254 - `"custom"`
255
256 - `created: number`
257
258 The Unix timestamp (in seconds) of when the chat completion was created.
259
260 - `model: string`
261
262 The model used for the chat completion.
263
264 - `object: "chat.completion"`
265
266 The object type, which is always `chat.completion`.
267
268 - `"chat.completion"`
269
270 - `service_tier: optional "auto" or "default" or "flex" or 2 more`
271
272 Specifies the processing type used for serving the request.
273
274 - 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'.
275 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.
276 - 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.
277 - When not set, the default behavior is 'auto'.
278
279 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.
280
281 - `"auto"`
282
283 - `"default"`
284
285 - `"flex"`
286
287 - `"scale"`
288
289 - `"priority"`
290
291 - `system_fingerprint: optional string`
292
293 This fingerprint represents the backend configuration that the model runs with.
294
295 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.
296
297 - `usage: optional CompletionUsage`
298
299 Usage statistics for the completion request.
300
301 - `completion_tokens: number`
302
303 Number of tokens in the generated completion.
304
305 - `prompt_tokens: number`
306
307 Number of tokens in the prompt.
308
309 - `total_tokens: number`
310
311 Total number of tokens used in the request (prompt + completion).
312
313 - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, rejected_prediction_tokens }`
314
315 Breakdown of tokens used in a completion.
316
317 - `accepted_prediction_tokens: optional number`
318
319 When using Predicted Outputs, the number of tokens in the
320 prediction that appeared in the completion.
321
322 - `audio_tokens: optional number`
323
324 Audio input tokens generated by the model.
325
326 - `reasoning_tokens: optional number`
327
328 Tokens generated by the model for reasoning.
329
330 - `rejected_prediction_tokens: optional number`
331
332 When using Predicted Outputs, the number of tokens in the
333 prediction that did not appear in the completion. However, like
334 reasoning tokens, these tokens are still counted in the total
335 completion tokens for purposes of billing, output, and context window
336 limits.
337
338 - `prompt_tokens_details: optional object { audio_tokens, cached_tokens }`
339
340 Breakdown of tokens used in the prompt.
341
342 - `audio_tokens: optional number`
343
344 Audio input tokens present in the prompt.
345
346 - `cached_tokens: optional number`
347
348 Cached tokens present in the prompt.
349
350### Example
351
352```http
353curl https://api.openai.com/v1/chat/completions/$COMPLETION_ID \
354 -H 'Content-Type: application/json' \
355 -H "Authorization: Bearer $OPENAI_API_KEY" \
356 -d '{
357 "metadata": {
358 "foo": "string"
359 }
360 }'
361```
362
363#### Response
364
365```json
366{
367 "id": "id",
368 "choices": [
369 {
370 "finish_reason": "stop",
371 "index": 0,
372 "logprobs": {
373 "content": [
374 {
375 "token": "token",
376 "bytes": [
377 0
378 ],
379 "logprob": 0,
380 "top_logprobs": [
381 {
382 "token": "token",
383 "bytes": [
384 0
385 ],
386 "logprob": 0
387 }
388 ]
389 }
390 ],
391 "refusal": [
392 {
393 "token": "token",
394 "bytes": [
395 0
396 ],
397 "logprob": 0,
398 "top_logprobs": [
399 {
400 "token": "token",
401 "bytes": [
402 0
403 ],
404 "logprob": 0
405 }
406 ]
407 }
408 ]
409 },
410 "message": {
411 "content": "content",
412 "refusal": "refusal",
413 "role": "assistant",
414 "annotations": [
415 {
416 "type": "url_citation",
417 "url_citation": {
418 "end_index": 0,
419 "start_index": 0,
420 "title": "title",
421 "url": "https://example.com"
422 }
423 }
424 ],
425 "audio": {
426 "id": "id",
427 "data": "data",
428 "expires_at": 0,
429 "transcript": "transcript"
430 },
431 "function_call": {
432 "arguments": "arguments",
433 "name": "name"
434 },
435 "tool_calls": [
436 {
437 "id": "id",
438 "function": {
439 "arguments": "arguments",
440 "name": "name"
441 },
442 "type": "function"
443 }
444 ]
445 }
446 }
447 ],
448 "created": 0,
449 "model": "model",
450 "object": "chat.completion",
451 "service_tier": "auto",
452 "system_fingerprint": "system_fingerprint",
453 "usage": {
454 "completion_tokens": 0,
455 "prompt_tokens": 0,
456 "total_tokens": 0,
457 "completion_tokens_details": {
458 "accepted_prediction_tokens": 0,
459 "audio_tokens": 0,
460 "reasoning_tokens": 0,
461 "rejected_prediction_tokens": 0
462 },
463 "prompt_tokens_details": {
464 "audio_tokens": 0,
465 "cached_tokens": 0
466 }
467 }
468}
469```
470
471### Example
472
473```http
474curl -X POST https://api.openai.com/v1/chat/completions/chat_abc123 \
475 -H "Authorization: Bearer $OPENAI_API_KEY" \
476 -H "Content-Type: application/json" \
477 -d '{"metadata": {"foo": "bar"}}'
478```
479
480#### Response
481
482```json
483{
484 "object": "chat.completion",
485 "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
486 "model": "gpt-4o-2024-08-06",
487 "created": 1738960610,
488 "request_id": "req_ded8ab984ec4bf840f37566c1011c417",
489 "tool_choice": null,
490 "usage": {
491 "total_tokens": 31,
492 "completion_tokens": 18,
493 "prompt_tokens": 13
494 },
495 "seed": 4944116822809979520,
496 "top_p": 1.0,
497 "temperature": 1.0,
498 "presence_penalty": 0.0,
499 "frequency_penalty": 0.0,
500 "system_fingerprint": "fp_50cad350e4",
501 "input_user": null,
502 "service_tier": "default",
503 "tools": null,
504 "metadata": {
505 "foo": "bar"
506 },
507 "choices": [
508 {
509 "index": 0,
510 "message": {
511 "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.",
512 "role": "assistant",
513 "tool_calls": null,
514 "function_call": null
515 },
516 "finish_reason": "stop",
517 "logprobs": null
518 }
519 ],
520 "response_format": null
521}
522```