TRAE-AI编程
OpenAI 更新聊天补全
更新聊天补全
post /chat/completions/{completion_id}
修改已存储的聊天补全。仅可修改创建时
将 store 参数设为 true 的聊天补全。目前
仅支持更新 metadata 字段。
路径参数
completion_id: string
要更新的聊天补全 ID。
请求体参数
内容类型为 application/json。
metadata: Metadata or null
可附加到对象的元数据，最多包含 16 组键值对，可 以结构化方式存储对象的额外信息， 并通过 API 或控制台查询对象。
键为最多 64 个字符的字符串，值为 最多 512 个字符的字符串。
返回值
ChatCompletion object { id, choices, created, 7 more }
表示模型根据输入返回的聊天补全响应。
id: string
聊天补全的唯一标识。
choices: array of object { finish_reason, index, logprobs, message }
聊天补全候选项列表。n 大于 1 时，可能包含多个候选项。
finish_reason: "stop" or "length" or "tool_calls" or 2 more
模型停止生成词元的原因。到达自然停止点或指定停止序列时为 stop，
达到请求中指定的最大词元数时为 length，
因内容过滤器标记而省略内容时为 content_filter，
调用工具时为 tool_calls，调用函数时为已弃用的 function_call。
详情参阅模型规范。
"stop"
"length"
"tool_calls"
"content_filter"
"function_call"
index: integer
候选项在列表中的索引。
logprobs: object { content, refusal } or null
候选项的对数概率信息。
content: array of ChatCompletionTokenLogprob or null
消息内容词元及其对数概率的列表。
token: string
词元。
bytes: array of number or null
表示词元 UTF-8 字节的整数列表。一个字符由多个词元表示、需要组合字节以正确还原文本时，此字段尤其有用。词元没有字节表示时可为 null。
logprob: number
若词元位于最可能的前 20 个词元内，此字段为其对数概率。否则以 -9999.0 表示该词元出现的可能性极低。
top_logprobs: array of object { token, bytes, logprob }
当前词元位置上最可能的词元及其对数概率列表，实际条目数可能少于请求的 top_logprobs。
token: string
词元。
bytes: array of number or null
表示词元 UTF-8 字节的整数列表。一个字符由多个词元表示、需要组合字节以正确还原文本时，此字段尤其有用。词元没有字节表示时可为 null。
logprob: number
若词元位于最可能的前 20 个词元内，此字段为其对数概率。否则以 -9999.0 表示该词元出现的可能性极低。
refusal: array of ChatCompletionTokenLogprob or null
拒绝响应词元及其对数概率列表。
token: string
词元。
bytes: array of number or null
表示词元 UTF-8 字节的整数列表。一个字符由多个词元表示、需要组合字节以正确还原文本时，此字段尤其有用。词元没有字节表示时可为 null。
logprob: number
若词元位于最可能的前 20 个词元内，此字段为其对数概率。否则以 -9999.0 表示该词元出现的可能性极低。
top_logprobs: array of object { token, bytes, logprob }
当前词元位置上最可能的词元及其对数概率列表，实际条目数可能少于请求的 top_logprobs。
message: ChatCompletionMessage
模型生成的聊天补全消息。
content: string or null
消息内容。
role: "assistant"
消息作者的角色。
"assistant"
annotations: optional array of object { type, url_citation }
消息注释，在适用时提供，例如使用 网络搜索工具时。
type: "url_citation"
URL 引用的类型，固定为 url_citation。
"url_citation"
url_citation: object { end_index, start_index, title, url }
使用网络搜索时的 URL 引用。
end_index: integer
URL 引用在消息中最后一个字符的索引。
start_index: integer
URL 引用在消息中第一个字符的索引。
title: string
网络资源标题。
url: string
网络资源 URL。
format: uri
audio: optional ChatCompletionAudio or null
请求音频输出模态时，此对象包含 模型音频响应的数据。参阅音频指南。
id: string
此音频响应的唯一标识。
data: string
模型生成的 Base64 编码音频字节，采用 请求指定的格式。
expires_at: integer
此音频响应不再能在服务端用于多轮 对话的时间，以 Unix 时间戳表示， 单位为秒。
format: unixtime
transcript: string
模型生成音频的转录文本。
function_call: optional object { arguments, name } or null
此字段已弃用，由 tool_calls 替代。它包含模型生成的待调用函数名称与参数。
arguments: string
模型以 JSON 格式生成的函数调用参数。模型可能生成无效 JSON，也可能虚构函数结构中未定义的参数。调用函数前，应在代码中验证这些参数。
name: string
要调用的函数名称。
refusal: optional string or null
模型生成的拒绝消息。
tool_calls: optional array of ChatCompletionMessageToolCall or null
模型生成的工具调用，例如函数调用。
ChatCompletionMessageFunctionToolCall object { id, function, type }
模型生成的函数工具调用。
id: string
工具调用 ID。
function: object { arguments, name }
模型调用的函数。
arguments: string
模型以 JSON 格式生成的函数调用参数。模型可能生成无效 JSON，也可能虚构函数结构中未定义的参数。调用函数前，应在代码中验证这些参数。
name: string
要调用的函数名称。
type: "function"
工具类型，目前仅支持 function。
"function"
ChatCompletionMessageCustomToolCall object { id, custom, type }
模型生成的自定义工具调用。
id: string
工具调用 ID。
custom: object { input, name }
模型调用的自定义工具。
input: string
模型生成的自定义工具调用输入。
name: string
要调用的自定义工具名称。
type: "custom"
工具类型，固定为 custom。
"custom"
created: integer
聊天补全创建时的 Unix 时间戳，单位为秒。
format: unixtime
model: string
聊天补全所使用的模型。
object: "chat.completion"
对象类型，固定为 chat.completion。
"chat.completion"
metadata: optional Metadata or null
可附加到对象的元数据，最多包含 16 组键值对，可 以结构化方式存储对象的额外信息， 并通过 API 或控制台查询对象。
键为最多 64 个字符的字符串，值为 最多 512 个字符的字符串。
moderation: optional object { input, output } or null
请求启用了审核补全时，提供请求输入与生成输出的 审核结果。
input: ModerationResults { model, results, type } or Error { code, message, type }
请求输入的审核结果。
ModerationResults object { model, results, type }
请求输入或生成输出的成功审核结果。
model: string
生成审核结果的审核模型。
results: array of object { categories, category_applied_input_types, category_scores, 3 more }
审核结果列表。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时，该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型，成功审核结果中固定为 moderation_result。
"moderation_result"
type: "moderation_results"
对象类型，固定为 moderation_results。
"moderation_results"
Error object { code, message, type }
尝试审核时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error"
对象类型，固定为 error。
"error"
output: ModerationResults { model, results, type } or Error { code, message, type }
生成输出的审核结果。
ModerationResults object { model, results, type }
请求输入或生成输出的成功审核结果。
model: string
生成审核结果的审核模型。
results: array of object { categories, category_applied_input_types, category_scores, 3 more }
审核结果列表。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时，该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型，成功审核结果中固定为 moderation_result。
"moderation_result"
type: "moderation_results"
对象类型，固定为 moderation_results。
"moderation_results"
Error object { code, message, type }
尝试审核时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error"
对象类型，固定为 error。
"error"
service_tier: optional "auto" or "default" or "flex" or 3 more or null (default: "auto")
指定处理请求所采用的服务类型。
- 设为 'auto' 时，按项目设置的服务层级处理请求。未另行配置时，项目使用 'default'。
- 设为 'default' 时，使用所选模型的标准价格和性能处理请求。
- 设为 'flex' 时，使用 Flex Processing 服务层级处理请求。
- 在请求级别启用快速模式，可在 Responses 或 Chat Completions 请求中传入
service_tier=fast或service_tier=priority。无论请求中使用哪一种值，响应均显示service_tier=priority。 - 未设置时，默认按 'auto' 处理。
设置 service_tier 后，响应体中的同名字段反映实际采用的处理模式，可能与请求参数的值不同。
"auto"
"default"
"flex"
"scale"
"priority"
"fast"
system_fingerprint: optional string
此指纹表示模型运行时的后端配置。
可结合请求的 seed 参数，判断后端变动是否可能影响输出的确定性。
usage: optional CompletionUsage
补全请求的用量统计。
completion_tokens: integer (default: 0)
生成补全中的词元数量。
prompt_tokens: integer (default: 0)
提示词中的词元数量。
total_tokens: integer (default: 0)
请求使用的词元总数，为提示词与补全之和。
completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, 2 more }
补全词元的用量明细。
accepted_prediction_tokens: optional integer (default: 0)
使用预测输出时，预测内容中 实际出现在补全中的词元数量。
audio_tokens: optional integer (default: 0)
模型生成的音频输入词元数量。
reasoning_tokens: optional integer (default: 0)
模型用于推理的词元数量。
rejected_prediction_tokens: optional integer (default: 0)
使用预测输出时，预测内容中 未出现在补全中的词元数量。与 推理词元一样，这些词元仍计入补全 词元总量，用于计费、输出和上下文窗口 限制的计算。
text_tokens: optional integer
模型生成的文本输出词元数量。
prompt_tokens_details: optional object { audio_tokens, cache_write_tokens, cached_tokens, 2 more }
提示词词元的用量明细。
audio_tokens: optional integer (default: 0)
提示词中的音频输入词元数量。
cache_write_tokens: optional integer (default: 0)
写入缓存的提示词词元原始数量。
cached_tokens: optional integer (default: 0)
提示词中命中缓存的词元数量。
image_tokens: optional integer
提示词中的图像输入词元数量。
text_tokens: optional integer
提示词中的文本输入词元数量。
示例
## 设置 OPENAI_API_KEY，并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/chat/completions/$COMPLETION_ID \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"metadata": {
"foo": "string"
}
}'200 响应示例
{
"id": "id",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"logprobs": {
"content": [
{
"token": "token",
"bytes": [
0
],
"logprob": 0,
"top_logprobs": [
{
"token": "token",
"bytes": [
0
],
"logprob": 0
}
]
}
],
"refusal": [
{
"token": "token",
"bytes": [
0
],
"logprob": 0,
"top_logprobs": [
{
"token": "token",
"bytes": [
0
],
"logprob": 0
}
]
}
]
},
"message": {
"content": "content",
"role": "assistant",
"annotations": [
{
"type": "url_citation",
"url_citation": {
"end_index": 0,
"start_index": 0,
"title": "title",
"url": "https://example.com"
}
}
],
"audio": {
"id": "id",
"data": "data",
"expires_at": 0,
"transcript": "transcript"
},
"function_call": {
"arguments": "arguments",
"name": "name"
},
"refusal": "refusal",
"tool_calls": [
{
"id": "id",
"function": {
"arguments": "arguments",
"name": "name"
},
"type": "function"
}
]
}
}
],
"created": 0,
"model": "model",
"object": "chat.completion",
"metadata": {
"foo": "string"
},
"moderation": {
"input": {
"model": "model",
"results": [
{
"categories": {
"foo": true
},
"category_applied_input_types": {
"foo": [
"text"
]
},
"category_scores": {
"foo": 0
},
"flagged": true,
"model": "model",
"type": "moderation_result"
}
],
"type": "moderation_results"
},
"output": {
"model": "model",
"results": [
{
"categories": {
"foo": true
},
"category_applied_input_types": {
"foo": [
"text"
]
},
"category_scores": {
"foo": 0
},
"flagged": true,
"model": "model",
"type": "moderation_result"
}
],
"type": "moderation_results"
}
},
"service_tier": "auto",
"system_fingerprint": "system_fingerprint",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"total_tokens": 0,
"completion_tokens_details": {
"accepted_prediction_tokens": 0,
"audio_tokens": 0,
"reasoning_tokens": 0,
"rejected_prediction_tokens": 0,
"text_tokens": 0
},
"prompt_tokens_details": {
"audio_tokens": 0,
"cache_write_tokens": 0,
"cached_tokens": 0,
"image_tokens": 0,
"text_tokens": 0
}
}
}示例
## 设置 OPENAI_API_KEY，并替换请求中的文件或聊天补全 ID。
curl -X POST https://api.openai.com/v1/chat/completions/chat_abc123 \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata": {"foo": "bar"}}'响应示例
{
"object": "chat.completion",
"id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
"model": "gpt-6-astra",
"created": 1738960610,
"request_id": "req_ded8ab984ec4bf840f37566c1011c417",
"tool_choice": null,
"usage": {
"total_tokens": 31,
"completion_tokens": 18,
"prompt_tokens": 13
},
"seed": 4944116822809979520,
"top_p": 1.0,
"temperature": 1.0,
"presence_penalty": 0.0,
"frequency_penalty": 0.0,
"system_fingerprint": "fp_50cad350e4",
"input_user": null,
"service_tier": "default",
"tools": null,
"metadata": {
"foo": "bar"
},
"choices": [
{
"index": 0,
"message": {
"content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.",
"role": "assistant",
"tool_calls": null,
"function_call": null
},
"finish_reason": "stop",
"logprobs": null
}
],
"response_format": null
}
更多建议：