OpenAI 列出聊天补全

列出聊天补全

get /chat/completions

列出已存储的聊天补全。仅返回创建时 将 store 参数设为 true 并已存储的聊天补全。

查询参数

• after: optional string

上一次分页请求中最后一个聊天补全的标识。

• limit: optional integer (default: 20)

要获取的聊天补全数量。

• metadata: optional Metadata or null

用于筛选聊天补全的元数据键列表，例如如下查询形式。

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

• model: optional string

生成聊天补全所使用的模型。

• order: optional "asc" or "desc" (default: "asc")

按时间戳对聊天补全排序。asc 为升序，desc 为降序，默认为 asc。

• "asc"

• "desc"

返回值

• data: array of ChatCompletion

聊天补全对象数组。

• 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

提示词中的文本输入词元数量。

• first_id: string or null

data 数组中第一个聊天补全的标识。

• has_more: boolean

表示是否还有更多聊天补全。

• last_id: string or null

data 数组中最后一个聊天补全的标识。

• object: "list" (default: "list")

对象类型，固定为 "list"。

• "list"

示例

## 设置 OPENAI_API_KEY，并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/chat/completions \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

{
  "data": [
    {
      "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
        }
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

示例

## 设置 OPENAI_API_KEY，并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

响应示例

{
  "object": "list",
  "data": [
    {
      "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": {},
      "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
    }
  ],
  "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
  "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
  "has_more": false
}